Monosecret

Stop committing secrets to git and putting them to .env files.

Secrets end up in .env files that get accidentally committed, shared over Slack, or copy pasted between machines. Each developer has their own version, nobody knows which secrets are actually needed, and onboarding means asking around for values.

Monosecret fixes this by separating secret declaration from secret storage. You commit a monosecret.toml that declares what secrets your application needs, while the actual values live in a secure provider like your system keyring, 1Password, or any other backend. No secrets in git, no .env files to leak.

Documentation | Quick Start | Announcement Blog Post

Features

• Declarative Configuration: Define your secrets in monosecret.toml with descriptions and requirements
• Multiple Provider Backends: Keyring, .env, OnePassword, LastPass, Pass, Proton Pass, environment variables, Google Cloud Secret Manager, AWS Secrets Manager, and Vault/OpenBao
• Type-Safe Rust SDK: Generate strongly-typed structs from your monosecret.toml for compile-time safety
• Profile Support: Override secret requirements and defaults per profile (development, production, etc.)
• Secret Generation: Auto-generate passwords, tokens, UUIDs, and more when secrets are missing — declarative "generate if absent"
• Configuration Inheritance: Extend and override shared configurations using the extends feature
• Discovery: monosecret init to discover secrets from existing .env files

Quick Start

# 1. Initialize monosecret.toml (discovers secrets from .env)
$ monosecret init
✓ Created monosecret.toml with 0 secrets

Next steps:
  1. monosecret config init    # Set up user configuration
  2. monosecret check          # Verify all secrets are set
  3. monosecret run -- your-command  # Run with secrets

# 2. Set up provider backend
$ monosecret config init
? Select your preferred provider backend:
> keyring: Uses system keychain (Recommended)
  onepassword: OnePassword password manager
  dotenv: Traditional .env files
  env: Read-only environment variables
  pass: Unix password manager with GPG encryption
  protonpass: Proton Pass via official pass-cli
  lastpass: LastPass password manager
  gcsm: Google Cloud Secret Manager
  awssm: AWS Secrets Manager
  vault: HashiCorp Vault / OpenBao secret management
  bws: Bitwarden Secrets Manager
? Select your default profile:
> development
  default
  none
✓ Configuration saved to /home/user/.config/monosecret/config.toml

# 3. Check and configure secrets
$ monosecret check

# 4. Run your application with secrets
$ monosecret run -- npm start

# Or with a specific profile and provider
$ monosecret run --profile production --provider dotenv -- npm start

See the Quick Start Guide for detailed instructions.

Installation

$ curl -sSL https://install.monosecret.dev | sh

See the installation guide for more options including Nix and Devenv.

Configuration

Each project has a monosecret.toml file that declares the required secrets:

[project]
name = "my-app"  # Inferred from current directory name when using `monosecret init`
revision = "1.0"
# Optional: extend other configuration files
extends = ["../shared/common", "../shared/auth"]

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
REDIS_URL = { description = "Redis connection string", required = false, default = "redis://localhost:6379" }

# Profile-specific configurations
[profiles.development]
DATABASE_URL = { description = "PostgreSQL connection string", required = false, default = "sqlite://./dev.db" }
REDIS_URL = { description = "Redis connection string", required = false, default = "redis://localhost:6379" }

[profiles.production]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
REDIS_URL = { description = "Redis connection string", required = true }

See the configuration reference for all available options.

Profiles

Profiles allow you to define different secret requirements for each environment (development, production, etc.):

$ monosecret run --profile development -- npm start
$ monosecret run --profile production -- npm start

# Set default profile
$ monosecret config init

Learn more about profiles and profile selection.

Providers

Monosecret supports multiple storage backends for secrets:

• Keyring - System credential store (recommended)
• .env files - Traditional dotenv files
• Environment variables - Read-only for CI/CD
• Pass - Unix password manager with GPG encryption
• Proton Pass - End-to-end encrypted via Proton's official pass-cli
• OnePassword - Team secret management; onepassword:// keeps Monosecret-owned storage while op:// opts into native 1Password references
• LastPass - Cloud password manager
• Google Cloud Secret Manager - GCP secret management
• AWS Secrets Manager - AWS secret management
• Vault / OpenBao - HashiCorp Vault and OpenBao KV engine
• Bitwarden Secrets Manager - Bitwarden Secrets Manager integration

$ monosecret run --provider keyring -- npm start
$ monosecret run --provider dotenv -- npm start

# Legacy Monosecret-owned 1Password storage
$ monosecret run --provider onepassword://Development -- npm start

# Native 1Password references, e.g. op://Development/dotfiles/forges/GITHUB_TOKEN
$ monosecret run --provider op://Development/dotfiles -- npm start

# Configure default provider
$ monosecret config init

See provider concepts and provider reference for details.

Rust SDK

Generate strongly-typed Rust structs from your monosecret.toml:

monosecret_derive::declare_secrets!("monosecret.toml");

fn main() -> Result<(), Box<dyn std::error::Error>> {
	// Load secrets with type safety
	let secrets = Monosecret::load(Provider::Keyring)?;

	// Access secrets as struct fields
	println!("Database: {}", secrets.database_url);

	// Optional secrets are Option<String>
	if let Some(redis) = &secrets.redis_url {
		println!("Redis: {}", redis);
	}

	Ok(())
}

See the Rust SDK documentation for advanced usage including profile-specific types.

CLI Reference

Common commands:

# Initialize and configure
monosecret init                    # Create monosecret.toml
monosecret config init            # Set up user configuration

# Manage secrets
monosecret check                  # Verify all secrets are set
monosecret set KEY               # Set a secret interactively
monosecret get KEY               # Retrieve a secret
monosecret import PROVIDER       # Import secrets from another provider

# Run with secrets
monosecret run -- command        # Run command with secrets as env vars

See the full CLI reference for all commands and options.

Contributing

We welcome contributions! Areas where you can help:

• New provider backends - See the provider implementation guide
• Language SDKs - Help us support more languages beyond Rust
• Package managers - Get Monosecret into your favorite package manager
• Documentation - Improve guides and examples

See our GitHub repository to get started.

License

This project is licensed under the Apache License 2.0.