CLI reference
Every ciresk ci command with its flags, its human output, its --json data and its exit code.
Every command is ciresk ci <command>; ciresk ci --help is the CLI's own help. Human output is a fixed layout per command; --json is the contract.
Global flags and environment
| Flag | Meaning |
|---|---|
--json | Exactly one JSON document on stdout (see the envelope); progress still goes to stderr unless --quiet. |
--region <eu|us> | The region whose cell to call; the default comes from the token, then eu. Only eu is live today. |
--api-url <url> | The API origin; overrides the region, CIRESK_CI_API_URL and the config file. The default is https://ci.eu.ciresk.com. |
--org <slug> | The organization whose stored token to use; the default is org: in .ciresk/ci.yaml, then the only stored one. |
--timeout <dur> | Network timeout per request, default 30s. |
--quiet | No stderr progress. |
-y, --yes | Skip confirmations. |
--color <when> | auto (a tty without NO_COLOR), always or never; default auto. |
--format <text|github> | github makes a command that prints a job summary (run --wait, check, test, build, lint, wait, summary) report to a GitHub Actions step: failing-test annotations, the job summary and step outputs. See GitHub Actions. Not with --json. |
--pass-token | Keeps CIRESK_TOKEN and CIRESK_CI_TOKEN in the environment for CI and containers; without it the token comes from the OS keychain. |
| Variable | Meaning |
|---|---|
CIRESK_TOKEN, CIRESK_CI_TOKEN | A csk_ key or an exchanged cix_ token, for machines and sandboxes. The OS keychain (from auth login) is read first. Never printed. ciresk ci drops both from the environment unless --pass-token is given. |
CIRESK_CI_API_URL, CIRESK_API_URL | The API origin, below --api-url and above ciresk ci config set server <url>. |
CIRESK_JOB | The default for every [job] argument. run without --wait prints export CIRESK_JOB=job_... on stderr. |
CIRESK_ACTOR | Overrides the detected actor (user, agent:claude-code, agent:codex, ...). |
CIRESK_SESSION | Attributes a session to the job. |
NO_COLOR | Disables color, as do a non-tty stdout and --json. |
Commands
| Command | Synopsis | Flags | Human output | --json data | Exit |
|---|---|---|---|---|---|
run | ciresk ci run <kind> [targets...] | -p <name>, --full, --wait, --follow, --max-wait <dur> (default 30m), --cancel-on-interrupt, --fail-fast, --no-fail-fast, --no-dedup, --actor <id>, --budget <units>, --label k=v, --idempotency-key <key>, --dry-run, --no-index, --no-watch, --no-warnings | The job: state, id, kind@branch, targets, trust, queue position; the summary when --wait | Job; with --wait Summary; with --dry-run Plan | 0 queued (no --wait); otherwise mirrors the job |
check, test, build, lint | ciresk ci check [targets...] | Same as run | Aliases for run <kind> --wait | Summary | Mirrors the job |
status | ciresk ci status [job] | --watch | State, targets, trust, cost so far, task table | Job | 0 if the job exists, regardless of state |
wait | ciresk ci wait [job] | --max-wait <dur> (default 30m), --follow, --cancel-on-interrupt, --no-warnings | Summary on completion | Summary | Mirrors the job; 7 when --max-wait elapses |
logs | ciresk ci logs [job] | --task <name>, --shard <k>, --all-shards, --all (failed tasks only by default), --tail <n> (default 200), --grep <re>, -C <n> (default 3), --range <off>:<len>, --from <line>, --lines <n>, --follow, --raw | The slice, then next | LogSlice | 0; 2 to 8 when the request fails |
tests | ciresk ci tests [job] | --all (failing only by default), --task <name>, --shard <k>, --limit <n> (default 50), --cursor <c>, --junit <path> | One line per test: status, name, file:line, first message line | {tests, total, failed_total, next_cursor} | 0 |
warnings | ciresk ci warnings [job] | --task <name>, --kind <kind>, --limit <n> (default 50), --cursor <c> | Counts by kind, then one line per warning | Warnings | 0 |
artifacts | ciresk ci artifacts [job] | --download <name>, --out <dir> (default .ciresk/<job>) | Name, task, size, expiry | {artifacts, downloaded} | 0 |
cancel | ciresk ci cancel [job] | --reason <text> | New state | {id, state, cancelled} | 0 when cancelled or already terminal |
approve | ciresk ci approve [job] --task <name> | --reject, --comment <text> | What was decided | {job, decision, tasks, sod_exception} | 0 decided; 4 not a person, not an approver, signed in over 10 minutes ago, or the job's requester |
approvals | ciresk ci approvals | --job <job> | The gates waiting for a person, each with its approve line | {approvals} | 0 |
summary | ciresk ci summary [job] | --tail <n> (default 50), --detailed, --no-warnings | One screen: verdict, failing tests, tail of the first failed task, next | Summary | Mirrors the job |
jobs | ciresk ci jobs | --repo <id>, --ref <ref>, --state <state>, --actor <id>, --limit <n> (default 20), --cursor <c> | One row per job: id, kind@branch, state, duration, cost, actor | Jobs | 0 |
budget | ciresk ci budget | Session and day spend, limits, resets, policy flags | {budget, policy, principal, actor} | 0 | |
affected | ciresk ci affected [--kind <kind>] | --strategy <s> | Not available yet: the cell answers 501 not_implemented | Affected | 8 |
watch | ciresk ci watch | --once | Index and upload progress; with --once, one refresh then exit | Watch | 0 |
init | ciresk ci init | --force, --stack <name> | Writes .ciresk/ci.yaml for the detected toolchain | Init | 0; 2 when a manifest exists and neither --force nor --yes is given |
doctor | ciresk ci doctor | --rehash | Token, API, tree, manifest, repository, index: one line each, with the fix when one fails | Doctor | 0; otherwise the exit code of the first failing check |
auth | ciresk ci auth login|status|logout | login --token csk_..., login --no-browser | Never prints tokens | Auth (logged_in, region, org, ...) | 0 or 3 |
config | ciresk ci config set server <url>, config set region <eu|us>, config show | The stored setting | Config | 0 | |
workers enrol | ciresk ci workers enrol | --name <host>, --expires-in <dur>, --factory <id> | The cwe_ secret (shown once) and the exact join line | {factory_id, secret, expires_at, join} | 0; 4 without ci:workers.admin |
workers add | ciresk ci workers add | --name, --slots, --labels, --idle-stop, --secrets, --docker, --image, --wait | Installs, enrols and starts this Linux host as a worker; with --docker a docker run line and a compose snippet | WorkersAdd | 0; 4 without ci:workers.admin |
workers list | ciresk ci workers list | --limit <n>, --cursor <c> | State, version, free slots, last heartbeat per worker | {workers, next_cursor} | 0 |
workers remove | ciresk ci workers remove <name|id> | --no-drain, --wait <dur>, --keep-install | Drains, deregisters and, on its own host, uninstalls a worker | WorkersRemove | 0; 4 without ci:workers.admin |
repos | ciresk ci repos list|get|delete | delete needs --yes off a terminal | Repositories, one repository, or what a delete removed | ReposList, Repo, RepoDelete | 0; 4 without ci:repos.admin for delete |
policy | ciresk ci policy get|set | --repo <id|.> | Every policy field with its value and source | Policy, PolicySet | 0; 2 for an unknown field or a wrong type |
hook | ciresk ci hook pretooluse | Reads a Claude Code hook document on stdin and answers it | Hook output | 0 | |
version | ciresk ci version | The CLI version, and the server's when a token is at hand | {version, protocol_version, schema_version, server, api_url, compatible} | 0 | |
update | ciresk ci update | --version <tag>, --check | Updates the CI plugin through ciresk update when it can, otherwise downloads, verifies and swaps itself; old -> new | Update | 0; 2 when the release is not published for the platform; 8 when the host cannot be reached or a verification fails |
Examples:
ciresk ci check # the check task on the working tree, wait, summary
ciresk ci test -p platform-api --json | jq .data.failing_tests
ciresk ci run build --full --wait # exit 4 unless policy allows and the token has ci:jobs.run_full
ciresk ci run test --actor agent:claude-code:$CLAUDE_CODE_SESSION_ID --budget 200
export CIRESK_JOB=$(ciresk ci run test --json | jq -r .data.id); ciresk ci wait; ciresk ci logs --grep 'panicked' -C 5
ciresk ci logs job_01a158... --task test --range 0:65536 --raw > test.logThe JSON envelope
Every --json output is {schema_version: 1, command: string, request_id: string|null, data: <type>, budget: Budget|null, next: string|null, truncated: bool}. Errors use the same envelope with error: Problem (the API's application/problem+json fields, see API errors) instead of data. schema_version increments only on an incompatible change; additive fields do not bump it, and clients must ignore unknown fields.
| Type | Fields |
|---|---|
Job | id (job_), repo, repo_id (repo_), base_ref, base_digest (commit sha), diff_digest, kind, targets, full, trust, priority, state, deduplicated, principal, actor, client, session, created_at, started_at, finished_at, duration_ms, cost_units, exit_code, url, tasks |
Task | name, shard (k/N), state, exit_code, started_at, finished_at, duration_ms, cost_units, worker_id, cache (hit, miss, write, none), log_bytes, has_junit, artifact_count |
Summary | job (without tasks), tasks, verdict (succeeded, failed, cancelled, timed_out, infra_error, running), failing_tests (max 20), failing_tests_total, first_failed_task, first_failure, warnings, tail, tail_task, critical_path, cache ({hits, misses, writes}), next |
TestResult | name, file, line, status (passed, failed, skipped, flaky), duration_ms, message (first 5 lines), stdout_tail (only with --detailed), task, shard |
LogSlice | job_id, task, byte_offset, byte_length, total_bytes, next_byte_offset, truncated, failed_only, lines, text, hint |
Artifact | name, task, size_bytes, media_type, digest, url (presigned), expires_at |
Budget | session: Spend, day: Spend, concurrent: {used, limit}, resets_at, rate_table, month (when a monthly budget is set) |
Spend | spent_units, limit_units, remaining_units, jobs, jobs_limit |
Policy | allow_full_build, default_kind, max_concurrent_per_actor, trust, untrusted_refs |
Principal | kind (user, api_key, service), org_id, jurisdiction, credential (prefix only, csk_live_eu_abcd), scopes |
Affected | base_ref, diff_digest, kind, strategy, changed_files, targets, escalated, escalation_reason, estimated_cost_units |
Ids are short and prefixed; human output shows kind@branch next to the id so a model does not carry UUIDs. All field names are snake_case; changes are additive only.
Size bounds
- Human output of any command is at most 120 lines;
summaryaims at 2,000 tokens with a hard cap of 8,000, enforced by trimmingfailing_teststo 20,tailto its line limit andmessageto 5 lines, then halvingtailuntil it fits. logsreturns at most 256 KiB per call; the default is the last 200 lines.- Every trimmed result says so in band:
truncated: truein JSON and a final line[truncated: 118 of 640 lines; next: ciresk ci logs ... --range 65536:65536]in human output. - The
nexthint is the last line of human output and thenextfield in JSON: the exact command to run for the obvious drill-down. --helpis written for agents: examples first, then flags, then exit codes, under 60 lines per command.
Exit codes
Every exit code, what it is mapped from and what to do next is in Exit codes. A failed job never exits 0.