Migrating to v0.46.0

Sparkwing v0.46.0 removes one CLI verb and changes what several commands print when stdout is not a terminal. Every migration is a mechanical edit to scripts and hooks: rewrite sparkwing runs submit calls, and add --output plain or --output pretty where a script consumed a command's text. Nothing in the runs store or the wire protocol changes.

runs submit becomes run --sw-detached

• Before: sparkwing runs submit [submit flags] <pipeline> [pipeline flags] queued a detached run. Its own flags went before the pipeline name and had no sw- prefix: --idempotency-key, --request-id, --consumer-idle, --consumer-claim-lease, --home, -C/--cd, -o/--output.

• After: sparkwing run <pipeline> --sw-detached [pipeline flags] does the same thing. The submit-only flags are --sw-idempotency-key, --sw-request-id, --sw-consumer-idle, --sw-consumer-claim-lease, and --sw-output, placed after the pipeline name like every other --sw- flag; --sw-cd replaces -C, and the home comes from SPARKWING_HOME. --sw-ref and --sw-priority behave as they did on submit. sparkwing runs submit is an unknown subcommand.

• Migration: Mechanical. Rewrite each call:

  # before
  sparkwing runs submit --idempotency-key k deploy --env staging
  # after
  sparkwing run deploy --sw-detached --sw-idempotency-key k --env staging
  

  A pipeline that declares a flag named like a detached-only flag is not reachable by that name in detached mode, the same rule as for every --sw- flag. Runs already queued by the old verb execute unchanged; the stored trigger source is still runs-submit, so runs find queries keep matching.

Lifecycle output

Dashboard and run-consumer start, status, and stop commands now emit compact JSON when stdout is piped. pipeline hooks status emits hook records followed by a summary. Existing status exit codes are unchanged.

Use --output pretty when a script needs the previous readable report. Use --output plain for one running or stopped value from a service command, or one hook name per line from hook status. JSON consumers should select the state field for services and kind: hook records for individual hooks.

Discovery and report output

• Before: Discovery and report commands (commands, docs, info, completion, cache info|explain|prune, and the other read-only report verbs) printed their readable text whether or not stdout was a terminal, and --output markdown selected Markdown from commands.
• After: With stdout redirected they emit compact JSON: one object per report, one object per line for lists, an empty stream for no results, errors on stderr only. Help, docs, agent cards, and completion scripts carry typed kind + text records in JSON mode. An explicit --output pretty|json|plain always wins over terminal detection. Cache JSON reports expose their fields directly (.entries, not .payload.entries) and a failed cache command returns nonzero with no stdout record. --output markdown is gone; commands --format markdown selects Markdown and --split-dir DIR writes it to files.
• Migration: Add --output plain wherever a script consumed the original text, for example source <(sparkwing completion --shell zsh --output plain), sparkwing docs read --topic pipelines --output plain, and sparkwing commands --format markdown --output plain. Read cache fields from the top level of the JSON object. See docs/cli.md for the full contract.

Bounded discovery

commands and docs list now return at most 40 records; docs search returns at most 20. JSON output ends with a kind: "page" record carrying total, returned, limit, truncated, and an optional next_cursor. Consumers must distinguish that record from command/topic/search metadata. Follow it with --cursor <next_cursor> and the same query/filter flags. Use the same binary version for continuation. --limit 0 explicitly emits all remaining matches; plain mode leaves continuation on stderr.

Replace sparkwing commands | grep -i status with sparkwing commands --query status. Command paths and synopses are searched before pagination; child counts still describe the full visible tree.

Documentation search no longer includes full bodies in JSON by default. Read the selected hit with sparkwing docs read --topic <slug> --section <start_line>, or request docs search --query <text> --body for the selected page's bodies. Section selectors apply only to embedded topics, not --web or --guide. Explicit Markdown command exports remain exhaustive and reject query/pagination flags.