Docs

CLI Reference

The supported Redshift CLI contract. Unknown commands and flags fail instead of being silently ignored.

Global options

  • --help, -h — show command help
  • --version, -v — show the compiled CLI version
  • --config-dir <path> — override the CLI configuration directory

redshift login

Authenticate with a local nsec or a NIP-46 remote signer.

# Hidden interactive nsec entry
redshift login

# Direct options (avoid secret-bearing values in shared shell history)
redshift login --nsec nsec1...
redshift login --bunker-stdin # Paste a one-time bunker URI through hidden input
redshift login --bunker 'bunker://...?relay=wss://...' # Secret-free pointer only
redshift login --connect

# Non-persistent CI authentication
REDSHIFT_NSEC=nsec1... redshift me

Use --overwrite to replace existing stored credentials. A one-time bunker pairing secret is never written back into the saved bunker pointer.

redshift logout

Remove Redshift credentials from supported secure storage and sanitized CLI configuration.

redshift me

Show the current public identity and authentication source. redshift whoami is an alias.

redshift setup

Create or replace redshift.yaml for the current directory.

# Interactive
redshift setup

# Deterministic CI setup
redshift setup --project my-app --config production --no-interactive

# Replace an existing file intentionally
redshift setup --project my-app --config staging --force

Non-interactive mode uses supplied values or documented defaults and never implies overwrite. Project and environment slugs are validated before the file is written.

redshift run

Fetch the latest authorized bundle, inject it into a hardened child environment, preserve exact argument boundaries, and forward SIGINT, SIGTERM, and SIGHUP.

# Exact argv mode; no shell reparsing
redshift run -- npm start
redshift run -- ./script --literal 'space value' ''

# Explicit shell mode when shell syntax is required
redshift run --command 'npm run build && npm start'

# Existing environment values win for selected names
redshift run --preserve-env PORT,HOST -- npm start

# Override configured context
redshift run --project my-app --config production -- ./deploy

Redshift authentication variables and runtime-hook variables are removed from the child environment. Use either positional argv after -- or --command, never both.

redshift secrets

Manage one secret at a time. Values are redacted unless --raw explicitly acknowledges plaintext output.

# Redacted listing and retrieval
redshift secrets
redshift secrets --json
redshift secrets get API_KEY

# Explicit plaintext (keep stdout out of logs/history)
redshift secrets --raw
redshift secrets --json --raw
redshift secrets get API_KEY --raw

# Mutations
redshift secrets set API_KEY 'sk_live_xxx'
redshift secrets set API_KEY=sk_live_xxx
redshift secrets delete API_KEY

# Plaintext .env export requires --raw
redshift secrets download --raw ./secrets.env
redshift secrets download --raw

# Merge a .env file
redshift secrets upload .env

Secret deletion publishes a newer encrypted empty/update bundle. It removes the key from current Redshift state but cannot erase historical ciphertext already retained by relays or backups.

redshift recovery

Inspect a mutation that reached only part of the configured relay set and retry its exact signed, encrypted event only to relays that were unavailable. Permanent relay rejection remains visible until you remove the local notice.

redshift recovery list
redshift recovery show <event-id>
redshift recovery retry <event-id>
redshift recovery remove <event-id>

The owner-only local record contains relay ciphertext and publication metadata, never a private key or plaintext secret. Retry is not a backup, does not create a new logical version, and cannot erase historical ciphertext retained by relays.

redshift backup

Create a versioned, passphrase-encrypted local snapshot of current authenticated secret state observed from responding configured relays. Restore always requires a separately authenticated target signer.

redshift backup create secrets.redshift
redshift backup restore secrets.redshift
redshift backup restore secrets.redshift --allow-identity-change
redshift backup restore secrets.redshift --allow-identity-change --overwrite

Passphrases use hidden prompts or explicit --passphrase-stdin; they are never accepted through argv, config, or environment variables. Archives exclude signer credentials, relay configuration, recovery records, tombstones, and history. Default restore publishes nothing when destination values conflict, while identical values are no-ops.

This is user-initiated local portability, not automatic or managed retention, complete relay history, key recovery, globally atomic restore, RPO/RTO, availability, or an SLA.

redshift history

Inspect bounded owner-authenticated versions observed from responding configured relays, compare key metadata without exposing values, and restore one complete bundle or logical tombstone as a new event.

redshift history list --project my-app --config production
redshift history list --limit 20 --cursor <cursor> --json
redshift history compare <from-event-id> <to-event-id> --project my-app --config production
redshift history restore <event-id> --project my-app --config production --yes

Ordering uses authenticated inner timestamps and deterministic event-ID ties, not randomized NIP-59 outer timestamps. Restore refreshes current state and aborts if it changed unless --overwrite-current is explicitly supplied. That check reduces accidental overwrite but is not relay-wide compare-and-swap.

Observed history can be incomplete or truncated and is not an audit log, retained backup, cryptographic erasure, RPO/RTO, availability, or an SLA. The dashboard keeps decrypted history only in ephemeral client memory.

redshift configure

Inspect or atomically modify non-secret CLI configuration.

redshift configure
redshift configure relays
redshift configure get relays
redshift configure set relays='["wss://relay.damus.io","wss://nos.lol"]'
redshift configure unset relays
redshift configure reset --yes

Relay URLs must use wss://, except loopback development relays may use ws://. Configuration output redacts credential-bearing fields.

redshift serve

Serve the embedded dashboard locally.

redshift serve
redshift serve --host 127.0.0.1 --port 3000
redshift serve --open

redshift bunker

Run or inspect the local NIP-46 signer prototype. Plaintext key mode requires the explicit --insecure-plaintext-keys acknowledgement.

redshift bunker start
redshift bunker status

redshift upgrade

Download a Linux/macOS release and replace the current binary only after GitHub build-provenance attestation verification succeeds. A current GitHub CLI is required.

redshift upgrade
redshift upgrade --tag v0.10.0
redshift upgrade --force