G-Man - Universal Command Line Secret Manager and Injection Tool

gman is a command-line tool for managing and injecting secrets for your scripts, automations, and applications. It provides a single, secure interface to store, retrieve, and inject secrets so you can stop hand-rolling config files or sprinkling environment variables everywhere.

Overview

gman acts as a universal wrapper for any command that needs credentials. Store your secrets—API tokens, passwords, certs—with a provider, then either fetch them directly or run your command through gman to inject what it needs as environment variables, flags, or file content.

Quick Examples: Before vs After

These examples show how gman reduces friction when running tools that need secrets. The run profile snippets referenced here are shown later in this README under Run Configurations.

AWS CLI (env vars)

Before:

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
aws sts get-caller-identity

After (with a run profile named aws):

gman aws sts get-caller-identity

Docker (flags)

Before:

docker run -e API_KEY=... -e DB_PASSWORD=... my/image

After (with a run profile named docker that uses -e flags):

gman docker run my/image

• Pro Tip: Run gman --dry-run docker run my/image to preview the full command with masked values

Config file injection

Before:

# Place plaintext secrets directly in configuration files (not recommended)
# Or use a tool like `envsubst` to replace placeholders; e.g.
export RADARR_API_KEY=...
export SONARR_API_KEY=...
envsubst < ~/.config/managarr/config.yml.template > ~/.config/managarr/config.yml
managarr radarr list movies

After (with a run profile named managarr that injects files):

# `gman` injects secret values into the file(s), runs the command, then restores the original content
gman managarr radarr list movies

Example roundtrip of adding, retrieving, and using a secret

# Add a secret (value read from stdin)
echo "mySuperSecretValue" | gman add my_api_key
# Retrieve a secret
gman get my_api_key
# Use a secret in a wrapped command (with an 'aws' run profile defined)
gman aws sts get-caller-identity

Features

• Secure encryption for stored secrets
• Pluggable providers (local by default; more planned)
• Git sync for local vaults to move secrets across machines
• Command wrapping to inject secrets for any program
• Customizable run profiles (env, flags, or files)
• Direct secret retrieval via gman get ...
• Dry-run to preview wrapped commands and secret injection

Table of Contents

• Features
• Installation
• Configuration
• Providers
  • Local
  • AWS Secrets Manager
  • GCP Secret Manager
  • Azure Key Vault
  • Gopass
• Run Configurations
  • Specifying a Default Provider per Run Config
  • Environment Variable Secret Injection
  • Inject Secrets via Command-Line Flags
  • Inject Secrets into Files
• Detailed Usage
  • Storing and Managing Secrets
  • Running Commands
  • Multiple Providers and Switching
• Creator

Installation

Cargo

If you have Cargo installed, then you can install gman from Crates.io:

cargo install gman

# If you encounter issues installing, try installing with '--locked'
cargo install --locked gman

Homebrew (Mac/Linux)

To install G-Man from Homebrew, install the gman tap. Then you'll be able to install gman:

brew tap Dark-Alex-17/gman
brew install gman

# If you need to be more specific, use:
brew install Dark-Alex-17/gman/gman

To upgrade gman using Homebrew:

brew upgrade gman

Scripts

Linux/MacOS (bash)

You can use the following command to run a bash script that downloads and installs the latest version of gman for your OS (Linux/MacOS) and architecture (x86_64/arm64):

curl -fsSL https://raw.githubusercontent.com/Dark-Alex-17/gman/main/install.sh | bash

Windows/Linux/MacOS (PowerShell)

You can use the following command to run a PowerShell script that downloads and installs the latest version of gman for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64):

powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/Dark-Alex-17/gman/main/scripts/install_gman.ps1 | iex"

Manual

Binaries are available on the releases page for the following platforms:

Windows Instructions

To use a binary from the releases page on Windows, do the following:

1. Download the latest binary for your OS.
2. Use 7-Zip or TarTool to unpack the Tar file.
3. Run the executable gman.exe!

Linux/MacOS Instructions

To use a binary from the releases page on Linux/MacOS, do the following:

1. Download the latest binary for your OS.
2. cd to the directory where you downloaded the binary.
3. Extract the binary with tar -C /usr/local/bin -xzf gman-<arch>.tar.gz (Note: This may require sudo)
4. Now you can run gman!

Enable Tab Completion

gman supports shell tab completion for bash, zsh, and fish. To enable it, run the following command for your shell:

# Bash
echo 'source <(COMPLETE=bash gman)' >> ~/.bashrc
# Zsh
echo 'source <(COMPLETE=zsh gman)' >> ~/.zshrc
# Fish
echo 'COMPLETE=fish gman | source' >> ~/.config/fish/config.fish

