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

ss import — bulk import

Import credentials from external sources in bulk. All sources support --dry-run to preview before writing.

ss import <source> [flags]

Sources:
  env           Scan environment variables for 40+ well-known API keys
  ssh           Import SSH private keys from ~/.ssh/ or a directory
  ssl           Import X.509 certificates from PEM/CRT files
  shadow        Import Linux /etc/shadow entries (requires file access)
  windows-cred  Import Windows Credential Manager entries (cmdkey /list)
  ntlm          Import NTLM hash entries from a dump file

Global flags:
  --container SLUG   Target container to import into (optional)
  --dry-run          Preview without writing to SecretServer
  -v, --verbose      Show each record as it's imported

Examples

# Scan current shell environment for known API keys (OpenAI, GitHub, Stripe, etc.)
ss import env
ss import env --dry-run       # preview — nothing is written
ss import env --container dev-keys

# Import SSH keys from ~/.ssh/
ss import ssh
ss import ssh --dir /etc/ssh                  # system host keys
ss import ssh --file ~/.ssh/id_ed25519        # single key

# Import TLS certificates from PEM files
ss import ssl --file /etc/ssl/certs/prod.pem
ss import ssl --dir /etc/ssl/certs            # entire directory (.pem/.crt/.cer)

# Import Linux shadow file (requires root or readable file)
sudo ss import shadow
ss import shadow --file backup.shadow

# Import Windows Credential Manager (run on Windows, import anywhere)
cmdkey /list > creds.txt
ss import windows-cred --file creds.txt
# or pipe directly on Windows:
cmdkey /list | ss import windows-cred --file -

# Import NTLM hash dump (secretsdump format)
ss import ntlm --file secretsdump.txt
cat hashes.txt | ss import ntlm --file -

ss discover — live discovery

Discover and inspect TLS certificates, SSH host keys, and DNS security records from live hosts. Use --import to save results directly into SecretServer.

ss discover <subcommand> [flags]

Subcommands:
  ssl    Inspect TLS certificate via live connection
  ssh    Retrieve SSH host key fingerprints
  dns    Query DNS security records (DANE, CAA, SSHFP, MTA-STS, SPF, DMARC)
  dkim   Discover DKIM public keys for a domain
  scan   Sweep a network range for TLS and SSH services

Global flags:
  --json           Output as JSON
  --import         Import discovered items into SecretServer
  --container SLUG Container for imported items

Examples

# Inspect a live TLS certificate
ss discover ssl --host example.com
ss discover ssl --host mail.example.com:465
ss discover ssl --host 10.0.0.1:8443 --json

# Retrieve SSH host key fingerprints (no auth required)
ss discover ssh --host example.com
ss discover ssh --host 192.168.1.1:2222

# DNS security records — TLSA/DANE, CAA, SSHFP, MTA-STS, SPF, DMARC
ss discover dns --domain example.com
ss discover dns --domain example.com --json

# DKIM public keys (tries 20 common selectors automatically)
ss discover dkim --domain example.com
ss discover dkim --domain example.com --selector google
ss discover dkim --domain example.com --all-selectors

# Network sweep — TLS (443, 8443) and SSH (22) on a CIDR range
ss discover scan --network 192.168.1.0/24
ss discover scan --hosts db.internal,api.internal,vpn.internal
ss discover scan --network 10.0.0.0/24 --ports 443,8443,9443

# Discover and import in one step
ss discover ssl --host example.com --import --container prod-certs

ss ct — Certificate Transparency

Query and monitor Certificate Transparency logs. CT logs are public, append-only records of every TLS certificate ever issued. Monitoring lets you catch mis-issuance, rogue certificates, and shadow IT before they become incidents.

ss ct <subcommand> [flags]

Subcommands:
  search   Search crt.sh for all known certificates for a domain
  monitor  Add / remove / list domains for CT monitoring
  import   Import certificates from CT logs into SecretServer
  watch    Live-tail new CT log entries for monitored domains

Global flags:
  --json              Output as JSON
  --include-expired   Include expired certificates in results
  --limit INT         Maximum results (default: 50)
  --import            Import found certs into SecretServer
  --container SLUG    Container for imported certs

Examples

# Search CT logs for all certs ever issued for a domain
ss ct search example.com
ss ct search example.com --include-expired
ss ct search example.com --json | jq '.[].common_name'

# Monitor a domain — alerts when new certs are issued
ss ct monitor add example.com
ss ct monitor add *.example.com
ss ct monitor list
ss ct monitor remove example.com

# Import CT log certificates into SecretServer
ss ct import --domain example.com
ss ct import --domain example.com --include-expired --container prod-certs

# Live-tail new CT events for all monitored domains
ss ct watch
ss ct watch --json

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"]