CLI Reference

Command-line interface for Soup. Manage secrets, flags, projects, and more.

Installation

curl -fsSL https://cli.getsoup.dev/install.sh | sh

Downloads the correct binary for your platform (Linux/macOS x64/ARM64).

Authentication

# Browser-based login
soup login

# Device flow (for remote/headless)
soup login --device

# Check current user
soup whoami

# Logout
soup logout

See Authentication for details on tokens and service accounts.

Projects

# Create project
soup project create my-app

# List projects
soup project list

Environments

# Create root environment
soup env create my-app root

# Create child environment (inherits from parent)
soup env create my-app production --parent root

Environments can be named anything. Common pattern: root, development, staging, production.

Secrets

Set/Get

# Set a secret
soup secrets set DATABASE_URL postgres://localhost/db

# Get a secret
soup secrets get DATABASE_URL

# List all secrets
soup secrets list

Context auto-selected from config. Or specify explicitly:

soup secrets set --project my-app --env production API_KEY xyz

Download/Upload

# Download all secrets to file
soup secrets download > secrets.env

# Upload secrets from file
soup secrets upload secrets.env

Run with Secrets

# Inject secrets as env vars
soup run -- npm start
soup run -- python manage.py runserver

Secrets exported to environment before running command.

Aliases

Short versions for secrets commands:

soup s set KEY value    # same as soup secrets set
soup s get KEY          # same as soup secrets get
soup s ls               # same as soup secrets list

Feature Flags

# Create flag
soup flags create dark-mode

# Enable/disable
soup flags on dark-mode
soup flags off dark-mode

# List flags
soup flags list

# Get flag details
soup flags get dark-mode

Aliases

soup f create dark-mode    # same as soup flags create
soup f on dark-mode        # same as soup flags on
soup f ls                  # same as soup flags list

API Tokens

# Create token interactively
soup token create

# Create with specific scopes
soup token create --name "CI" --scopes secrets:read,secrets:write

# List tokens
soup token list

# Revoke token
soup token revoke <id>

# Show available scopes
soup token scopes

Available scopes:

• projects:read, projects:write
• secrets:read, secrets:write, secrets:delete
• flags:read, flags:write, flags:delete
• envs:create, envs:delete

Configuration

Interactive Setup

soup config

Prompts for project and environment context. Saves to ~/.soup/config.json.

Config File

Location: ~/.soup/config.json

{
  "dashboard_url": "https://app.getsoup.dev",
  "control_plane_url": "https://app.getsoup.dev",
  "token": "soup_pat_...",
  "org": "my-org",
  "project": "my-app",
  "environment": "production"
}

Environment Variables

Override config with env vars:

SOUP_TOKEN=soup_pat_xxx soup secrets list
SOUP_PROJECT=other-app soup flags list

Utilities

# Check health
soup health

# Show version
soup version

# Update CLI
soup update

# Show settings
soup settings show

Common Workflows

Local Development

# Pull secrets and run app
soup run -- npm run dev

CI/CD

# GitHub Actions
- name: Install Soup
  run: curl -fsSL https://cli.getsoup.dev/install.sh | sh

- name: Deploy
  env:
    SOUP_TOKEN: ${{ secrets.SOUP_TOKEN }}
  run: |
    soup config  # sets project/env
    soup run -- ./deploy.sh

Environment Variables

# Export to current shell
eval $(soup secrets export)

# Or manually source
soup secrets download > .env
source .env

Self-Hosted

For standalone Soup instances:

# Use API key instead of session token
SOUP_TOKEN=sk_master_xxx soup secrets list

# Point to local instance
soup config
# Server URL: http://localhost:8080

Getting Help

# Show all commands
soup --help

# Command-specific help
soup secrets --help
soup flags create --help