SecretStash CLI

Command-line interface for SecretStash - secure team secrets management.

Installation

npm (recommended)

npm install -g @secretstash/cli

Docker

Pull the official Docker image:

# From Docker Hub
docker pull secretstash/cli:latest

# From GitHub Container Registry
docker pull ghcr.io/secretstash/secretstash-cli:latest

Homebrew (macOS/Linux)

brew install secretstash/tap/sstash

Quick Start

Authentication

The CLI uses browser-based authentication by default, supporting passkeys, OAuth (GitHub/Google), and 2FA:

# Login via browser (opens browser window)
sstash login

# This will:
# 1. Generate a session code
# 2. Open your default browser to complete authentication
# 3. Wait for you to sign in (passkey, OAuth, or email/password)
# 4. Automatically complete CLI authentication

# Check who you're logged in as
sstash whoami

# Logout
sstash logout

Service Token Authentication (CI/CD)

For automated workflows, use service tokens instead of browser authentication:

# Set service token as environment variable
export SECRETSTASH_TOKEN=stk_your-service-token

# Or login with token directly
sstash login --token stk_your-service-token

# Verify token works
sstash teams

Working with Secrets

# Pull secrets to .env file
sstash pull --env production --output .env

# Push secrets from .env file
sstash push --env development --input .env

# List all secrets in an environment
sstash list --env production

# Set a single secret
sstash set API_KEY=your-api-key --env production

# Get a single secret
sstash get API_KEY --env production

# Run a command with secrets injected
sstash run --env production -- npm start

Projects and Environments

# List projects
sstash projects list

# Switch project context
sstash projects use my-project

# List environments
sstash environments list

# Create a new environment
sstash environments create staging

Docker Usage

Basic Usage

Run commands directly with Docker:

# Show help
docker run --rm secretstash/cli:latest --help

# Pull secrets (using service token)
docker run --rm \
  -e SECRETSTASH_TOKEN=your-token \
  secretstash/cli:latest \
  pull --env production

# Pull secrets to a file
docker run --rm \
  -e SECRETSTASH_TOKEN=your-token \
  -v $(pwd):/workspace \
  -w /workspace \
  secretstash/cli:latest \
  pull --env production --output .env

Docker Compose

Create a docker-compose.yml:

version: '3.8'
services:
  secretstash:
    image: secretstash/cli:latest
    environment:
      - SECRETSTASH_TOKEN=${SECRETSTASH_TOKEN}
    command: pull --env production

Run with:

export SECRETSTASH_TOKEN=your-token
docker-compose run --rm secretstash

CI/CD Integration

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Pull secrets
        run: |
          docker run --rm \
            -e SECRETSTASH_TOKEN=${{ secrets.SECRETSTASH_TOKEN }} \
            -v ${{ github.workspace }}:/workspace \
            -w /workspace \
            secretstash/cli:latest \
            pull --env production --output .env

      - name: Deploy with secrets
        run: |
          source .env
          # Your deployment commands here

GitLab CI

stages:
  - prepare
  - deploy

pull_secrets:
  stage: prepare
  image: secretstash/cli:latest
  script:
    - sstash pull --env $CI_ENVIRONMENT_NAME --output .env
  artifacts:
    paths:
      - .env
    expire_in: 1 hour

deploy:
  stage: deploy
  needs: [pull_secrets]
  script:
    - source .env
    - ./deploy.sh

CircleCI

version: 2.1
jobs:
  deploy:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Pull secrets
          command: |
            docker run --rm \
              -e SECRETSTASH_TOKEN=$SECRETSTASH_TOKEN \
              -v $(pwd):/workspace \
              -w /workspace \
              secretstash/cli:latest \
              pull --env production --output .env
      - run:
          name: Deploy
          command: |
            source .env
            npm run deploy

Jenkins

pipeline {
    agent any
    environment {
        SECRETSTASH_TOKEN = credentials('secretstash-token')
    }
    stages {
        stage('Pull Secrets') {
            steps {
                sh '''
                    docker run --rm \
                        -e SECRETSTASH_TOKEN=$SECRETSTASH_TOKEN \
                        -v $WORKSPACE:/workspace \
                        -w /workspace \
                        secretstash/cli:latest \
                        pull --env production --output .env
                '''
            }
        }
        stage('Deploy') {
            steps {
                sh '''
                    source .env
                    ./deploy.sh
                '''
            }
        }
    }
}

Multi-Architecture Support

The Docker image supports multiple architectures:

• linux/amd64 (Intel/AMD 64-bit)
• linux/arm64 (ARM 64-bit, including Apple Silicon Macs and AWS Graviton)

Docker will automatically pull the correct architecture for your platform.

Available Tags

| Tag | Description | |-----|-------------| | latest | Latest stable release | | x.y.z | Specific version (e.g., 1.2.3) | | x.y | Latest patch for minor version (e.g., 1.2) | | x | Latest minor/patch for major version (e.g., 1) |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SECRETSTASH_TOKEN | Service token for authentication | - | | SECRETSTASH_API_URL | API endpoint URL | https://api.secretstash.dev | | SECRETSTASH_CONFIG_DIR | Configuration directory | ~/.config/secretstash |

Configuration

Config File

The CLI stores configuration in ~/.config/secretstash/config.json:

{
  "apiUrl": "https://api.secretstash.dev",
  "currentProject": "my-project",
  "currentTeam": "my-team"
}

Service Tokens

For CI/CD and automated workflows, use service tokens instead of user credentials:

1. Generate a token in the web dashboard under Settings > Service Tokens
2. Set the SECRETSTASH_TOKEN environment variable
3. Optionally scope tokens to specific environments for security

Commands Reference

Authentication

| Command | Description | |---------|-------------| | sstash login | Authenticate via browser (passkeys, OAuth, 2FA) | | sstash login --token <token> | Authenticate with service token | | sstash logout | Clear authentication | | sstash whoami | Show current user/token info | | sstash 2fa setup | Set up two-factor authentication | | sstash register | Create a new SecretStash account |

Secrets

| Command | Description | |---------|-------------| | sstash pull | Pull secrets from SecretStash | | sstash push | Push secrets to SecretStash | | sstash secrets list | List secrets in an environment | | sstash secrets get <key> | Get a specific secret | | sstash secrets set <key>=<value> | Set a specific secret | | sstash secrets delete <key> | Delete a specific secret | | sstash secrets history <key> | View version history for a secret | | sstash secrets rollback <key> | Rollback to a previous version | | sstash secrets tag <key> <tag> | Add a tag to a secret | | sstash secrets untag <key> <tag> | Remove a tag from a secret | | sstash secrets expiring | List secrets expiring soon | | sstash run | Run a command with secrets injected | | sstash diff | Compare local and remote secrets |

Organization

| Command | Description | |---------|-------------| | sstash teams | List teams | | sstash teams use <slug> | Switch team context | | sstash projects | List projects in current team | | sstash projects use <slug> | Switch project context | | sstash environments | List environments in current project | | sstash environments create <name> | Create a new environment |

Tags & Shares

| Command | Description | |---------|-------------| | sstash tags | List tags in current team | | sstash tags create <name> | Create a new tag | | sstash share create <key> | Create a share link for a secret | | sstash share list | List active share links | | sstash share revoke <id> | Revoke a share link |

Use sstash --help or sstash <command> --help for detailed usage information.

Security

• All secrets are encrypted in transit (TLS 1.3) and at rest (AES-256-GCM)
• Service tokens can be scoped to specific environments
• Audit logs track all secret access and modifications
• The CLI never stores secrets on disk (except when explicitly writing to .env files)

For security best practices, see SECURITY.md.

License

MIT