CLI reference: sparkwing configure

CLI reference: sparkwing configure

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

sparkwing configureSection anchor link

Configure laptop-local settings

Configure this machine. 'init' prepares the configuration directory and reports its contents. 'profiles' manages controller connections. 'xrepo' registers local repositories.

Manage controller users and tokens with 'sparkwing cluster'. Manage secrets with 'sparkwing secrets'.

SubcommandsSection anchor link

  • init -- Set up ~/.config/sparkwing/ and report laptop-level config status
  • profiles -- Manage connection profiles for remote controllers
  • xrepo -- Manage the laptop-local repo registry

ExamplesSection anchor link

# First-time laptop setup
sparkwing configure init

# Status of laptop config
sparkwing configure init -o json

# List profiles
sparkwing configure profiles list

# Add a new profile
sparkwing configure profiles add --name prod --controller https://api.sparkwing.example --token $TOKEN

# Register the current repo with the cross-repo registry
sparkwing configure xrepo add

sparkwing configure initSection anchor link

Set up ~/.config/sparkwing/ and report laptop-level config status

Idempotent setup + status command for laptop-level sparkwing config. Creates ~/.config/sparkwing/ if it doesn't exist, then reports which config files are present (profiles.yaml, repos.yaml, secrets.env), the running CLI + Go toolchain version, and a curated list of next-step commands.

Pairs with the per-project flow: use this one on a fresh laptop after install, then run 'sparkwing pipeline new --name ' inside each project to scaffold .sparkwing/ + your first pipeline in one step (no separate init needed).

Re-running on an already-set-up laptop re-applies 0700 to ~/.config/sparkwing/ and reports each config file's mode, naming any that group or other users can read. --dry-run skips both the mkdir and the permission fix so the command reports existing state.

Run inside a sparkwing project, it also reports whether this checkout's declared git hooks fire, and names the command that arms them. It installs nothing and changes no git configuration.

FlagsSection anchor link

FlagDescription
-o, --output FORMATOutput format: pretty | json | plain (default: pretty on TTY, json when piped)
--dry-runProbe + report without creating or tightening ~/.config/sparkwing/

ExamplesSection anchor link

# First-time laptop setup
sparkwing configure init

# Status of laptop config (agent-readable)
sparkwing configure init -o json

# Probe without writing anything
sparkwing configure init --dry-run

sparkwing configure profilesSection anchor link

Manage connection profiles for remote controllers

Profile config lives at $SPARKWING_PROFILES (if set), else $XDG_CONFIG_HOME/sparkwing/profiles.yaml, else ~/.config/sparkwing/profiles.yaml. Permissions on save are 0600.

Every human-driven client command (tokens, users, runs retry/cancel/prune/logs, gc) reads connection info from the selected profile via --profile NAME. No --controller/--token flags exist on other commands; profiles are the only config surface.

SubcommandsSection anchor link

  • add -- Register a new connection profile
  • list -- Print every registered profile
  • show -- Print one profile's full config
  • remove -- Delete a profile
  • duplicate -- Copy one profile's config into another
  • set -- Update fields on an existing profile
  • test -- Probe controller/auth/logs/gitcache for one profile

sparkwing configure profiles addSection anchor link

Register a new connection profile

Creates a new entry in profiles.yaml. --name and --controller are required; the token is optional. --token-stdin reads the token from stdin and prompts without echo when stdin is a terminal; prefer it over --token, which is visible to other processes in the process list and recorded in shell history. Configure storage and service backends by editing profiles.yaml.

FlagsSection anchor link

FlagDescription
--name NAMEProfile name (unique per profiles.yaml) (required)
--controller URLController base URL (required)
--token TOKENBearer token, visible to other processes and shell history (omit for local/unauthed stacks)
--token-stdinRead the bearer token from stdin, prompting without echo on a terminal

ExamplesSection anchor link

# Add a prod profile, prompting for the token
sparkwing configure profiles add --name prod --controller https://api.sparkwing.example --token-stdin

# Add a prod profile from a piped token
printf %s "$TOKEN" | sparkwing configure profiles add --name prod --controller https://api.sparkwing.example --token-stdin

# Add a local profile without auth
sparkwing configure profiles add --name local --controller http://127.0.0.1:4344

sparkwing configure profiles duplicateSection anchor link

Copy one profile's config into another

Copies the source profile into a new destination profile. The destination name must be unused.

FlagsSection anchor link

FlagDescription
--src NAMESource profile name (required)
--dst NAMEDestination profile name (must not exist yet) (required)

ExamplesSection anchor link

# Branch prod into a staging-prod profile
sparkwing configure profiles duplicate --src prod --dst staging-prod

sparkwing configure profiles listSection anchor link

Print every registered profile

Prints a table of profile name, controller URL, logs URL, and token. JSON is one profile per line; the token is redacted in every mode.

FlagsSection anchor link

FlagDescription
-o, --output FORMATOutput format: pretty | json | plain (default: pretty on TTY, json when piped)

