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

The basic syntax for using Kuba is:

bash
kuba run -- <your-application>

This will fetch all secrets defined in your kuba.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 Kuba is:

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

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.

Important: Escaping $ characters is only necessary when using the --command flag. When passing an application and its arguments directly, Kuba 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 kuba.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 kuba.yaml
kuba run --contain -- node dist/server.js

Node.js Application

bash
kuba run -- node dist/server.js

Python Application

bash
kuba run -- python app.py

Docker Container

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

Shell Script

bash
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.

bash
# 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:

bash
kuba run --env development -- node app.js
bash
kuba run --env staging -- python app.py
bash
docker run --env-file=<(kuba show --output dotenv --env production) 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:

bash
# 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:

bash
# 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:

bash
# 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 .

docker run --env-file=<(kuba 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
kuba show

This will print all environment variables as defined in your kuba.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
kuba show --env prod "DATABASE_URL" "LOG_*"

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

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

Automatically update kuba binary

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

bash
kuba update

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

Interactive TUI for environments and secrets

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

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

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

Show the baked-in changelog

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

bash
# Latest section
kuba changelog latest

# Or a specific version
kuba changelog 1.8.0

Create or edit a user template

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

bash
kuba create template my-template
Tip: You can create a template named default. When you run kuba init without a template name, Kuba 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 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:

bash
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