CLI Reference

Sparkwing ships a single sparkwing binary. This page is a map of what each command group is for; the complete, auto-generated listing of every command, flag, and argument lives in cli-reference.md (and offline via sparkwing docs read --topic cli-reference). Treat that generated reference as authoritative -- when this page and it disagree, it wins.

The rule across the whole tree: every input is a named flag. The one intentional exception is the pipeline name on sparkwing run <pipeline> (and its sparkwing pipeline run <pipeline> long form), which is positional because operators type it all day.

sparkwing runSection anchor link

sparkwing run <pipeline> [flags...]

Compiles and runs a pipeline from the nearest .sparkwing/, locally. sparkwing run owns a set of control flags prefixed --sw-* (plus --profile and --target); everything else on the line is forwarded to the pipeline binary and parsed against the pipeline's typed Inputs. The --sw-* prefix keeps those control flags from colliding with pipeline-defined flags -- see the flag-namespace section of sdk.md for the full list and the forwarding rules.

--profile NAME selects the storage and dispatch addressing (state/cache/logs, and any controller auth). Execution still happens locally; to hand a run to a cluster, use sparkwing pipeline trigger instead of sparkwing run.

Command groupsSection anchor link

Top-level groups, each with its own --help and a full entry in cli-reference.md:

GroupFor
infoAgent entrypoint card: what sparkwing is, what's in this repo, what to run next
pipelineThis repo's pipelines: list / describe / discover / new / explain / run / trigger / hooks / sparks
runShortcut for pipeline run (the positional form)
runsInspect and manage runs: list / status / logs / retry / cancel, plus approvals and triggers
profileShow which profile would resolve right now, and why (read-only; never prints tokens)
versionComposite CLI + SDK + sparks version card; version update --sdk bumps the pinned SDK
updateSelf-update the sparkwing CLI binary
dashboardDetached local dashboard server: start / kill / status
clusterCluster ops against a profile's controller: status / agents / worker / gc / users / tokens / image / webhooks / concurrency
secretsSecrets, laptop dotenv or controller-stored with --profile: set / get / list / delete
configureLaptop-local config: init / profiles / xrepo
debugInteractive run debugging: run / release / attach / env / rerun / replay
docsThe embedded copy of this doc tree: list / read / all / search
commandsThe full CLI surface as JSON (agent self-discovery)
completionShell completion script (--shell bash|zsh|fish)

For repo-local shell chores (formatters, port-forwards, Makefile-style glue) use dowing; sparkwing is the Go-pipeline platform.

ConventionsSection anchor link

  • Named flags only. Every input is --flag value; the pipeline name on sparkwing run is the sole positional.
  • Structured output. List / describe / get verbs accept -o pretty|json|plain (default pretty). -o / --output is the one output-format selector across the CLI.
  • Profile addressing. --profile NAME picks the storage/dispatch profile. Absent, commands read local state (SQLite under ~/.sparkwing/). sparkwing run always executes locally; sparkwing pipeline trigger is the verb for remote (cluster) execution.
  • Required flags. Marked [required] in --help; missing ones fail before any side effect.
  • Hidden entries. Pipelines marked hidden: true don't appear in pipeline list or tab-complete but stay invocable by exact name. Pass --all to pipeline list to see them.

Agent discoverySection anchor link

Agents should read the catalog as JSON rather than scraping help text:

sparkwing pipeline list -o json                 # every invocable with metadata
sparkwing pipeline describe --name X -o json    # one pipeline's full metadata
sparkwing pipeline discover --query TEXT -o json # ranked fuzzy search
sparkwing pipeline explain --name X -o json     # Plan DAG before running
sparkwing commands                              # the entire CLI surface as JSON

The describe schema matches sparkwing.DescribePipeline plus group / tags / triggers drawn from the pipelines: block in .sparkwing/sparkwing.yaml.