ExamplesSection anchor link

# List profiles
sparkwing configure profiles list

# Agent-readable record
sparkwing configure profiles list -o json

sparkwing configure profiles removeSection anchor link

Delete a profile

Removes the named entry from profiles.yaml.

FlagsSection anchor link

FlagDescription
--name NAMEProfile name to remove (required)

ExamplesSection anchor link

# Remove a stale profile
sparkwing configure profiles remove --name old-stage

sparkwing configure profiles setSection anchor link

Update fields on an existing profile

Only flags you pass are overwritten. --token="" explicitly clears the token (empty value, not an omitted flag), and --token-stdin with empty input clears it too. --token-stdin reads the token from stdin and prompts without echo when stdin is a terminal; prefer it over --token, which is visible to other processes in the process list and recorded in shell history. Use --show-token on 'profiles show' afterward to confirm.

FlagsSection anchor link

FlagDescription
--name NAMEProfile name to mutate (required)
--controller URLNew controller URL
--token TOKENNew bearer token, visible to other processes and shell history (empty string clears)
--token-stdinRead the new bearer token from stdin, prompting without echo on a terminal

ExamplesSection anchor link

# Rotate a profile's token
sparkwing configure profiles set --name prod --token-stdin

# Change a profile's controller
sparkwing configure profiles set --name prod --controller https://api.sparkwing.example

sparkwing configure profiles showSection anchor link

Print one profile's full config

Prints all fields of the profile named by --name. Token is redacted unless --show-token is passed.

FlagsSection anchor link

FlagDescription
--name NAMEProfile name (required)
--show-tokenPrint the raw token (redacted by default)

ExamplesSection anchor link

# Show a named profile
sparkwing configure profiles show --name prod

# Show a named profile with the raw token
sparkwing configure profiles show --name prod --show-token

sparkwing configure profiles testSection anchor link

Probe controller/auth/logs/gitcache for one profile

Sequentially checks the profile's controller (/api/v1/health), auth (/api/v1/runs?limit=1 + /api/v1/auth/whoami), logs service (if configured), and gitcache (if configured). Each probe prints ok / warn / fail along with latency and any error detail.

Exit code is non-zero when any probe fails. Missing optional services (logs, gitcache) count as warn, not fail, so a minimally-configured laptop profile can still exit 0.

FlagsSection anchor link

FlagDescription
--profile NAMEProfile name (required)
-o, --output FMTOutput format (json|table)

ExamplesSection anchor link

# Probe a named profile
sparkwing configure profiles test --profile prod

# JSON for scripting
sparkwing configure profiles test --profile prod -o json

sparkwing configure xrepoSection anchor link

Manage the laptop-local repo registry

The registry maps pipeline names to local checkouts so cross-repo RunAndAwait calls resolve without hardcoded WithFreshRepo annotations. Auto-populated when you run 'sparkwing run ' in a .sparkwing/-bearing repo (set SPARKWING_NO_AUTO_REGISTER=1 to disable).

SubcommandsSection anchor link

  • list -- List registered checkouts and their pipelines
  • add -- Register a checkout
  • remove -- Remove a registered checkout
  • prune -- Remove checkouts whose pipeline directory is gone

ExamplesSection anchor link

# Register the current checkout
sparkwing configure xrepo add

# Show the fleet the registry reaches
sparkwing configure xrepo list

# Drop entries whose checkout is gone
sparkwing configure xrepo prune

sparkwing configure xrepo addSection anchor link

Register a checkout

Registers a checkout explicitly. The path defaults to the current directory.

ArgumentsSection anchor link

  • [path] (optional) -- Checkout path; defaults to the current directory

ExamplesSection anchor link

# Register the current checkout
sparkwing configure xrepo add

# Register another checkout
sparkwing configure xrepo add ../service

sparkwing configure xrepo listSection anchor link

List registered checkouts and their pipelines

Shows each registered checkout, its status, and the pipelines it provides.

FlagsSection anchor link

FlagDescription
-o, --output FORMATOutput format: json | table
--pipelinesInclude pipeline names (default: true)

ExamplesSection anchor link

# List registered checkouts
sparkwing configure xrepo list

# Emit one JSON record per checkout
sparkwing configure xrepo list -o json

# Skip pipeline discovery
sparkwing configure xrepo list --pipelines=false

sparkwing configure xrepo pruneSection anchor link

Remove checkouts whose pipeline directory is gone

Removes registered checkouts that no longer contain a .sparkwing directory.

ExamplesSection anchor link

# Remove stale registry entries
sparkwing configure xrepo prune

sparkwing configure xrepo removeSection anchor link

Remove a registered checkout

Removes every registry entry matching a path or basename.

ArgumentsSection anchor link

  • <path-or-basename> (required) -- Registered path or basename to remove

ExamplesSection anchor link

# Remove a checkout by basename
sparkwing configure xrepo remove service