> For the complete documentation index, see [llms.txt](https://sparkwing.dev/llms.txt). This page as HTML: https://sparkwing.dev/docs/cli-secrets/ # CLI reference: sparkwing secrets Every `sparkwing secrets` command, flag, and argument, generated from the CLI's own command registry. All command groups are indexed in [cli-reference.md](cli-reference.md). ## `sparkwing secrets` Manage secrets in this machine's local store or on a controller ### Subcommands - `delete` -- Remove a secret - `get` -- Read a secret's value - `list` -- List secret names + metadata - `rotate` -- Re-encrypt every stored secret under the current key - `set` -- Store (or replace) a secret value ### Flags | Flag | Description | |---|---| | `-o, --output FORMAT` | Pretty on a terminal; JSON when piped; explicit format wins. Values: pretty, json, plain. | | `-C, --checkout PATH` | Resolve the project from this local checkout path. | | `-h, --help` | Show command help without executing. | | `--help-all` | Include uncommon flags in command help. | ## `sparkwing secrets delete` Remove a secret Delete the exact pipeline or unscoped row. A pipeline row is named by --repo and --pipeline together. JSON retains whether the row was deleted or already absent; plain emits the name. ### Flags | Flag | Description | |---|---| | `-o, --output FORMAT` | Pretty on a terminal; JSON when piped; explicit format wins. Values: pretty, json, plain. | | `-C, --checkout PATH` | Resolve the project from this local checkout path. | | `-h, --help` | Show command help without executing. | | `--help-all` | Include uncommon flags in command help. | | `--secret NAME` | Secret name. (required) | | `--repo REPO` | Repository identity as owner/name. Naming a repository grants no access. | | `--pipeline NAME` | Pipeline name. | | `--profile NAME` | Controller connection profile from your config. Optional profiles use the saved default, then local; --profile= selects local. | ## `sparkwing secrets get` Read a secret's value This explicit authorized read includes the value. --repo and --pipeline together read the row that repository's pipeline would. JSON retains metadata and value, including an empty value. Pretty and plain emit the raw bytes without adding a newline. ### Flags | Flag | Description | |---|---| | `-o, --output FORMAT` | Pretty on a terminal; JSON when piped; explicit format wins. Values: pretty, json, plain. | | `-C, --checkout PATH` | Resolve the project from this local checkout path. | | `-h, --help` | Show command help without executing. | | `--help-all` | Include uncommon flags in command help. | | `--secret NAME` | Secret name. (required) | | `--repo REPO` | Repository identity as owner/name. Naming a repository grants no access. | | `--pipeline NAME` | Pipeline name. | | `--profile NAME` | Controller connection profile from your config. Optional profiles use the saved default, then local; --profile= selects local. | ## `sparkwing secrets list` List secret names + metadata List metadata without values, including each pipeline row's repository and pipeline, and pool restrictions. Search matches names case-insensitively; --repo matches a repository name case-insensitively or its key exactly, and --pipeline requires --repo. JSON emits metadata records; plain emits names. ### Flags | Flag | Description | |---|---| | `-o, --output FORMAT` | Pretty on a terminal; JSON when piped; explicit format wins. Values: pretty, json, plain. | | `-C, --checkout PATH` | Resolve the project from this local checkout path. | | `-h, --help` | Show command help without executing. | | `--help-all` | Include uncommon flags in command help. | | `--search PATTERN` | Text to match against record names and summaries; log text is not searched. | | `--repo REPO` | Repository identity as owner/name. Naming a repository grants no access. | | `--pipeline NAME` | Pipeline name. | | `--profile NAME` | Controller connection profile from your config. Optional profiles use the saved default, then local; --profile= selects local. | ## `sparkwing secrets rotate` Re-encrypt every stored secret under the current key Retain rotated counts and skipped row names/pipelines. The previous key is still needed when any row was skipped. JSON includes the controller's replay marker. ### Flags | Flag | Description | |---|---| | `-o, --output FORMAT` | Pretty on a terminal; JSON when piped; explicit format wins. Values: pretty, json, plain. | | `-C, --checkout PATH` | Resolve the project from this local checkout path. | | `-h, --help` | Show command help without executing. | | `--help-all` | Include uncommon flags in command help. | | `--profile NAME` | Controller connection profile from your config. Optional profiles use the saved default, then local; --profile= selects local. | ## `sparkwing secrets set` Store (or replace) a secret value Restricted --only-on secrets require matching pool demands at seal and reserved pools at release; restricted secrets are refused for here machines. If neither --value nor --file is supplied, read the value from stdin. Preserve empty values and trailing newlines. --variable stores an unmasked value. A pipeline secret belongs to one GitHub repository and one pipeline: --repo and --pipeline go together, and only runs whose code Sparkwing fetched from that repository through the team's GitHub App, or whose repository a GitHub Actions job proved, read it; uploaded, local and --runner here runs read only --shared secrets. --repo takes owner/name or a gh: key. --shared stores a team-wide secret every pipeline of every repository in the team reads. Local unscoped writes are shared with local pipelines. Controller writes preserve explicit --pipeline or --shared selection. Saving a short secret prints one warning line on stderr. Read `sparkwing docs read --topic secrets` for the masking length rule. JSON returns metadata and replay without the value; plain emits the name. ### Flags | Flag | Description | |---|---| | `-o, --output FORMAT` | Pretty on a terminal; JSON when piped; explicit format wins. Values: pretty, json, plain. | | `-C, --checkout PATH` | Resolve the project from this local checkout path. | | `-h, --help` | Show command help without executing. | | `--help-all` | Include uncommon flags in command help. | | `--secret NAME` | Secret name. (required) | | `--value VALUE` | Secret value given on the command line, where it is visible in shell history and the process list; prefer --file or standard input. | | `--file PATH` | Read the value from this file, which must be a regular file owned by you or root and not writable by group or others. | | `--variable` | Store an unmasked variable instead of a secret. | | `--repo REPO` | Repository identity as owner/name. Naming a repository grants no access. | | `--pipeline NAME` | Pipeline name. | | `--shared` | Store a team-wide secret that every pipeline of every repository in the team reads, including uploaded, local and --runner here runs. | | `--profile NAME` | Controller connection profile from your config. Optional profiles use the saved default, then local; --profile= selects local. | | `--only-on POOL` | Release the secret only to jobs placed on this reserved runner pool, never to here machines; omitted when replacing a secret, its existing pool restriction is kept. |