cli reference

Source snapshot, not a live availability guarantee. Use the client and release supplied during onboarding. Contributor build instructions below refer to the source workspace; they are not a public package installer. Version notes.

Generated from the operation catalogue. Every command accepts --json and then prints exactly one JSON document on stdout, the operation’s response document; without it the command prints text for a person. Diagnostics go to stderr.

authentication

• cargo sorus login runs the device flow: a person confirms the printed code on the approval page inside a signed-in session.
• SORUS_TOKEN holds a tenant credential (a device token or an agent credential) and authenticates every command without a device flow.
• SORUS_CREDENTIAL_FILE names a file whose content is the credential, or a JSON credential file the CLI stored; it takes effect when SORUS_TOKEN is unset.
• SORUS_ENDPOINT selects the API origin; the default is https://app.lathe.run.

exit codes

A followed job’s terminal state decides between 0, 1 and 5 by its failure code and cancellation source, never by the status label alone:

A cancellation source of user is the customer’s request, adapter is the customer’s GitHub workflow cancelled upstream, and wall_clock_ceiling is the ceiling the job recorded at admission: the platform default of 21600 seconds or a lower repository override, visible before execution. A job that is not terminal when the follow ends, after a lost stream or a failed read, exits 4. A job status read that meets a transport failure or HTTP 408, 429 or 5xx while following, or while reading the job for a --json document after the follow, is read again, at most 3 attempts in all, 1 s and then 2 s apart, each within 60 s; stderr names each retry with its attempt number, and only the last attempt’s failure is a failed read. After an interrupt has detached the follow, the document read makes one attempt. A succeeded job whose output or requested artifacts cannot be delivered exits 4, or 3 when the delivery is refused for authentication. On a terminal failure stderr names the class, the failure code and the next step.

Under --json, test, check and build print one document on every exit path, with job, principal, tenant, repository, submission_key, toolchain, toolchain_origin, status, failure (origin, code, detail), cancellation_source, stage, refusal and exit_code, which equals the process exit status. A command that ends before a job is admitted prints job, status and failure as null, the stage it ended at (arguments, authenticate, prepare or deliver) and the platform’s typed refusal (status, code, detail) when it gave one. After a follow, status, failure and cancellation_source are null when the read after the follow fails on every attempt, is interrupted or carries another tenant’s job; toolchain and toolchain_origin come from that read when the read right after admission failed or carried another tenant’s job; neither changes the exit. status <job> --json prints one document after the follow on every exit path, with the whole job and exit_code; job is null when the read after the follow fails on every attempt, is interrupted or carries another tenant’s job, which never changes the exit.

Before 5 and 130 existed, a platform-caused terminal job exited 1 and an interrupt exited 4. A caller that tests only for a nonzero exit is unaffected. A caller that retried on 1 retries on 5; a caller that falls back on 4 falls back on 5 as well once a job was admitted. failure.code in the JSON document is unchanged.

commands

Cargo commands capture the complete selected source and upload bounded chunks before submitting a source reference. The API must advertise compatible streamed execution; the CLI refuses an unavailable capability before source upload. Limits are 1 GiB of regular-file bytes, 250000 entries and 32 MiB of metadata, separate from the 4 MiB chunk size. Deployment support still requires qualified management, host and guest artifacts. When the server’s source transfer limit answers a chunk check, chunk upload or completion with HTTP 429, the CLI prints a source transfer limited line on stderr, waits the window the answer names (1 to 60 seconds) and repeats the same request under the same upload and submission key, for at most 300 seconds of waiting per upload; after that it exits 4 and the same --submission-key resumes the upload.

Each command prints its submission key and retains a private recovery record under $XDG_STATE_HOME/sorus/submissions or $HOME/.local/state/sorus/submissions, outside the repository. Repeat the original Cargo invocation with --submission-key <key> to resume the captured input after interruption, including after working-tree edits. A changed endpoint, tenant, invocation directory or Cargo options conflicts. The local source copy is removed only after the job acknowledgement is durably recorded; the request and job receipt remain for recovery. An unadmitted upload that expires still refuses admission, preserves the original local archive and never silently captures changed files or submits a new job. Credentials are not stored in these records.

Generated commands take path parameters as positional arguments in path order, then query parameters and body members as --name value flags (--name alone for a boolean, repeated for a list). A keyed mutation takes --idempotency-key <key>; without it the CLI generates one and prints it on stderr.

Operations without a command:

• device.pending: the approval page is a human surface inside a signed-in session
• device.approve: device approval is a human act inside a signed-in session
• events.stream: the dashboard hint stream is a browser session surface; the CLI reads the tenant event stream
• jobs.submit_diff: a retained predecessor route; the CLI submits captured Cargo workspaces
• jobs.submit_diff_v2: a retained predecessor route; the CLI submits captured Cargo workspaces
• jobs.submit_diff_keyed: a retained predecessor route; the CLI submits captured Cargo workspaces

credential management

• cargo sorus credential create <name> --scope <scope>... --expires <duration> mints an agent credential and prints its value once; <duration> is a count with a unit (30d, 12h, 45m). --requests-per-minute <n> sets its limit.
• cargo sorus credential list lists the tenant’s credentials without their values.
• cargo sorus credential revoke <name> revokes one; its next use is refused.