Verb Reference

add

enqueue a command; –key deduplicates active queued/running jobs

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Mutually exclusive: --after / --at

Traits: mutates, idempotent (when –key is supplied)

JSON data schema: {job_id: int, state: ‘queued’|‘running’, deduplicated: bool, next_run_at: float, priority: int, queue: str, cwd: str|null, env_keys: [str], idempotency?: {key, metadata_differs, metadata_differences}}

Example

spoolctl add --json --key run-1 -- true

brief

compact db-free usage brief for agent context injection

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {text: str, approx_tokens: int, budget_tokens: 700}

Example

spoolctl brief --json

cancel

cancel a queued job; –running also stops a running one (killed by its owning worker within a heartbeat)

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Safety: confirmation: --yes, requires: --running, --yes, refusal: SAFETY_BLOCK

Traits: mutates, destructive (only with –running)

JSON data schema: {job_id: int, state: ‘canceled’, was_running: bool}

Example

spoolctl cancel --json 1

capabilities

this machine-readable contract

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {attempt_states, contract_policy, contract_version, env, error_codes, events, exit_codes, failure_reasons, job_states, scheduling, verbs}

Example

spoolctl capabilities --json

config-show

show effective read-only project configuration and DB path source

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {config_path, config_exists, config_valid, values:{db_path}, sources:{db_path}, precedence, ignored_keys}

Example

spoolctl config-show --json

config-validate

validate project config JSON without opening the queue database

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {config_path, exists, valid, format, schema_version, recognized_keys, unknown_keys}

Example

spoolctl config-validate --json

doctor

check local spoolctl readiness without repairs or database mutation

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {ready, summary:{passed,warnings,failed,skipped}, config, checks:[{id,status,message,remediation,blocked_by}], versions}

Example

spoolctl doctor --json

events

read the durable event ledger; verify job ids with spoolctl show; –follow –json emits NDJSON data frames plus end/error control frames

Flags

Output modes: envelope, frames, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Mutually exclusive: --wait / --follow

Mutually exclusive: --limit / --follow

Mutually exclusive: --max-events / --wait

Mutually exclusive: --idle-timeout / --wait

Traits: idempotent

JSON data schema: {count: int, events: [{id, job_id, at, event, worker_id, detail}]}; meta.pagination:{cursor, first_id}; –wait also adds meta.wait:{reason, waited_ms}

Example

spoolctl events --json --limit 10

feedback

one-call verdict on a job: terminal, succeeded, why it failed, output tails, and the next command to run

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {job_id, state, terminal: bool, succeeded: bool|null, exit_code, failure_reason, last_error, attempts, attempts_total, latest_attempt_no, duration_seconds, remediation, streams:{stdout,stderr}: {tail, size_bytes, truncated, missing, path}}

Example

spoolctl feedback --json 1

list

enumerate jobs, newest first, optionally filtered by state/tag/queue/priority

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {count: int, jobs: [{id, argv, state, attempts, crashes, max_retries, timeout_seconds, created_at, started_at, finished_at, next_run_at, priority, queue, cwd, last_exit_code, last_error, idempotency_key, tags, note}]}

Example

spoolctl list --json --limit 10

output

captured stdout/stderr for any attempt of a job

Positionals

Flags

Output modes: envelope, raw, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {attempt_no, attempt_state, attempts_total, job_id, streams: {stdout|stderr: {path, preview, preview_truncated, size_bytes}}} or {attempts: []}

Example

spoolctl output --json 1 --stream stdout

prune

delete terminal jobs older than a duration, files first then rows; requires –yes unless –dry-run reports without deleting

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Mutually exclusive: --yes / --dry-run

Safety: confirmation: --yes, dry run: --dry-run, refusal: SAFETY_BLOCK

Traits: mutates, destructive

JSON data schema: {matched: int, deleted_jobs: int, deleted_attempts: int, deleted_events: int, freed_bytes: int, dry_run: bool, actual: bool, irreversible?: bool}

Example

spoolctl prune --json --older-than 30d --dry-run

retry

requeue a dead or failed job with a fresh retry budget

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Safety: force: --force, force required for: running_job, refusal: SAFETY_BLOCK

Traits: mutates, destructive (only with –force on running jobs)

JSON data schema: {job_id: int, state: ‘queued’}

Example

spoolctl retry --json 1

robot-docs

agent workflow guide; currently supports the guide subcommand

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {text: str, approx_tokens: int, sections: [{title, bullets}]}

Example

spoolctl robot-docs guide --json

schema

export JSON Schemas for the envelope, verb data payloads, and streams

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {dialect: str, envelope_schema: object, verbs: {: schema}, streams: {events_follow: schema}}

Example

spoolctl schema --json

show

one job in full detail: row, attempts, event trail

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {job: {id, argv, state, attempts, max_retries, timeout_seconds, created_at, started_at, finished_at, next_run_at, priority, queue, cwd, env, crashes, max_crashes, locked_by, locked_pid, locked_at, heartbeat_at, last_exit_code, last_error, last_failure_reason, idempotency_key, tags, note}, attempts: [{attempt_no, state, worker_id, worker_pid, started_at, finished_at, exit_code, error, failure_reason, stdout_path, stderr_path}], events: [{at, event, worker_id, detail}]}

Example

spoolctl show --json 1

status

queue counts, scheduled sub-counts, per-lane counts, and recent dead jobs; always exit 0

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {counts: {canceled,dead,done,failed,queued,running}, scheduled: int, queues: {: {counts, scheduled}}, recent_dead: [{id, command, attempts, crashes, last_error, finished_at, stdout_path, stderr_path}]}

Example

spoolctl status --json

wait

block until every given job settles (done/dead/canceled); exit 0 all done, exit 6 any failed (envelope stays ok:true)

Positionals

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Traits: idempotent

JSON data schema: {all_succeeded: bool, jobs: {‘’: {state, attempts, last_exit_code, last_error}}}

Example

spoolctl wait --json 1

work

run jobs until stopped; –once runs at most one; –drain runs until the queue settles; –queue serves one lane; –slots optionally bounds running jobs in that lane

Flags

Output modes: envelope, text

Exit codes: 0, 1, 2, 3, 4, 5, 6

Mutually exclusive: --once / --drain

Traits: mutates

JSON data schema: –once: {claimed: bool, job_id?, attempt_no?, result?, job_state?}; –drain: {drained: bool, executed: int}; loop mode writes nothing to stdout; claimed:false means no job runnable by this worker right now, including a full slot ceiling

Example

spoolctl work --json --once