CLI Usage

The Soup CLI is the primary way to interact with your secrets.

Installation

# macOS
brew install soup-secrets/tap/soup

# Linux/WSL
curl -fsSL https://soup.dev/install.sh | sh

# Or download directly
curl -L https://github.com/soup-secrets/soup-engine/releases/latest/download/soup-linux-amd64 -o soup
chmod +x soup
sudo mv soup /usr/local/bin/

Authentication

Login to Cloud

soup login
# Opens browser for authentication

Login to Self-Hosted

soup login http://your-server:8080
# Enter your password when prompted

Check Login Status

soup whoami
# Output: Logged in as user@example.com

Logout

soup logout

Project Commands

Create Project

soup project create my-app
soup project create my-app --description "Main application"

List Projects

soup project list

Delete Project

soup project delete my-app
# Requires confirmation

Environment Commands

Create Environment

# Root environment (no parent)
soup env create my-app base

# Child environment
soup env create my-app production --parent base

List Environments

soup env list my-app

Delete Environment

soup env delete my-app preview-123
# Cannot delete if has child environments

Secret Commands

Set a Secret

soup set <project> <env> <key> <value>

# Examples
soup set my-app base DATABASE_URL "postgres://localhost/mydb"
soup set my-app production API_KEY "sk_live_..."

# From stdin (useful for multiline or sensitive values)
echo "my-secret-value" | soup set my-app base API_KEY -

# From file
soup set my-app base PRIVATE_KEY --file ./private.pem

Get a Secret

soup get <project> <env> <key>

# Examples
soup get my-app production DATABASE_URL

# Raw (without resolving references)
soup get my-app base DATABASE_URL --raw

# Verbose (show inheritance info)
soup get my-app production DATABASE_URL --verbose

List Secrets

soup list <project> <env>

# Show values (hidden by default)
soup list my-app production --show-values

# Show where each value comes from
soup list my-app production --show-source

# Only show secrets set in this environment
soup list my-app production --local

Delete a Secret

soup delete <project> <env> <key>

soup delete my-app production OLD_CONFIG

Export Commands

Export to Shell

# Export as shell commands
soup export my-app production
# Output:
# export DATABASE_URL="postgres://..."
# export API_KEY="sk_live_..."

# Use directly
eval $(soup export my-app production)

Export Formats

# Shell (default)
soup export my-app production --format shell

# Dotenv
soup export my-app production --format dotenv > .env

# JSON
soup export my-app production --format json

# YAML
soup export my-app production --format yaml

Filter Exports

# Only secrets starting with DB_
soup export my-app production --prefix DB_

# Only specific keys
soup export my-app production --keys DATABASE_URL,API_KEY

Run Commands

Execute a command with secrets injected:

soup run <project> <env> -- <command>

# Examples
soup run my-app production -- npm start
soup run my-app development -- python manage.py runserver
soup run my-app staging -- ./my-binary --config /etc/app.conf

Configuration

Config File

Soup stores config in ~/.soup/config.json:

{
  "server": "https://api.soup.dev",
  "token": "..."
}

Environment Variables

Override config with environment variables:

SOUP_SERVER=http://localhost:8080 soup list my-app base
SOUP_TOKEN=your-token soup get my-app base KEY

Project-Level Config

Create .soup.json in your project root:

{
  "project": "my-app",
  "default_env": "development"
}

Now commands use these defaults:

# Instead of: soup get my-app development DATABASE_URL
soup get DATABASE_URL

Output Options

Quiet Mode

soup set my-app base KEY value --quiet
# No output on success

JSON Output

soup list my-app production --json
# Output as JSON for scripting

Common Workflows

Local Development

# Pull secrets for local dev
eval $(soup export my-app development)
npm run dev

Deployment Script

deploy.sh

#!/bin/bash
# Pull production secrets
eval $(soup export my-app production)

# Deploy
docker build -t my-app .
docker run -e DATABASE_URL -e API_KEY my-app

CI/CD Pipeline

.github/workflows/deploy.yml

- name: Install Soup
  run: curl -fsSL https://soup.dev/install.sh | sh

- name: Deploy
  env:
    SOUP_TOKEN: ${{ secrets.SOUP_TOKEN }}
  run: |
    eval $(soup export my-app production)
    ./deploy.sh