Then restart your shell or source the appropriate config file.

Configuration

gman reads a YAML configuration file located at an OS-specific path:

Linux

$HOME/.config/gman/config.yml

Mac

$HOME/Library/Application Support/rs.gman/config.yml

Windows

%APPDATA%/Roaming/gman/config.yml

Discover paths (helpful for debugging)

You can ask gman where it writes its log file and where it expects the config file to live:

gman --show-log-path
gman --show-config-path

Default Configuration

gman supports multiple providers. Select one as the default and then list provider configurations.

---
default_provider: local
providers:
  - name: local
    type: local
    password_file: ~/.gman_password
    # Optional Git sync settings for the 'local' provider
    git_branch: main # Defaults to 'main'
    git_remote_url: null # Set to enable Git sync (SSH or HTTPS)
    git_user_name: null # Defaults to global git config user.name
    git_user_email: null # Defaults to global git config user.email
    git_executable: null # Defaults to 'git' in PATH

# List of run configurations (profiles). See below.
run_configs: []

Providers

gman supports multiple providers for secret storage. The default provider is local, which stores secrets in an encrypted file on your filesystem. The CLI and config format are designed to be extensible so new providers can be documented and added without breaking existing setups. The following table shows the available and planned providers:

Key:

Provider: local

The default local provider stores an encrypted vault file on your filesystem. Any time you attempt to access the local vault (e.g., adding, retrieving, or deleting secrets), gman will prompt you for the password you used to encrypt the applicable secrets.

Similar to Ansible Vault, gman lets you store the password in a file for convenience. This is done via the password_file configuration option. If you choose to use a password file, ensure that it is secured with appropriate file permissions (e.g., chmod 600 ~/.gman_password). The default file for the password file is ~/.gman_password.

For use across multiple systems, gman can sync with a remote Git repository (requires git to be installed).

Important Notes for Git Sync:

• You must create the remote repository on your Git provider (e.g., GitHub) before attempting to sync.
• The git_remote_url must be in SSH or HTTPS format (e.g., git@github.com:your-user/your-repo.git).
• First sync behavior:
  • If the remote already has content, gman sync adopts the remote state and discards uncommitted local changes in the vault directory to avoid merge conflicts.
  • If the remote is empty, gman sync initializes the repository locally, creates the first commit, and pushes.

Example local provider config for Git sync:

default_provider: local
providers:
  - name: local
    type: local
    git_branch: main
    git_remote_url: "git@github.com:my-user/gman-secrets.git"
    git_user_name: "Your Name"
    git_user_email: "your.email@example.com"

Repository layout and file tracking

• By default (no sync), secrets are stored in a single file: ~/.config/gman/vault.yml.
• After configuring a remote and running gman sync for the first time:
  • A dedicated repository directory is created under the config dir, derived from the remote name, e.g. ~/.config/gman/.vault or ~/.config/gman/.test-vault.
  • The existing vault.yml is moved into that directory as ~/.config/gman/.<repo-name>/vault.yml.
  • Only vault.yml is tracked and committed in that repository; other files in the config directory are ignored.
• With multiple local providers each pointing at different remotes, each gets its own .repo-name directory, so you can switch between isolated sets of secrets.

Security and encryption basics

• Client-side encryption: Secrets are encrypted before being written to disk. The local provider uses Argon2id for key derivation and XChaCha20-Poly1305 (AEAD) for encryption/authentication.
• Strong defaults: A unique random salt and nonce are generated with the OS RNG for every encryption; Argon2id parameters are tuned for interactive usage and can evolve in future versions.
• Tamper detection: The AEAD ensures decryption fails if the password is wrong or the ciphertext is modified.
• Envelope format: The stored value encodes header, version, KDF params, and base64-encoded salt, nonce, and ciphertext to enable robust, portable decryption.
• Memory hygiene: Sensitive buffers are wiped after use (zeroized), and secrets are handled with types (like SecretString) that reduce accidental exposure through logs and debug prints. No plaintext secrets are logged.

Provider: aws_secrets_manager

The aws_secrets_manager provider uses AWS Secrets Manager as the backing storage location for secrets.

• Requires two fields: aws_profile and aws_region.
• Uses the shared AWS config/credentials files under the named profile to authenticate.

Configuration example:

default_provider: aws
providers:
  - name: aws
    type: aws_secrets_manager
    aws_profile: default     # Name from your ~/.aws/config and ~/.aws/credentials
    aws_region: us-east-1    # Region where your secrets live

