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.

belld revision confirm accepts --edits JSON to override detected descriptor fields before confirming. Accepted top-level fields are build_plan, runtime, entrypoint and ports; the API validates their values. Without --edits the detected descriptor is confirmed as-is.

belld revision confirm rev_REPLACE --product prod_REPLACE --edits '{"ports":[{"port":8080,"protocol":"http"}]}'

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. Service 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.

When using local credentials obtained through belld login with a refresh token stored on disk, the internal polling in belld evaluate automatically renews the access token on HTTP 401 and retries the request once. External tokens supplied through BELLD_TOKEN or --token have no refresh token, so HTTP 401 still ends the command with exit code 3. Exit 3 is not an evaluation failure: the pipeline run continues on the platform, so use belld pipeline-run get pipe_REPLACE --json repeatedly until the run reaches a terminal state. If an external token has expired, obtain a fresh token and update BELLD_TOKEN or --token, or remove the external token and run belld login to use local refresh credentials.

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.

When a write fails in human-readable mode, the CLI prints the key it used on stderr as idempotency-key KEY; rerun the same command with --idempotency-key KEY to replay it without creating a duplicate. JSON mode output is unchanged; pass --idempotency-key yourself if you need to replay.

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.

belld binding create requires --capability-scope JSON as one structured JSON argument. Its id must match --capability; the Broker validates the capability-specific shape before creating a new binding. Missing or malformed JSON is a local usage error (exit 2) and sends no HTTP requests. For example:

belld binding create --credential cred_REPLACE --capability ai.generate --actions generate --scope model-a --expires-at 2030-01-01T00:00:00Z --capability-scope '{"id":"ai.generate","scope":{"models":["text"],"max_tokens_per_call":1000},"provider_models":{"text":"model-a"}}'

Add --app app_ID to limit the binding to one App in the same workspace; the App must be active. Without --app the binding is shared across the workspace. Once an App has its own active or blocked binding for a capability and environment, its services use only the App's bindings and no longer fall back to shared ones.

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.