CLI reference: sparkwing runs

CLI reference: sparkwing runs

Every sparkwing runs command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in cli-reference.md.

sparkwing runs

Inspect and control pipeline runs

Subcommands

• annotations -- Read or append persistent job + step annotations
• approvals -- List approval gates (pending and history)
• cancel -- Request cancellation of in-flight runs
• grep -- Search run log text
• list -- List recent pipeline runs
• logs -- Print a run's logs
• prune -- Delete finished runs older than a threshold, or by id
• retry -- Trigger fresh runs copying pipeline + args from old ones
• stats -- Report run counts, success rate, and duration percentiles
• status -- Read one run's status, attempts, notices and selected view

Flags

sparkwing runs annotations

Read or append persistent job + step annotations

Subcommands

• add -- Append an annotation to a job or step
• list -- List annotations on a run

Flags

sparkwing runs annotations add

Append an annotation to a job or step

Plain emits run/job[/step]. JSON retains the controller replay result.

Flags

sparkwing runs annotations list

List annotations on a run

JSON emits job_id, optional step_id, level, message and source location per annotation. Plain emits one message per line, with line breaks replaced by spaces.

Flags

sparkwing runs approvals

List approval gates (pending and history)

Subcommands

• approve -- Approve a pending approval-gate job
• deny -- Deny a pending approval-gate job
• list -- List pending approvals (or one run's history)

Flags

sparkwing runs approvals approve

Approve a pending approval-gate job

The controller derives the approver from authentication. Plain emits run/job. JSON includes the approval and replay result.

Flags

sparkwing runs approvals deny

Deny a pending approval-gate job

The controller derives the approver from authentication. Plain emits run/job. JSON includes the approval and replay result.

Flags

sparkwing runs approvals list

List pending approvals (or one run's history)

Without --run, list pending approvals. With --run, include resolved history. Plain emits run/job.

Flags

sparkwing runs cancel

Request cancellation of in-flight runs

Flags

sparkwing runs grep

Search run log text

Search controller logs across matching runs. Filters apply before the run page limit. --max-matches limits matches per log subject, with zero meaning uncapped.

JSON emits matching records and a page record with next_cursor and truncated. Quiet JSON emits run_id records and sends continuation metadata to stderr. Plain emits matching lines, or run IDs with --quiet.

Flags

sparkwing runs list

List recent pipeline runs

Read runs through the selected controller. Filters apply before pagination. Runs are ordered by descending team number. --since accepts days and weeks, such as 7d or 2w.

JSON emits compact run records and a page record with next_cursor and truncated. Quiet JSON emits id records and sends continuation metadata to stderr. Plain emits run IDs.

--by-pipeline totals every matching page and retains the newest --sparkline statuses. --group-by run|job|step requires --status failed and groups the selected page.

--wait blocks until a matching run appears. --follow reads every newer matching run between polls. Grouped follow output describes each new batch. Interrupted or timed-out waits exit 3. A refused read (not found, unauthenticated or forbidden) exits 4, which retrying cannot change.

Flags

sparkwing runs logs

Print a run's logs

Read job-attempt and trigger, plan or eval logs through the controller. --job selects a job. --tree includes descendants. --events-only and --no-events select lifecycle events or output.

Every read consumes all available pages. Without --follow, a snapshot with pending final log segments reports logs incomplete and exits 3. --follow waits for new records until final log segments are complete. An interrupted observation exits 3. A run that does not exist or that the credential cannot read exits 4; stop polling on 4.

JSON emits tagged log records. Plain emits log lines. Use --grep without --run to search across runs with the same filters and pagination as runs grep.

Flags

sparkwing runs prune

Delete finished runs older than a threshold, or by id

Select --run, including --run - for IDs on stdin, or --older-than. Age selection reads every page and includes only terminal runs started before the cutoff. A failed selection deletes nothing.

--dry-run prints the selected IDs without deleting. The controller enforces retention pins. JSON reports the selected run and any structured failure. Plain emits acknowledged run IDs.

Flags

sparkwing runs retry

Trigger fresh runs copying pipeline + args from old ones

Select --failed to reuse successful jobs or --all-jobs to execute the sealed plan again. Retry preserves the source request, plan, source trust and actor. The controller records the retrier separately.

Repeat --run or use --run - for newline-separated IDs on stdin. JSON emits one safe receipt or structured failure per source run. Plain emits new run IDs. Local and remote retries use the same controller API.

Flags

sparkwing runs stats

Report run counts, success rate, and duration percentiles

Read every matching root-run page through the selected controller. --since accepts days and weeks. JSON emits pipeline counts, success percentage, mean duration and nearest-rank P50 and P95. Plain emits pipeline names.

--sizing reads controller measurements, job rows, source, drift, memo exclusions and demand floors. --reset selects one --pipeline or --all-pipelines --yes and preserves resource pins. --since applies to run statistics only.

Sizing reset requires an authorized controller route. Until that contract exists the adapter returns policy_missing without changing state.

Flags

sparkwing runs status

Read one run's status, attempts, notices and selected view

Read the same public run detail through a controller profile or the local controller. Numeric run selectors are per-team numbers.

Views: summary, timeline, receipt, errors, tree. Summary includes recorded failing steps and errors for failed jobs. --steps includes all recorded steps. Receipts retain the controller's hashes and settled cost.

--follow streams observations until the run ends. Exit 0 means success or a completed dry run, 1 means a failed or cancelled run, 2 means invalid usage, 3 means the observation is incomplete and may be retried, and 4 means the run does not exist or the credential cannot read it, so polling again will not help. --exit-zero suppresses terminal failure only.

Cloud awards awaiting activation show "Waiting for dedicated Cloud capacity" with elapsed time. Missing shared pool configuration for the requested hardware class ends the unit as cloud_capacity_unconfigured, releases its credit hold, and gives support@sparkwing.dev a run reference. A closed Cloud budget breaker ends a unit that needs a fresh node as cloud_capacity_unavailable the same way. JSON preserves run details and notices: one document per observation, so --follow and the errors view (one record per failed job) are NDJSON. The exit code carries the outcome, and no error document follows the observation. Plain summary prints the run status, every job's status and outcome, and failure details. Errors prints failed job IDs, tree prints run IDs, and receipt prints the receipt hash. --steps adds recorded steps to summary and tree output.

Flags