Quick Start

Installation

Choose your preferred installation method:

$ npm install --global @monosecret/cli

brew install monosecret

winget install --exact --id Cachix.Monosecret

Add to your devenv.nix:

{ config, ... }:
{
  # Secrets are automatically populated from monosecret.toml
  env.DATABASE_URL = config.monosecret.secrets.DATABASE_URL;
  env.REDIS_URL = config.monosecret.secrets.REDIS_URL;
}

$ nix-env -iA monosecret -f https://github.com/NixOS/nixpkgs/tarball/nixpkgs-unstable

Getting started

Start with one project and the system keyring. You will declare the secrets the application expects, store one value, and run the application with that value in its environment.

1. Initialize `monosecret.toml`

From your project directory, create a manifest:

$ monosecret init

✓ Created monosecret.toml with 0 secrets

Next steps:
  1. monosecret config global init    # Set up user defaults (0.2+)
  2. monosecret check                 # Verify all secrets are set
  3. monosecret run -- your-command   # Run with secrets

This example assumes the project does not have a .env file. If one exists, init discovers its secret names automatically and reports the number of declarations it created. Review those declarations instead of replacing them in the next step. See Migration for details.

2. Declare your secrets

Edit monosecret.toml so it describes what your application expects:

[project]
name = "my-app"
revision = "1.0"

[profiles.default]
DATABASE_URL = { description = "PostgreSQL connection string", required = true }
SENTRY_DSN = { description = "Error reporting endpoint", required = false }

DATABASE_URL must be available before the application can run. SENTRY_DSN is optional, so leaving it unset does not block resolution. The manifest contains declarations, not secret values, and is safe to commit.

3. Store and use a secret

Store the required value in your system keyring:

$ monosecret set DATABASE_URL --provider keyring

Enter value for DATABASE_URL (profile: default): ********
✓ Secret 'DATABASE_URL' saved to keyring (profile: default)

Start your application with the resolved values in its environment:

$ monosecret run --provider keyring -- npm start

4. Configure your personal defaults

The commands above use --provider keyring explicitly. Monosecret 0.2+ can save your preferred backend and default profile as preferences for your user:

$ monosecret config global init  # 0.2+
? Select your preferred provider backend:
> keyring: Uses system keychain (Recommended)
  kdbx: KeePass KDBX databases (0.2+)
  onepassword: 1Password password manager
  keeper: Keeper Secrets Manager (0.2+) via official Rust SDK
  dotenv: Traditional .env files
  file: Plaintext files, one per secret (0.2+)
  env: Read-only environment variables
  null: Use defaults, generation, or run prompts without storage (0.19+)
  systemd-credential: Read-only systemd service credentials (0.17+)
  fly: Fly.io application secrets via flyctl, write-only (0.20+)
  cloudflare: Cloudflare Secrets Store, write-only (0.20+)
  pass: Unix password manager with GPG encryption
  gopass: Gopass CLI password manager with GPG encryption (0.2+)
  protonpass: Proton Pass via official pass-cli
  passbolt: Passbolt self-hosted password manager (0.2+) via go-passbolt-cli
  lastpass: LastPass password manager
  dashlane: Dashlane password manager, read-only (0.2+)
  gcsm: Google Cloud Secret Manager
  awssm: AWS Secrets Manager
  awsps: AWS Systems Manager Parameter Store (0.2+)
  scaleway: Scaleway Secret Manager (0.2+)
  vault: HashiCorp Vault secret management
  openbao: OpenBao secret management (0.2+)
  bw: Bitwarden Password Manager (0.2+)
  bws: Bitwarden Secrets Manager
  akv: Azure Key Vault
  aac: Azure App Configuration (0.20+)
  infisical: Infisical secret management (0.16+)
  age: age-encrypted file (0.17+)
  sops: SOPS encrypted files (0.17+)
  kubernetes: Kubernetes (0.20+)
? Select your default profile:
  development
> default
  none
✓ Configuration saved to /home/user/.config/monosecret/config.toml

These preferences are stored in ~/.config/monosecret/config.toml. They are not written to the project, committed to version control, or shared with other users. They become your personal defaults across projects and can still be overridden by project configuration or command-line options.

You can now omit the provider from everyday commands:

$ monosecret set DATABASE_URL
$ monosecret check
$ monosecret run -- npm start

Next Steps

Continue with the commands in Basic Usage
Bring existing values into Monosecret with the Migration guide
Learn about Profiles to manage environment-specific configurations
Explore different Providers for secret storage
Choose an SDK to resolve secrets from your application