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

The basic syntax for using Kuba is:

kuba run -- <your-command>

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

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

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

# Useful for Docker containers to avoid inheriting host environment
docker run --env-file=<(kuba run --contain -- env) myapp

Node.js Application

kuba run -- node dist/server.js

Python Application

kuba run -- python app.py

Docker Container

docker run --env-file=<(kuba run --contain -- env) myapp

Shell Script

kuba run -- ./deploy.sh

Validate Access and Mappings

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

# Use default environment
kuba test

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

# Specify an environment
kuba test --env staging

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

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

kuba run --env development -- node app.js
kuba run --env staging -- python app.py
docker run --env-file=<(kuba run --env production --contain -- env) myapp
If no environment is specified, Kuba will use the default environment from your configuration.

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

# Start development server with secrets
kuba run --env development -- npm run dev

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

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

Integrate Kuba into your CI/CD pipelines:

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

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

Use Kuba with Docker containers:

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

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

# Use --contain to avoid inheriting host environment
docker run --env-file=<(kuba run --contain -- env) myapp

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

Validate your kuba.yaml file. Use kuba 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 Kuba is doing:

kuba 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 kuba.yaml configuration file.

Configuration Guide

Cloud Providers

Set up authentication and permissions for your cloud providers.

Cloud Providers Guide