CLI behavior

Options and output

--json, --verbose and --force are booleans. Other options take a value. The generated CLI reference lists the options accepted by each command and the seven globals. --force is local to init. Unknown options or missing positional arguments are usage errors.

--json preserves the API object, with centralized secret redaction. Human errors go to stderr; JSON problems go to stdout. Inspect business state even after exit 0.

Exit codes

0: HTTP operation succeeded. 1: general error, 429, 5xx, or timeout. 2: usage or option error. 3: unauthenticated or missing credentials. 4: not found. 5: forbidden.

Polling and retries

The default deadline is 600 seconds. Backoff is 0.2, 0.4, 0.8, 1.6, then 2 seconds, including HTTP wait in the deadline. Product creation polls source freeze. Evaluation stops at qualification qualified or stopped, or pipeline completed, passed, warning, blocked, failed, or unsafe. Check qualification before releasing.

Descriptor confirmation and evaluation retry admission not_found within the deadline with the same Idempotency-Key. After evaluation is accepted, polling uses pipeline GET. Other POST operations do not retry automatically. Deployment, Surface, and pipeline-run GET commands read once.

Each invocation normally uses a fresh key; --idempotency-key KEY supports deliberate replay of the same operation across calls. Keys are 1–256 printable non-space ASCII characters.

Credentials and pagination

Use login or BELLD_TOKEN; a flag token overrides the environment. Do not put provider secrets in arguments. Credential creation accepts stdin or --from-env NAME. CLI output redacts secrets; never assume an arbitrary external log is safe to publish.

List cursors are opaque. Pass --limit (1–200), --cursor, and --order asc or desc only where the command table allows them. Budget list has no pagination options.