npm package: @secretstash/cli
Description: CLI tool for SecretStash - secure team secrets management
Latest version: 0.1.9

# SecretStash CLI

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

## Installation

### npm (recommended)

```bash
npm install -g @secretstash/cli
```

### Docker

Pull the official Docker image:

```bash
# From Docker Hub
docker pull secretstash/cli:latest

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

### Homebrew (macOS/Linux)

```bash
brew install secretstash/tap/sstash
```

## Quick Start

### Authentication

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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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`:

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

Run with:

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

### CI/CD Integration

#### GitHub Actions

```yaml
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

```yaml
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

```yaml
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

```groovy
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`:

```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](./SECURITY.md).

## License

MIT