<div align="center">

Kuba

Why? • Installation • Usage

<p></p>

Kuba is Swahili for "vault."

Kuba helps you to get rid of .env files.

Pass env directly from GCP Secret Manager, AWS Secrets Manager, Azure Key Vault, OpenBao, and Bitwarden Secrets Manager to your application

<p></p> </div>

Table of Contents

• Why?
  • Advantages over other services
• Installation
  • Manual Installation
  • Automatic Linux and macOS Installation
  • Automatic Windows Installation
• Usage
  • Configuration File Structure
  • Environment Variable Interpolation
  • Secret Path Mapping
  • Running with a specific environment
  • Testing configuration and access
• Cloud Provider Setup
  • Google Cloud Platform (GCP)
  • AWS Secrets Manager
  • Azure Key Vault
  • OpenBao
  • Bitwarden Secrets Manager

---

Why?

Environment variables are a common way to manage configuration in applications, especially when deploying to different environments like development, staging, and production.

However, managing these variables can become cumbersome, especially when dealing with multiple cloud providers and secret management systems.

This often leads to the use of .env files, which can be problematic for several reasons:

• Onboarding new developers, often involves sharing .env files. This often leads to .env files being shared insecurely, such as through email or chat applications, which can expose sensitive information.
• Manual Management: Keeping .env files up-to-date with the latest secrets from cloud providers can be tedious and error-prone.
• Security Risks: .env files can accidentally be committed to version control, exposing sensitive information.
• Lack of Standardization: Each cloud provider has its own way of managing secrets, leading to a fragmented approach that can complicate development and deployment.

Kuba addresses these issues by allowing you to define your environment variables in a single kuba.yaml file and fetch them directly from cloud providers like GCP Secret Manager, AWS Secrets Manager, Azure Key Vault, and OpenBao.

This eliminates the need for .env files and provides a more secure, consistent, and scalable way to manage environment variables across different environments.

Advantages over other services

To be clear, there are many other tools that can help you manage secrets:

• Doppler
• Vault
• 1Password Secrets Automation
• Infisical

… and many more.

[!CAUTION] Most of them require a whopping subscription fee, or setting up and maintaining a separate service yourself, which can be a barrier for small teams or individual developers.

However, Kuba is designed to be straightforward and easy to use, by leveraging the existing secret management systems of cloud providers, that you might already be using.

Installation

Kuba is a single binary, so you can install it easily.

Manual installation

Download the latest release from GitHub Releases.

Automatic Linux and macOS installation

You can install it using curl:

curl -sSL https://kuba.mwco.app/install.sh | sh

Automatic Windows installation

Run the following command in PowerShell:

iwr https://kuba.mwco.app/install.ps1 -useb | iex

Usage

kuba run -- <your-application>

This will fetch all secrets defined in kuba.yaml and pass them as environment variables to any arbitrary application.

A basic example:

kuba run -- npm run dev

Running commands directly

If you want to run a command with arguments, use the --command flag:

kuba run --command "<your-command> [args...]"

When using the --command flag, make sure to wrap the entire command in quotes.

If you don't escape $ characters, your shell might try to interpolate them before Kuba runs.

[!IMPORTANT] Escaping $ characters is only necessary when using the --command flag.

When passing an application and its arguments directly, Kuba will handle them correctly.

A basic example with the --command flag:

kuba run --command "echo \$DATABASE_URL"

[!NOTE] 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

Debug mode

For troubleshooting configuration issues and seeing detailed execution steps, you can enable debug mode:

kuba --debug run -- <your-application>
# or use the short form
kuba -d run -- <your-application>

Debug mode provides verbose logging that shows:

• Configuration file discovery and loading
• Environment selection and validation
• Secret provider initialization
• Secret retrieval attempts and results
• Environment variable mapping
• Application execution details

This is particularly useful for:

• Diagnosing cloud provider authentication issues
• Troubleshooting configuration file syntax errors
• Understanding why certain secrets aren't being loaded
• Verifying environment variable interpolation
• Debugging provider-specific errors

Available commands and flags

Kuba provides several commands to help you manage your configuration:

• completion: Generates shell completion scripts for Kuba
• config: Manages global Kuba configuration options such as:
  • cache: Enable or disable local caching of secrets
  • defaults: Manage provider defaults (e.g. default regions)
• create: Create kuba resources such as templates
  • template <template_name>: Create/edit a template in the user templates directory
• convert: Converts existing configuration sources (e.g. dotenv (.env*), Knative Service manifests) to kuba.yaml format
• changelog [latest|version]: Shows the contents of CHANGELOG.md (during build-time) in the terminal
• help: Displays help information for Kuba and its commands
• init [template]: Initializes a new kuba.yaml using a template
• run: Runs an application with environment variables fetched from secrets
• show: Displays the effective environment variables for a given configuration
• test: Tests the configuration and secret retrieval without running an application
• update: Updates Kuba to the latest version
• version: Displays the current version of Kuba

# Initialize a new configuration file
kuba init

# Initialize using a named template from ~/.config/kuba/templates
kuba init my-template

# Create or edit a template in ~/.config/kuba/templates
kuba create template my-template

# Run a command with secrets
kuba run -- <application> [args...]

# Test secret retrieval without running a command
kuba test --env <environment>

# Show version information
kuba version

# Show changelog (contents at built-time)
kuba changelog

# Show latest release notes only
kuba changelog latest

# Show a specific version section only
kuba changelog v1.7.0

# Get help
kuba --help

Global Flags:

• --debug, -d: Enable debug mode for verbose logging
• --version: Show version information
• --help, -h: Show help information

Run Command Flags:

• --env, -e: Specify environment (default: "default")
• --config, -c: Path to configuration file
• --contain: Only use environment variables from kuba.yaml, do not merge with OS environment

Test Command Flags:

• --env, -e: Specify environment (default: "default")
• --config, -c: Path to configuration file

Let's say you want to pass some secrets from GCP to your node application.

kuba run -- node dist/server.js

Using the --contain flag

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

# 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) your-container

and your kuba.yaml would look something like this:

# yaml-language-server: $schema=https://kuba.mwco.app/kuba.schema.json
---
# Top-level sections for different environments.
default:
  provider: gcp
  project: 1337

  # Mapping of cloud projects to environment variables and secret keys.
  env:
    GCP_PROJECT_ID:
      secret-key: "