CLI Reference

Global flags

These flags apply to every command.

ss secret — path-based access

Retrieve any secret type by its container path. The path format is container/key or container/key/version. No need to know the secret type — the API resolves it automatically.

ss secret <container/key[/version]> [flags]

Examples

# Get the current value of a secret
ss secret production/postgres-password

# Output:
# Name:    postgres-password
# Type:    computer_credential
# Created: 2026-02-15
#
# Data:
#   password:            s3cur3P@ssw0rd!

# Pipe the value directly to another command (-q returns only the secret value)
ss secret production/postgres-password -q
# s3cur3P@ssw0rd!

# Use in command substitution
export DB_PASS=$(ss secret production/postgres-password -q)
psql -U admin -W "$DB_PASS" mydb

# Get a specific historical version (2 = previous, 3 = two versions back)
ss secret production/postgres-password/2

# Output as JSON
ss secret production/postgres-password -o json

Versioning

Version numbers: 1 = current (default), 2 = previous, 3 = two back, etc. Maximum stored versions is configurable per-secret (1–12, default 6) and requires history to be enabled.

ss secret history

View or configure version history for a secret.

ss secret history <container/key> [flags]

Flags:
  --enable        Enable version history for this secret
  --disable       Disable version history
  --max INT       Maximum versions to store (1-12)

Examples

# List version history (metadata only — not values)
ss secret production/postgres-password history

# Version    Date                           Created By
# ----------------------------------------------------------
# v1 (prev)  2026-02-14 09:12:34            alice@example.com
# v2         2026-02-10 14:22:01            bob@example.com
# v3         2026-01-28 11:05:50            alice@example.com

# Enable history and keep up to 6 versions
ss secret production/postgres-password history --enable --max 6

# Disable history
ss secret production/postgres-password history --disable

ss secret share

Share a secret with another user in your organisation. They must already have an account.

ss secret share <container/key> --with EMAIL [--expires DURATION]

Flags:
  --with EMAIL      Email of user to share with (required)
  --expires DURATION  Expiry duration: 1h, 24h, 7d, 30d, etc. (default: 72h)

Examples

# Share with read access, expires in 3 days (default)
ss secret production/postgres-password share --with bob@example.com

# Share with custom expiry
ss secret production/postgres-password share --with bob@example.com --expires 7d

# Share a Wi-Fi credential with an employee
ss secret office/wifi/guest-network share --with contractor@example.com --expires 1d

ss secret temp-access

Generate a short-lived, unauthenticated token that grants access to a single secret value. Ideal for CI/CD pipelines, ephemeral scripts, and external services that cannot hold an API key.

ss secret temp-access <container/key> --duration DURATION

Flags:
  --duration DURATION   Token lifetime: 5m, 15m, 1h, 4h, 24h (default: 15m)

Examples

# Generate a 15-minute token
ss secret production/deploy-key temp-access --duration 15m

# TOKEN=a3f8c2e1d4b7...
# EXPIRES=2026-02-17T12:15:00Z

# Use in a script (-q outputs JSON)
RESULT=$(ss secret production/deploy-key temp-access --duration 15m -q)
TOKEN=$(echo $RESULT | jq -r .TOKEN)

# Redeem the token via HTTP (no API key required)
curl https://api.secretserver.io/api/v1/t/$TOKEN

ss secrets — generic secrets

Manage generic key-value secrets. Use ss secret (singular) for path-based access to typed credentials.

ss secrets list                  # List all secrets
ss secrets get NAME              # Get secret by name
ss secrets create                # Create a new secret (interactive)
ss secrets create --name NAME --value VALUE
ss secrets delete NAME

Shell integration

# Pipe secret to docker login
ss secret registry/dockerhub -q | docker login --password-stdin

# Inject into environment
export STRIPE_KEY=$(ss secret payments/stripe-secret -q)
export AWS_SECRET=$(ss secret aws/access-key -q)

# Pass to kubectl as a secret
kubectl create secret generic db-creds   --from-literal=password="$(ss secret prod/db-password -q)"

# SSH using a stored key
ss secret servers/bastion-key -q > /tmp/key && chmod 600 /tmp/key
ssh -i /tmp/key user@bastion.example.com

Scripting & CI/CD

GitHub Actions

- name: Install ss CLI
  run: curl -sSL https://secretserver.io/install | sh

- name: Deploy
  env:
    SS_API_KEY: ${{ secrets.SS_API_KEY }}
  run: |
    export DB_PASS=$(ss secret production/postgres-password -q)
    ./deploy.sh

Using temp-access in CI (no stored API key)

# In your pipeline setup step (using your API key once):
TOKEN=$(ss secret production/deploy-key temp-access --duration 1h -q | jq -r .TOKEN)

# Pass TOKEN to the job — no API key needed in the job itself
curl https://api.secretserver.io/api/v1/t/$TOKEN

Dockerfile pattern

RUN curl -sSL https://secretserver.io/install | sh
# At runtime, not build time:
CMD ["sh", "-c", "export DB=$(ss secret prod/db-password -q) && exec myapp"]