Operations CLI

The how-to is Operations CLI; this page is the contract scripts rely on. The exit codes, the error object and the stdout shape are stable across releases.

Commands¶

forze ops list      [--app REF] [--json]
forze ops describe  [--app REF] OP [--json]
forze ops call      [--app REF] OP
                    [--input JSON|@PATH|- | --FIELD VALUE ... | --batch @PATH|-]
                    [--tenant UUID] [--idempotency-key KEY]
                    [--timeout SECONDS] [--grace SECONDS]
                    [--correlation-id UUID] [--causation-id UUID]
                    [--api-key-file PATH] [--pretty]

OP is the operation key, dots included: orders.get. --app names the OpsApp as module:attribute, or a zero-argument callable returning one, and falls back to FORZE_OPS_APP. A group from build_ops_cli(app) has the declaration bound and no --app.

OP completes in the shell after describe and call once completion is installed with forze --install-completion. Completion loads the declaration from --app or FORZE_OPS_APP as list does, never builds the runtime, and offers nothing when the declaration cannot load. A group from build_ops_cli completes from its own declaration, installed by your root CLI's --install-completion. Every TAB imports the application module, so its import side effects run in the operator's shell.

list and describe never build the runtime. They write text, or JSON with --json. describe shows the title and description, the kind, the declared authn requirement and permissions, idempotency support, the deadline, the typed flags, the query surface, and the input and output JSON Schemas.

call options¶

A malformed --timeout, --grace, --tenant, --batch or id is a parse error: Click's usage text on stderr, exit 2, nothing on stdout. Every other refusal is an error object, an option call does not have included: it is read as a typed flag.

Typed flags¶

An operation whose input is flat scalars also takes that input as flags after OP, instead of --input:

$ forze ops call notes.create --title "Quarterly report"

• Spelling. A field's flag is its name with - for _. An alias never is.
• Validation. The flags build the object --input would carry, and it is validated the same way: each value is the string you typed, coerced by the DTO; an omitted flag takes the field's default; a missing required field or a bad value exits 4 and is never echoed.
• A value that looks like a flag. --title --pretty gives --pretty to call, and --title --draft is refused: the token after a flag that needs a value cannot start with --. Write --title=--pretty.
• On argv. Every value is on the command line, where ps and shell history show it. A secret field is refused; pass any other sensitive value with --input @PATH.
• All or none. An input takes no flags when one of its fields is anything else (a list, a model, a union), when it declares a SecretStr or SecretBytes field, or when a flag would be spelled like a call option (--timeout, --input, …) or like another field's. A call option means the same for every operation. describe lists the flags, or says why there are none.
• Exclusive. Typed flags and --input cannot be combined.

Batches¶

--batch @PATH or --batch - calls the operation once per line of a JSONL file, or of stdin, inside one runtime: one startup and one shutdown for the whole batch. Each line is an input object, as --input would carry; blank lines are skipped.

$ forze ops call notes.create --batch @notes.jsonl
{"line": 1, "result": {"id": "…", "title": "a", …}, "execution_id": "…", "correlation_id": "…"}
{"line": 2, "result": {"id": "…", "title": "b", …}, "execution_id": "…", "correlation_id": "…"}

• Validated first. Every line is read and validated before the runtime is built. A line that does not parse or validate is the only line written, and nothing runs. The whole input is held in memory, so split a file too large for that.
• One line out per call. Stdout holds one JSON document per line that ran, in order, each written as its call finishes: {"line": N, "result": …} or the error object with "line": N. Each carries its own execution_id; all share one correlation_id, the --correlation-id given or one minted for the batch. Each line is a governed call: its identity is verified and its tenant resolved again.
• Stops at the first failure. The failed line is the last one written, and its exit code, by the table below, is the batch's. Exit 0 means every line succeeded.
• No idempotency key. One key would claim every line, so --idempotency-key is refused. A retryable failure therefore exits 75 from a query and 69 from a command.
• Signals. A signal stops the batch: the line in flight gets --grace as a single call does, and no line starts after it. When lines remained, the batch exits 130 or 143.
• The batch as a whole. A refusal before any line runs (a conflicting option, an unreadable file, a runtime that does not start) is one error object without line.

Output¶

After the declaration loads, call writes exactly one JSON document to stdout, followed by a newline. For the duration of the call, file descriptor 1 points at stderr, so whatever the application logs or prints lands there.

The result is encoded with the operation's declared output type. An operation that returns nothing writes null.

The error object is the masked error envelope: a server-side error carries the generic detail, and a denial about a resource type a non-disclosing posture covers reads as not found.

{"error": {"code": "core.authentication", "kind": "authentication", "detail": "Invalid API key",
           "retryable": false, "context": {}},
 "execution_id": "…", "correlation_id": "…"}

execution_id and correlation_id are always present, whatever failed: they are minted before the first step that can fail.

An interrupt before any commit started writes the one kind the CLI adds: "code": "interrupted", "kind": "interrupted", a detail naming the signal, and "retryable": false, since an operation may have side effects outside its transaction.

Two failures write nothing to stdout:

Exit codes¶

The code is derived from the error envelope's kind, after the denial posture applies. Retryability is read from the kind's egress policy first.

69, 75 and 78 are EX_UNAVAILABLE, EX_TEMPFAIL and EX_CONFIG from sysexits.h. The retryable kinds are concurrency, throttled, infrastructure and unavailable.

Error codes the CLI adds¶

Environment¶