cli

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package cli is a command line client for the admin JSON API (github.com/ubgo/workflow/admin): list and inspect runs, retry, cancel and delete them one at a time or by filter, pause and resume, list and trigger schedules, watch a queue drain and read run-end history.

It talks HTTP only. It imports nothing beyond the standard library (not even the workflow core), so installing it pulls no driver, SDK or database code, and it works against an app in any language that serves the same API. A test (TestGuard_StdlibOnly) fails if that changes.

Connecting

The API is closed by default and authenticated by the app, so the CLI sends whatever the app's Identify accepts:

--url URL        where the app mounted admin.NewHandler; env WORKFLOW_ADMIN_URL
--token T        sent as "Authorization: Bearer T"; env WORKFLOW_ADMIN_TOKEN
--header 'K: V'  any header, repeatable (a session cookie, a tenant header); env WORKFLOW_ADMIN_HEADER holds one

The token is never printed, not even in an error.

Commands

caps                         operations the server's driver supports
runs|failures|discarded      list runs; --workflow --queue --status --label k=v --tenant --from --to --limit --cursor --count
inspect RUN                  one run, its attempt errors and, with --output, captured output
retry RUN | retry --all      retry one failed run, or every failed run a filter matches
cancel RUN | cancel --all    cancel one run, or every run a filter matches
delete RUN | delete --all    forget one finished run, or every finished run a filter matches
reschedule RUN --at T        move a delayed run that has not started
cancel-step RUN STEP         withdraw one step of a run
pause|resume                 --workflow W | --queue Q | --everything
pauses                       the active pauses
queues                       depth and oldest wait per queue
schedules | schedule ID      list schedules, or show one
trigger SCHEDULE             run a schedule now
drain                        wait until no run is queued or running (--queue, --wait, --interval)
metrics                      run ends per step by status (--window, --step, --workflow)
health                       live, ready and each check; exit 1 when not ready
nodes                        the nodes that are online

Every destructive command takes --dry-run, which reads what it would touch and changes nothing; --all on retry, cancel and delete asks the server to preview with the same filter. Every command takes --json, which prints the API's own JSON answer instead of a table. The exit code is 0 on success, 1 when the API refused or failed (or drain timed out), and 2 on a usage error.

Embedding

Run is the whole CLI as a function, so an app can ship it as a subcommand of its own binary (with its own default URL and auth), and cmd/workflow is the stand-alone binary.

Index

Constants

View Source
const (
	// EnvURL is the admin API's mount point, the default of --url.
	EnvURL = "WORKFLOW_ADMIN_URL"
	// EnvToken is a bearer token, the default of --token.
	EnvToken = "WORKFLOW_ADMIN_TOKEN"
	// EnvHeader is one extra header, "Name: value", added before any
	// --header flag.
	EnvHeader = "WORKFLOW_ADMIN_HEADER"
)

The environment variables Run reads through Options.Getenv.

View Source
const (
	ExitOK    = 0 // the command did what it was asked
	ExitError = 1 // the API refused or failed, or drain timed out
	ExitUsage = 2 // the command line is wrong
)

The exit codes Run returns.

View Source
const DefaultTimeout = 30 * time.Second

DefaultTimeout bounds one HTTP request when Options.HTTPClient is nil.

Variables

This section is empty.

Functions

func Main

func Main()

Main is the stand-alone binary's body: Run over the process's arguments, standard streams and environment, cancelled by an interrupt, then exit with its code.

func Run

func Run(ctx context.Context, args []string, opts Options) int

Run runs the CLI with args (without the program name) and returns the exit code: ExitOK, ExitError or ExitUsage.

Types

type APIError

type APIError struct {
	Status  int
	Code    string
	Message string
}

APIError is an error answer from the admin API: its HTTP status and the code and message from its {"error":{...}} body.

func (*APIError) Error

func (e *APIError) Error() string

type Options

type Options struct {
	// Stdout gets results; Stderr gets errors and usage. Nil discards.
	Stdout, Stderr io.Writer
	// Getenv reads EnvURL, EnvToken and EnvHeader; nil reads nothing (an
	// embedding app passes os.Getenv, or its own lookup).
	Getenv func(string) string
	// HTTPClient sends the requests; nil is a client with DefaultTimeout.
	HTTPClient *http.Client
	// Now and Sleep drive drain's polling; nil means the wall clock.
	// Sleep returns early with ctx's error when ctx ends.
	Now   func() time.Time
	Sleep func(ctx context.Context, d time.Duration) error
	// Name is the program name in usage text; empty means "workflow".
	Name string
}

Options are what Run takes from the process around it, so an app can embed the CLI and a test can drive it without a real terminal, network or clock.

Directories

Path Synopsis
cmd
workflow command
Command workflow is the command line client for the workflow admin API; see package github.com/ubgo/workflow/cli.
Command workflow is the command line client for the workflow admin API; see package github.com/ubgo/workflow/cli.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL