Selectors, output, and exit status
This page summarizes the stable CLI surfaces intended for automation. The compatibility contract is the authoritative v1 policy.
Job selectors
Commands that accept JOB resolve selectors in this order:
- a complete canonical UUIDv7 job ID;
- a unique ID prefix of at least eight characters; or
- an unambiguous exact display name.
Scripts should retain the complete ID printed by jobman run. Names and prefixes are conveniences for interactive use and can become ambiguous after more jobs are submitted.
Run selectors
Commands supporting a run selection accept a positive run number or negative index. -1 is the latest run, -2 is the preceding run, and so on. Run number zero is invalid.
Supported inspection forms include:
$ jobman show JOB
$ jobman show job JOB
$ jobman show run JOB -1
$ jobman logs --run -1 JOB
JSON envelope
Machine-readable inspection uses one object with a version and payload:
{
"schema_version": 1,
"data": {}
}
Existing fields do not change meaning or type in compatible v1 patch and minor releases. Minor releases may add fields, so consumers must ignore unknown fields. Human wording and column alignment are not stable interfaces.
Times use UTC RFC3339 with nanosecond precision when needed. IDs are opaque lowercase UUIDv7 strings.
Commands with JSON output include list --json, status --json, show --json, and doctor --json. config show emits effective configuration as JSON and can include origins.
Process exit status
| Status | Meaning |
|---|---|
0 | The command operation succeeded. |
1 | Internal or uncategorized failure. |
2 | Usage or validation failure. |
3 | No matching job or run. |
4 | Ambiguous selector. |
5 | Lifecycle or durable-state conflict. |
6 | Partial live-input delivery. |
The exit status of wait, run --wait, or run --foreground also reflects the managed lifecycle contract. Consult command help when distinguishing a Jobman operation error from a target job outcome.
Standard streams
Normal results go to stdout. Diagnostics go to stderr. Structured output is not mixed with progress decoration. Captured target logs are read explicitly with logs; detached targets do not inherit the submitting terminal’s output.
Redaction
Configured redaction applies to Jobman diagnostics and structured output. Captured target stdout and stderr remain raw. Secret references are persisted; resolved secret values are not included in the immutable job specification.