Important notes:

• Deletions are immediate: the provider calls DeleteSecret with force_delete_without_recovery = true, so there is no recovery window. If you need a recovery window, do not delete via gman.
• add uses CreateSecret. If the secret already exists, AWS returns an error. Use update to change an existing secret value.
• IAM permissions: ensure the configured principal has secretsmanager:GetSecretValue, CreateSecret, UpdateSecret, DeleteSecret, and ListSecrets for the relevant region and ARNs.
• Credential resolution: the provider explicitly selects the given aws_profile and aws_region via the AWS config loader; it does not fall back to other profiles or env-only defaults.

Provider: gcp_secret_manager

The gcp_secret_manager provider uses Google Cloud Secret Manager as the backing storage location for secrets.

• Requires: gcp_project_id (string) to scope secrets to your project.
• Replication: secrets are created with Automatic replication.

Configuration example:

default_provider: gcp
providers:
  - name: gcp
    type: gcp_secret_manager
    gcp_project_id: my-project-id

Authentication (Application Default Credentials):

• Option 1: gcloud auth application-default login (user ADC on your machine).
• Option 2: Set GOOGLE_APPLICATION_CREDENTIALS to a service account key JSON file path.
  • Example: export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
  • Ensure the service account has appropriate roles (e.g., roles/secretmanager.admin or a combination of get/create/update/delete/list permissions).

Important notes:

• Deletion removes the entire secret resource, including all versions, not just the latest.
• set creates the Secret and first version; if the Secret already exists, it errors (AlreadyExists). Use update to add a new version.
• get returns the latest version; older versions remain unless you delete the secret.

Provider: azure_key_vault

The azure_key_vault provider uses Azure Key Vault as the backing storage location for secrets.

• Requires: vault_name (Key Vault name; the endpoint is constructed as https://<vault_name>.vault.azure.net).

Configuration example:

default_provider: azure
providers:
  - name: azure
    type: azure_key_vault
    vault_name: my-vault-name

Authentication:

• Use the Azure CLI and ensure you are logged in: az login.
• If needed, select the correct subscription: az account set -s <subscription-id-or-name>.
• The provider uses DefaultAzureCredential, which can authenticate via Azure CLI, environment variables, managed identity, etc.

Important notes:

• Deleting a secret removes the entire secret and all its versions, not just the latest version. Depending on your vault’s soft-delete settings, the secret may enter a deleted state until purged.
• set/update create a new secret version each time; reads return the latest by default.
• Ensure your identity has the necessary Key Vault permissions (RBAC such as Key Vault Secrets User/Administrator, or appropriate access policies) for get/set/list/delete.

Provider: gopass

The gopass provider uses gopass as the backing storage location for secrets.

• Optional: store (string) to specify a particular gopass store if you have multiple.

Configuration example:

default_provider: gopass
providers:
  - name: gopass
    type: gopass
    store: my-store  # Optional; if omitted, uses the default configured gopass store

Important notes:

• Ensure gopass is installed and initialized on your system.
• Secrets are managed using gopass's native commands; gman acts as a wrapper to interface with gopass.
• Updates overwrite existing secrets
• If no store is specified, the default gopass store is used and gman sync will sync with all configured stores.

Run Configurations

Run configurations (or "profiles") tell gman how to inject secrets into a command. Three modes of secret injection are supported:

1. Environment Variables (default)
2. Command-Line Flags
3. Files

When you wrap a command with gman and don't specify a specific run configuration via --profile, gman will look for a profile with a name matching <command>. If found, it injects the specified secrets. If no profile is found, gman will error out and report that it could not find the run config with that name.

You can manually specify which run configuration to use with the --profile flag. Again, if no profile is found with that name, gman will error out.

Specifying a Default Provider per Run Config

All run configs also support the provider field, which lets you override the default provider for that specific profile. This is useful if you have multiple providers configured and want to use a different one for a specific command , but that provider may not be the default_provider, and you don't want to have to specify --provider on the command line every time.

For Example:

default_provider: local
run_configs:
  # `gman aws ...` uses the `aws` provider instead of `local` if no
  # `--provider` is given.
  - name: aws
    # Can be overridden by explicitly specifying a `--provider`
    provider: aws
    secrets:
      - DB_USERNAME
      - DB_PASSWORD
  # `gman docker ...` uses the default_provider `local` because no 
  # `provider` is specified.
  - name: docker
    secrets:
      - MY_APP_API_KEY
      - MY_APP_DB_PASSWORD
  # `gman managarr ...` uses the `local` provider; This is useful 
  # if you change the default provider to something else.
  - name: managarr
    provider: local
    secrets:
      - RADARR_API_KEY
      - SONARR_API_KEY
    files:
      - /home/user/.config/managarr/config.yml

Important Note: Any run config with a provider field can be overridden by specifying --provider on the command line.

Environment Variable Secret Injection

By default, secrets are injected as environment variables. The two required fields are name and secrets.

Example: A profile for the aws CLI.

run_configs:
  - name: aws
    secrets:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY

When you run gman aws ..., gman will fetch these two secrets and expose them as environment variables to the aws process.

Inject Secrets via Command-Line Flags

For applications that don't read environment variables, you can configure gman to pass secrets as command-line flags. This requires three additional fields: flag, flag_position, and arg_format.

• flag: The flag to use (e.g., -e).
• flag_position: An integer indicating where to insert the flag in the command's arguments. 1 is immediately after the command name.
• arg_format: A string that defines how the secret is formatted. It must contain the placeholders {{key}} and {{value}}.

Example: A profile for docker run that uses the -e flag.

run_configs:
  - name: docker
    secrets:
      - MY_APP_API_KEY
      - MY_APP_DB_PASSWORD
    flag: -e
    flag_position: 2 # In 'docker run ...', the flag comes after 'run', so position 2.
    arg_format: "{{key}}={{value}}"

When you run gman docker run my-image, gman will execute a command similar to: docker run -e MY_APP_API_KEY=... -e MY_APP_DB_PASSWORD=... my-image

Inject Secrets into Files

For applications that require secrets to be provided via files, you can configure gman to automatically populate specified files with the secret values before executing the command, run the command, and then restore the original content regardless of command completion status.

This just requires one additional field:

• files: A list of absolute file paths where the secret values should be written.

Example: An implicit profile for managarr that injects the specified secrets into the corresponding configuration file. More than one file can be specified, and if gman can't find any specified secrets, it will leave the file unchanged.

run_configs:
  - name: managarr
    secrets:
      - RADARR_API_KEY
      - SONARR_API_KEY
    files:
      - /home/user/.config/managarr/config.yml

And this is what my managarr configuration file looks like:

radarr:
  - name: Radarr
    host: 192.168.0.105
    port: 7878
    api_token: '{{RADARR_API_KEY}}' # This will be replaced by gman with the actual secret value
sonarr:
  - name: Sonarr
    host: 192.168.0.105
    port: 8989
    api_token: '{{SONARR_API_KEY}}'

Then, all you need to do to run managarr with the secrets injected is:

gman managarr

Detailed Usage

Storing and Managing Secrets

• Add a secret:

  # The value is read from standard input
  echo "your-secret-value" | gman add my_api_key
  

  or don't provide a value to add the secret interactively:

  gman add my_api_key
  

• Retrieve a secret:

  gman get my_api_key
  

• Update a secret:

  echo "new-secret-value" | gman update my_api_key
  

  or don't provide a value to update the secret interactively:

  gman add my_api_key
  

• List all secret names:

  gman list
  

• Delete a secret:

  gman delete my_api_key
  

• Synchronize with remote secret storage (specific to the configured provider):

  gman sync
  

Running Commands

• Using a default profile:

  # If an 'aws' profile exists, secrets are injected.
  gman aws sts get-caller-identity
  

• Specifying a profile:

  # Manually specify which profile to use with --profile
  gman --profile my-docker-profile docker run my-app
  

• Dry Run:

  # See what command would be executed without running it.
  gman --dry-run aws s3 ls
  # Output will show: aws -e AWS_ACCESS_KEY_ID=***** ... s3 ls
  

Multiple Providers and Switching

You can define multiple providers—even multiple of the same type—and switch between them per command.

Example: two AWS Secrets Manager providers named lab and prod.

default_provider: prod
providers:
  - name: lab
    type: local
    password_file: /home/user/.lab_gman_password
    git_branch: main
    git_remote_url: git@github.com:username/lab-vault.git

  - name: prod
    type: local
    password_file: /home/user/.prod_gman_password
    git_branch: main
    git_remote_url: git@github.com:username/prod-vault.git

run_configs:
  - name: aws
    secrets:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY

Switch providers on the fly using the provider name defined in providers:

# Use the default (prod)
gman aws s3 ls

# Explicitly use lab
gman --provider lab aws s3 ls

# Fetch a secret from prod
gman get my_api_key

# Fetch a secret from lab
gman --provider lab get my_api_key

Creator

• Alex Clarke