Learn how to use withsecrets to securely run your applications with environment variables from cloud providers.

The basic syntax for using withsecrets is:

bash
ws run -- <your-application>

This will fetch all secrets defined in your ws.yaml file and pass them as environment variables to your application. By default, these secrets are merged with your current OS environment.

The basic syntax for running a one-of command with withsecrets is:

bash
ws run --command "echo \$SOME_SECRET"

This will fetch all secrets defined in your ws.yaml file and pass them as environment variables to your command. By default, these secrets are merged with your current OS environment.

Important: Escaping $ characters is only necessary when using the --command flag. When passing an application and its arguments directly, withsecrets will handle them correctly.
Important: The --command flag tries to spawn a shell to run the command, so it may behave differently on different platforms. It tries to use the default shell on your system by checking the $SHELL environment variable on Unix-like systems

The --contain flag prevents the merging of the current OS environment with the environment variables from ws.yaml. This is useful when you want to ensure only the secrets defined in your configuration are available to the command.

bash
# Only use environment variables from ws.yaml
ws run --contain -- node dist/server.js

Node.js Application

bash
ws run -- node dist/server.js

Python Application

bash
ws run -- python app.py

Docker Container

bash
docker run --env-file=<(ws show --output dotenv --env default) myapp

Shell Script

bash
ws run -- ./deploy.sh

Validate Access and Mappings

Use the test subcommand to verify that withsecrets can load your configuration and retrieve all mapped values for an environment without executing a program.

bash
# Use default environment
ws test

# Also test with verbose/debug output
ws test --debug

# Specify an environment
ws test --env staging

# Point to a specific configuration file
ws test --config ./config/ws.yaml --env production

You can specify which environment configuration to use with the --env flag:

bash
ws run --env development -- node app.js
bash
ws run --env staging -- python app.py
bash
docker run --env-file=<(ws show --output dotenv --env production) myapp
If no environment is specified, withsecrets will use the default environment from your configuration.

Use withsecrets during development to avoid managing local .env files:

bash
# Start development server with secrets
ws run --env development -- npm run dev

# Run tests with test environment secrets
ws run --env testing -- npm test

# Run database migrations
ws run --env development -- npm run migrate

Integrate withsecrets into your CI/CD pipelines:

bash
# Build and test with staging secrets
ws run --env staging -- npm run build
ws run --env staging -- npm test

# Deploy with production secrets
ws run --env production -- docker build -t myapp .
ws run --env production -- docker push myapp

Use withsecrets with Docker containers:

bash
# Run container with secrets as environment variables
ws run -- docker run -e DATABASE_URL -e API_KEY myapp

# Build container with secrets available during build
ws run -- docker build --build-arg DATABASE_URL --build-arg API_KEY .

docker run --env-file=<(ws show --output dotenv) myapp

Show values

Use the show subcommand to display the resolved environment variables based on your configuration without running a program:

bash
ws show

This will print all environment variables as defined in your ws.yaml file.

You can also specify an environment to show its specific variables. Or just show a specific variable by name, or a group of variables using a wildcard.

bash
ws show --env prod "DATABASE_URL" "LOG_*"

If you want to hide sensitive values when displaying, use the --sensitive flag.

bash
ws show --sensitive --env prod "LOG_*"

Automatically update withsecrets binary

withsecrets can update itself to the latest version using the following command:

bash
ws update

This command checks for the latest version of withsecrets and replaces the current binary with the updated one. It also creates a backup of the existing binary.

Interactive TUI for environments and secrets

withsecrets includes an interactive terminal UI for viewing, editing, and adding secrets.

bash
# Uses ./ws.yaml if present, otherwise searches parent directories
ws tui

# Or point to a specific file
ws tui --config ./config/ws.yaml
The TUI reads your configured providers from ws.yaml. Make sure you’ve set up auth for your provider(s) first (see Providers).

Show the baked-in changelog

You can view withsecrets’s changelog directly in your terminal (rendered as formatted markdown):

bash
# Latest section
ws changelog latest

# Or a specific version
ws changelog 1.8.0

Create or edit a user template

withsecrets can open a user template in your editor (uses $VISUAL or $EDITOR).

bash
ws create template my-template
Tip: You can create a template named default. When you run ws init without a template name, withsecrets will use that default template automatically.
If you see “no default editor is set”, set VISUAL or EDITOR in your shell.

Ensure your cloud provider credentials are properly configured. Check the Cloud Providers guide for setup instructions.

Validate your ws.yaml file. Use ws init to generate a valid template.

Ensure your credentials have the necessary permissions to access the secrets specified in your configuration.

Enable debug mode to see detailed information about what withsecrets is doing:

bash
ws run --debug -- node app.js
  • Never commit secrets to version control
  • Use environment-specific configurations
  • Rotate secrets regularly
  • Limit access to production secrets
  • Use descriptive environment variable names
  • Group related secrets with secret paths
  • Leverage variable interpolation
  • Document your configuration structure
  • Test configurations in staging first
  • Use CI/CD for consistent deployments
  • Monitor secret access and usage
  • Have a rollback strategy
  • Use local development environments
  • Share configuration templates, not secrets
  • Test with different cloud providers
  • Keep configurations in sync across teams

Configuration Guide

Learn how to set up your ws.yaml configuration file.

Configuration Guide

Cloud Providers

Set up authentication and permissions for your cloud providers.

Cloud Providers Guide