Show HN: RunSecret – An open source secrets management CLI for developers

Securely manage secrets for local development with one simple philosophy: Never store secrets statically

RunSecret (rsec) is a CLI tool that simplifies secret management for local development by injecting secrets from your team's vault at runtime.

• Why RunSecret?
• How It Works
• Installation
• Quick Start
• Secret Reference Format
• Complete Example
• Commands Reference
• Supported Secret Vaults
  • AWS Secrets Manager
  • Azure Key Vault
  • HashiCorp Vault
  • Upcoming Vault Support (Roadmap)
• Uninstalling
• Contributing
• License

Most engineering teams are solving local development secrets with git-ignored .env files. These files store secrets in plaintext, and are rife with problems:

• ❌ Manual bootstrapping the secret values for every new developer
• ❌ Regular manual updates need to be performed by every team member when secrets rotate
• ❌ There's a high risk of accidental secret commits, especially when you're managing multiple .env files
• ❌ Employees retain access to secrets when they rotate teams or leave the company

It's generally a pain for the developers, and a security risk for the company. RunSecret seeks to address these issues by providing a simple, secure way to manage secrets for local development.

RunSecret uses secret references to solve these problems. Think of these as pointers that replace the secrets themselves. To use RunSecret you simply:

1. Update your environment variables or .env files with references to secrets (not the secrets themselves)
2. Use rsec run to inject actual secret values from your vault at runtime
3. Continue using your existing development workflow with no code changes!

Benefits:

• ✅ Easy Setup: Works with existing .env files and environment variables
• ✅ Team-Friendly: .env files can be safely committed to git, making team onboarding/offboarding a breeze
• ✅ Vault Agnostic: Works with multiple secret storage solutions, with more on the way
• ✅ Secure: Leverages your existing vault permissions so only those who need access to secrets can get them
• ✅ Leak Prevention: Automatically redacts secret values in logs and console output

If you use Homebrew, you can install RunSecret with the following command:

For Linux and macOS, you can use the following command to install RunSecret:

For Linux and macOS, you can use the following command to install RunSecret:

For Windows, you can use the following command to install RunSecret:

1. Authenticate with your secret vault

   Ensure your local machine is authenticated with your secrets vault. This can vary by vault provider, but often requires logging in via a provided CLI.

2. Replace static secrets with references

   Instead of:

   DATABASE_PASSWORD=MyS3cretP@ssw0rd

   Use a secret reference (AWS Secrets Manager Example):

   DATABASE_PASSWORD=rsec://012345678912/sm.aws/MyDatabasePassword?region=us-east-1

3. Run your application with rsec

   Or with a .env file:

   rsec run -e .env -- npm start

Secret references point to secrets in your vault. The format is consistent across all supported secret vaults, though optional arguments may only apply to specific Secret Vaults which support or require thoe features.

All secret references, regardless of the underlying vault, conform to the following format:

where:

• vaultAddress: Is the minimum address required to reach out to the vault. The exact format of this value may vary from one vault provider to the next.
• vaultType: Is a specific string that tells rsec which vault provider this secret lives in.
• secretNameOrPath: Is the full path (where applicable) or name of the secret you want to access.
• arguments: Are optional arguments provided as query parameters to configure how to access the secret value. Note: Some arguments may only apply for certain secret vaults. These will be documented for each secret vault provider.

Tip: Use the rsec ref command to generate references from Vault Addresses or vice versa:

For examples specific to your vault provider, see the Supported Secret Vaults section.

Here's a complete workflow example:

1. Create a .env file with secret references

   # myapp/.env DATABASE_URL=rsec://012345678912/sm.aws/DatabasePassword?region=us-east-1 API_KEY=rsec://apiVault/kv.azure/ApiKey

2. Commit this file to your repository

   Since it contains only references, not actual secrets, it's safe to commit and share with your team.

3. Run your application using rsec

For example:

4. What happens behind the scenes:
   • RunSecret loads the .env file
   • Retrieves actual secrets from AWS Secrets Manager and Azure Key Vault (multiple vaults can be used simultaneously)
   • Injects them into the environment only for your application
   • Monitors stdout/stderr and redacts any accidental leaks of those secrets

Runs a command with secrets injected into the environment.

Example:

Retrieves and copies a secret value directly to your clipboard securely.

Example:

Generates a secret reference from a vault address, or vice versa.

Example:

Authentication:

• Uses standard AWS SDK authentication
• Supports environment variables, shared credentials file, IAM roles

Limitations:

• Only supports string values (not binary)

Secret Reference Format All AWS Secrets Manager references are constructed with the following values:

The region attribute is currently only applicable to AWS Secrets Manager references, and will appear on all secret references for this provider.

Example:

Authentication:

• Uses standard Azure SDK authentication
• Supports Azure CLI, Managed Identity, Service Principal

Secret Reference Format For Azure Key Vault, the reference format is:

Where:

• vaultAddress: The name of the Azure Key Vault (e.g. if using https://myvault.vault.azure.net/ then myvault is the vault address)
• secretName: The name of the secret in the Azure Key Vault
• arguments: Optional arguments, such as version to specify a specific version of the secret.

Example:

Using Azure China/Azure Government/Azure Germany If you are using Azure China, Azure Government, or Azure Germany, you can use rsec in the same way described above, but will replace the kv.azure with a region-specific value. For example, for Azure China, you would use kv.azure.cn instead of kv.azure. Example secret references for each Azure region is as follows:

Supports both versions of the KV secret engine (v1 and v2) and credential-based secret engines such as database, AWS, RabbitMQ, etc.

Authentication:

• Currently supports token-based authentication via one of the following methods:
  • The VAULT_TOKEN environment variable
  • Tokens set in the ~/.vault-token file (via userpass authentication)

Limitations

• Currently returns the entire secret object, not just the value. This will be addressed in issue #8.

Secret Reference Format For HashiCorp Vault, the reference format may look like one of the following:

Where:

• mountPath: The path where the secret or credential is mounted in HashiCorp Vault.
• secretName: The name of the secret in HashiCorp Vault
• arguments: Optional arguments
  • endpoint: The URL encoded endpoint to the HashiCorp Vault server (e.g. https://vault.example.com). If not set, will default to the VAULT_ADDR environment variable.

• GCP Secret Manager
• AWS Parameter Store

We recommend using the same method you used to install RunSecret to uninstall it. For example, if you installed it with Homebrew, you can uninstall it with:

If you installed it with the install script, you can uninstall it with:

Or with wget:

Or with PowerShell:

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.