Projects & Environments

Soup organizes secrets into projects and environments.

Projects

A project represents an application or service that needs configuration. Examples:

• my-api - Your backend API
• web-frontend - Your React/Vue/Svelte app
• worker - Background job processor
• shared - Secrets used across multiple services

Creating Projects

# Create a project
soup project create my-api

# With a description
soup project create my-api --description "Main REST API"

# List all projects
soup project list

Project Organization

Keep projects focused. If secrets are only used by one service, put them in that service’s project. For shared secrets, create a dedicated shared project.

Environments

Environments within a project represent different deployment contexts. Common patterns:

Simple (dev/prod)

base
├── development
└── production

Standard (with staging)

base
├── development
├── staging
└── production

Complex (with preview/PR environments)

base
├── development
├── staging
│   └── preview-*
└── production

Creating Environments

# Create base environment (no parent)
soup env create my-api base

# Create children that inherit from base
soup env create my-api development --parent base
soup env create my-api staging --parent base
soup env create my-api production --parent base

# List environments
soup env list my-api

Environment Naming

Use consistent, lowercase names:

• ✅ base, development, staging, production
• ❌ Base, DEV, Staging, PROD

Working with Secrets

Setting Secrets

# Set in base (available to all children)
soup set my-api base DATABASE_NAME myapi

# Set in specific environment
soup set my-api production DATABASE_HOST prod-db.internal

Getting Secrets

# Get a single secret
soup get my-api production DATABASE_HOST

# Get with inheritance shown
soup get my-api production DATABASE_NAME
# Output shows it's inherited from base

Listing Secrets

# List all secrets in an environment (with inheritance)
soup list my-api production

# List only secrets set directly in this environment
soup list my-api production --local

Deleting Secrets

# Delete a secret
soup delete my-api production DATABASE_HOST

# Delete from base (affects all children)
soup delete my-api base OLD_CONFIG

Best Practices

1. Use Base for Shared Config

Put config that’s the same across environments in base:

soup set my-api base APP_NAME "My API"
soup set my-api base LOG_FORMAT json
soup set my-api base MAX_CONNECTIONS 100

2. Override Only What’s Different

Production might need different values:

soup set my-api production LOG_LEVEL warn  # base has 'info'
soup set my-api production MAX_CONNECTIONS 500

3. Use References for Derived Values

Don’t duplicate:

# Instead of setting DATABASE_URL in every environment
soup set my-api base DB_HOST localhost
soup set my-api base DB_NAME myapi
soup set my-api base DATABASE_URL 'postgres://${DB_HOST}:5432/${DB_NAME}'

# Then just override the component
soup set my-api production DB_HOST prod-db.internal

4. Document with Descriptions

(Coming soon) Add descriptions to help team members understand secrets:

soup set my-api base API_KEY "..." --description "Stripe API key for payments"