Skip to content

CLI reference

This document contains the help content for the murk command-line program.

These rules hold for every command.

  • Vault. A command that reads a vault takes --vault <VAULT>. The default is .murk. The environment variable MURK_VAULT sets the same option, and the flag wins when both are set.
  • Finding the vault. A bare name such as .murk is looked up in the current directory first. If it is not there, murk searches the parent directories, up to the git root or HOME, whichever comes first. It does not search when the working directory is under neither. A name with a path separator is used as written. murk init and murk env always use the name as written.
  • Repeatable flags. A flag marked “(repeatable)” can appear more than once, as in --tag a --tag b.
  • Exit codes. 0 is success. 1 is a failure, or an unresolved warning from a check command such as murk verify, murk doctor or murk scan. 2 is a usage error: the arguments are invalid, so murk did nothing. murk exec and murk agent exec exit with the status of the command they run.
  • Options before the command. murk exec and murk agent exec pass everything after the command name to the command. Put murk options such as --only and --vault before it. murk exec echo hi --only FOO runs echo hi --only FOO and injects every secret.

Command Overview:

Encrypted secrets manager for developers: one file, age encryption, git-friendly

Usage: murk <COMMAND>

  • init — Initialize a vault or reuse its existing key
  • env — Write a .envrc for direnv integration
  • restore — Print the key encoded by a BIP39 recovery phrase (saves nothing)
  • recover — Print the BIP39 recovery phrase for your age key
  • add — Add or update a secret
  • generate — Generate a random secret and store it
  • rotate — Rotate secrets with new values
  • rm — Remove a secret
  • get — Get a single decrypted value
  • edit — Edit secrets in $EDITOR (experimental)
  • ls — List all secret names
  • export — Export all secrets as shell export statements
  • import — Import secrets from a .env file
  • describe — Set a secret’s description, example, tags and rotation or expiry policy
  • info — Show public schema and key info
  • skeleton — Export schema-only vault with no secrets or recipients
  • exec — Run a command with secrets injected as environment variables
  • agent — Give AI agents scoped, time-limited access to secrets (experimental)
  • mcp — Run an MCP (Model Context Protocol) stdio server for AI agents (experimental)
  • policy — Manage the agent access policy (experimental)
  • circle — Manage recipients
  • group — Manage recipient groups (experimental)
  • verify — Verify vault integrity without exporting secrets
  • trust — Review who signed the vault and what changed, then trust it on this machine
  • doctor — Check the surrounding repo for hygiene issues
  • scan — Scan files for leaked secret values
  • diff — Show secret and access changes vs a git ref (experimental)
  • setup-merge-driver — Configure git to use murk’s merge driver for vault files named *.murk or .murk.* (experimental)
  • completion — Generate or install shell completions

Initialize a vault or reuse its existing key

Usage: murk init [OPTIONS]

  • --vault <VAULT> — Vault filename

    Default value: .murk

  • --reuse-key — When another vault in this directory already has a key stored on this machine, store that key for this vault too, without asking

  • --separate-key — When another vault in this directory already has a key stored on this machine, make a new key for this vault, without asking

Write a .envrc for direnv integration

Creates .envrc in the current directory with a line that runs murk export. If .envrc already exists, murk appends the line. If it already has a murk export line, murk changes nothing. Run direnv allow afterward.

Usage: murk env [OPTIONS]

  • --vault <VAULT> — Vault filename

    Default value: .murk

Print the key encoded by a BIP39 recovery phrase (saves nothing)

Usage: murk restore [OPTIONS]

  • --vault <VAULT> — Vault filename, for the restored-identity recipient check

    Default value: .murk

Print the BIP39 recovery phrase for your age key

murk uses the key from MURK_KEY, MURK_KEY_FILE or the stored key for .murk. SSH keys and plugin identities have no recovery phrase.

Usage: murk recover

Add or update a secret

On a terminal, murk asks for the value with a hidden prompt. When stdin is piped, murk reads all of it as the value and drops one trailing newline.

Usage: murk add [OPTIONS] <KEY>

  • <KEY> — Name of the secret
  • --desc <DESC> — Description of the secret

  • --example <EXAMPLE> — Example value

  • --group <GROUP> — Who can read the secret: everyone, me (a private value for you only) or a group name (experimental). Omit it to keep an existing secret’s tier. A new secret is shared with everyone

  • --tag <TAG> — Tag for grouping (repeatable)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Generate a random secret and store it

Usage: murk generate [OPTIONS] <KEY>

  • <KEY> — Name of the secret
  • --length <LENGTH> — Length in bytes

    Default value: 32

  • --hex — Encode the value as hex instead of URL-safe base64

  • --desc <DESC> — Description of the secret

  • --example <EXAMPLE> — Example value

  • --group <GROUP> — Who can read the secret: everyone, me (a private value for you only) or a group name (experimental). Omit it to keep an existing secret’s tier. A new secret is shared with everyone

  • --tag <TAG> — Tag for grouping (repeatable)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Rotate secrets with new values

New values come from a hidden prompt on a terminal, or from piped stdin. With a KEY, murk reads all of stdin as the value. With --all, it reads one line per secret, in name order. --generate and --values-from supply values another way. murk refuses --generate with --all.

Usage: murk rotate [OPTIONS] [KEY]

  • <KEY> — Secret to rotate. Omit it when you use --all
  • --all — Rotate all secrets in the vault

  • --generate — Generate random values instead of prompting (refused with --all)

  • --length <LENGTH> — Length in bytes for generated values

    Default value: 32

  • --hex — Encode generated values as hex instead of URL-safe base64

  • --values-from <FILE> — Read new values from a dotenv file of KEY=value lines (- for stdin), matched by secret name

  • --list — List the secrets that need rotation instead of rotating (exits 1 if any do)

  • --json — Print the listing as a JSON object with verified and issues. The exit code is then 0 even when secrets need rotation

  • --vault <VAULT> — Vault filename

    Default value: .murk

Remove a secret

Usage: murk rm [OPTIONS] <KEY>

  • <KEY> — Name of the secret
  • --vault <VAULT> — Vault filename

    Default value: .murk

Get a single decrypted value

Usage: murk get [OPTIONS] <KEY>

  • <KEY> — Name of the secret
  • --vault <VAULT> — Vault filename

    Default value: .murk

Edit secrets in $EDITOR (experimental)

Usage: murk edit [OPTIONS] [KEY]

  • <KEY> — Edit one secret. Omit it to edit all
  • --scoped — Deprecated alias for --group me. Edits your private values instead of shared secrets

  • --group <GROUP> — Edit this group’s values instead of shared secrets. me means your private values. A group name is experimental

  • --vault <VAULT> — Vault filename

    Default value: .murk

List all secret names

Usage: murk ls [OPTIONS]

  • --tag <TAG> — Filter by tag (repeatable)

  • --json — Output as JSON

  • --vault <VAULT> — Vault filename

    Default value: .murk

Export all secrets as shell export statements

Usage: murk export [OPTIONS]

  • --tag <TAG> — Filter by tag (repeatable)

  • --json — Output as JSON

  • --allow-reserved — Allow secrets named like loader, shell or tool variables (PATH, LD_, GIT_, MURK_*, …)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Import secrets from a .env file

Usage: murk import [OPTIONS] [FILE]

  • <FILE> — Path to the .env file to import

    Default value: .env

  • --force — Overwrite existing secrets. Without it, import stops if any secret already exists

  • --group <GROUP> — Who can read the imported secrets: everyone, me (private values for you only) or a group name (experimental). Omit it to keep each existing secret’s tier. New secrets are shared with everyone

  • --example <EXAMPLE> — Example value applied to every imported secret

  • --vault <VAULT> — Vault filename

    Default value: .murk

Set a secret’s description, example, tags and rotation or expiry policy

Each call replaces the description. It also replaces the example: omitting --example clears it. --tag replaces the tags only when given. --rotate-every and --expires change only when given.

Usage: murk describe [OPTIONS] <KEY> <DESCRIPTION>

  • <KEY> — Name of the secret
  • <DESCRIPTION> — Description text (replaces the current one)
  • --example <EXAMPLE> — Example value. Omitting it clears the current example

  • --tag <TAG> — Tag for grouping (repeatable, replaces existing tags)

  • --rotate-every <DAYS> — Rotation interval, e.g. 90d or 90 (days). never clears it

  • --expires <DATE> — Hard expiry date, e.g. 2026-09-01. never clears it

  • --vault <VAULT> — Vault filename

    Default value: .murk

Show public schema and key info

Usage: murk info [OPTIONS]

  • --tag <TAG> — Filter by tag (repeatable)

  • --json — Output as JSON

  • --vault <VAULT> — Vault filename

    Default value: .murk

Export schema-only vault with no secrets or recipients

Usage: murk skeleton [OPTIONS]

  • -o, --output <OUTPUT> — New output file. murk refuses a path that already exists. Without this option, murk prints to stdout

  • --vault <VAULT> — Vault filename

    Default value: .murk

Run a command with secrets injected as environment variables

Usage: murk exec [OPTIONS] <COMMAND>...

  • <COMMAND> — Command and arguments to run

    Put murk options such as --only before the command. murk passes everything after the command name to the command, so murk exec echo hi --only FOO runs echo hi --only FOO and injects every secret.

  • --only <ONLY> — Inject only these secrets (repeatable)

  • --tag <TAG> — Filter by tag (repeatable)

  • --clean-env — Start the command with only the injected secrets plus PATH, HOME and TERM on Unix

    On Windows, murk keeps PATH and a fixed set of system variables.

  • --allow-reserved — Allow secrets named like loader, shell or tool variables (PATH, LD_, GIT_, MURK_*, …)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Give AI agents scoped, time-limited access to secrets (experimental)

Usage: murk agent <COMMAND>

  • plan — Emit schema-only context safe to paste into an AI agent prompt (experimental)
  • exec — Run a command with strict agent-safe defaults (experimental)
  • grant — Mint a scoped ephemeral key that can read only the named secrets (experimental)
  • init — Mint a scoped grant and print how to run the agent safely (experimental)
  • ls — List active agent grants and their TTLs (experimental)
  • revoke — Revoke an agent grant (experimental)
  • connect — Add murk mcp to an AI client’s MCP config and mint a scoped grant for it (experimental)
  • disconnect — Remove murk’s entry from an AI editor’s MCP config (experimental)

Emit schema-only context safe to paste into an AI agent prompt (experimental)

Usage: murk agent plan [OPTIONS]

  • --tag <TAG> — Filter by tag (repeatable)

  • --json — Output as JSON

  • -o, --output <OUTPUT> — New output file. murk refuses a path that already exists. Without this option, murk prints to stdout

  • --vault <VAULT> — Vault filename

    Default value: .murk

Run a command with strict agent-safe defaults (experimental)

On Unix the command keeps only PATH, HOME and TERM from the inherited environment. On Windows it keeps PATH and a fixed set of system variables. murk strips MURK_KEY, requires --only and masks the injected values in the output.

Usage: murk agent exec [OPTIONS] --only <ONLY> <COMMAND>...

  • <COMMAND> — Command and arguments to run

    Put murk options such as --only before the command. murk passes everything after the command name to the command, so murk agent exec echo hi --only FOO fails with a missing --only.

  • --only <ONLY> — Inject only these secrets (repeatable, required)

  • --allow-operator-key — Decrypt with a key that is not an agent grant: your own stored key from ~/.config/murk/keys, or a full recipient’s MURK_KEY or MURK_KEY_FILE. Without this, agent exec needs an agent grant key

  • --allow-reserved — Allow secrets named like loader, shell or tool variables (PATH, LD_, GIT_, MURK_*, …)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Mint a scoped ephemeral key that can read only the named secrets (experimental)

Usage: murk agent grant [OPTIONS] --name <NAME> --only <ONLY>

  • --name <NAME> — Grant name (used to revoke it later)

  • --only <ONLY> — Secrets this grant can read (repeatable, required)

  • --ttl <TTL> — Time to live, e.g. 30m, 2h or 7d, up to 365d. Reads fail closed after expiry

    Default value: 2h

  • --renew — Replace the grant with this name: revoke its key, mint a fresh one. Without this, murk refuses a name that still has a grant record, and an expired grant keeps its record until the next vault write

  • --out <OUT> — Where to write the agent key: a path, or - for stdout

  • --force — Replace a file already at –out (refused by default)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Mint a scoped grant and print how to run the agent safely (experimental)

With --allow-tag, murk first sets the agent allow-list to those tags.

Usage: murk agent init [OPTIONS] --name <NAME> --only <ONLY>

  • --name <NAME> — Grant name (used to revoke it later)

  • --only <ONLY> — Secrets the agent can read (repeatable, required)

  • --allow-tag <ALLOW_TAG> — Set the agent allow-list to these tags before granting (repeatable)

  • --ttl <TTL> — Time to live, e.g. 30m, 2h or 7d, up to 365d. Reads fail closed after expiry

    Default value: 2h

  • --out <OUT> — Where to write the agent key: a path, or - for stdout

  • --force — Replace a file already at –out (refused by default)

  • --vault <VAULT> — Vault filename

    Default value: .murk

List active agent grants and their TTLs (experimental)

Usage: murk agent ls [OPTIONS]

  • --json — Output as JSON

  • --vault <VAULT> — Vault filename

    Default value: .murk

Revoke an agent grant (experimental)

The grant’s key can still decrypt old versions of the vault from git history, so rotate the secrets it could read: pass --rotate, or answer the prompt on a terminal.

Usage: murk agent revoke [OPTIONS] <NAME>

  • <NAME> — Grant name
  • --rotate — Rotate the secrets the grant could read, in the same run. murk stores a new value for each. It does not rotate them at the provider

  • --values-from <FILE> — With –rotate, read new values from a dotenv file of KEY=value lines (- for stdin)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Add murk mcp to an AI client’s MCP config and mint a scoped grant for it (experimental)

Usage: murk agent connect [OPTIONS] --only <ONLY> [CLIENT]

  • <CLIENT> — Client to configure: claude, cursor, vscode, zed, gemini, omp or codex. Omit it to configure every client that already has a config file or marker directory (such as .cursor/) next to the vault
  • --only <ONLY> — Secrets the agent may read (repeatable, required)

  • --allow-tag <ALLOW_TAG> — Set the agent allow-list to these tags before granting (repeatable)

  • --allow-exec — Also enable the murk_exec tool in the MCP server (writes --allow-exec into the client config)

  • --ttl <TTL> — Grant time to live, e.g. 30m, 2h or 7d, up to 365d. Reads fail closed after expiry

    Default value: 2h

  • --name <NAME> — Grant name (used to disconnect/revoke it later)

    Default value: mcp

  • --vault <VAULT> — Vault filename

    Default value: .murk

Remove murk’s entry from an AI editor’s MCP config (experimental)

With no CLIENT, murk clears every configured editor. The grant stays live unless you pass --rotate, which also revokes the grant named by --name and rotates the secrets it could read.

Usage: murk agent disconnect [OPTIONS] [CLIENT]

  • <CLIENT> — Editor to disconnect. Omit for every configured editor
  • --rotate — Revoke the grant and rotate the secrets it could read

  • --name <NAME> — Grant name to revoke with –rotate

    Default value: mcp

  • --vault <VAULT> — Vault filename

    Default value: .murk

Run an MCP (Model Context Protocol) stdio server for AI agents (experimental)

Usage: murk mcp [OPTIONS]

  • --vault <VAULT> — Vault filename

    Default value: .murk

  • --allow-exec — Enable the murk_exec tool, which runs commands with the grant’s secrets injected

    Off by default. The tool runs arbitrary commands as this user. The injected secrets are limited to the grant, but the command itself is not sandboxed.

Manage the agent access policy (experimental)

Usage: murk policy <COMMAND>

  • show — Show the agent access policy (works without a key)
  • set — Set the agent allow-list: agents may only receive secrets carrying one of these tags
  • clear — Remove the policy. Agent mode becomes unrestricted again

Show the agent access policy (works without a key)

Usage: murk policy show [OPTIONS]

  • --json — Output as JSON

  • --vault <VAULT> — Vault filename

    Default value: .murk

Set the agent allow-list: agents may only receive secrets carrying one of these tags

Usage: murk policy set [OPTIONS] --allow-tag <ALLOW_TAG>

  • --allow-tag <ALLOW_TAG> — Tag agents are allowed to receive (repeatable, required)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Remove the policy. Agent mode becomes unrestricted again

Usage: murk policy clear [OPTIONS]

  • --vault <VAULT> — Vault filename

    Default value: .murk

Manage recipients

With no subcommand, lists the vault’s recipients.

Usage: murk circle [OPTIONS] [COMMAND]

  • authorize — Add a recipient to the vault
  • revoke — Remove a recipient from the vault
  • --json — Output the recipient list as JSON

  • --vault <VAULT> — Vault filename

    Default value: .murk

Add a recipient to the vault

Usage: murk circle authorize [OPTIONS] <PUBKEY>

  • <PUBKEY> — Public key (age1…), ssh:path, ssh: (default ~/.ssh/id_ed25519.pub), or github:username (experimental)
  • --name <NAME> — Display name for this recipient

  • --group <GROUP> — Also add the new recipient to this group (experimental)

  • --force — Accept changed GitHub keys. Without it, authorize stops when a user’s keys differ from the pinned set

  • --allow-ssh-rsa — Allow ssh-rsa keys. They are refused or skipped by default, so prefer ed25519

  • --vault <VAULT> — Vault filename

    Default value: .murk

Remove a recipient from the vault

Usage: murk circle revoke [OPTIONS] <RECIPIENT>

  • <RECIPIENT> — Recipient pubkey, display name, or github:username
  • --rotate — Rotate the secrets they had access to in the same session

  • --values-from <FILE> — With –rotate, read new values from a dotenv file of KEY=value lines (- for stdin)

  • --force — Revoke every key of a multi-key GitHub user without confirmation

  • --vault <VAULT> — Vault filename

    Default value: .murk

Manage recipient groups (experimental)

Usage: murk group <COMMAND>

  • create — Create a new recipient group (you become its first member)
  • ls — List groups and their members
  • add — Add a member to a group
  • rm — Remove a member from a group, or delete the group entirely

Create a new recipient group (you become its first member)

Usage: murk group create [OPTIONS] <NAME>

  • <NAME> — Group name
  • --vault <VAULT> — Vault filename

    Default value: .murk

List groups and their members

Usage: murk group ls [OPTIONS]

  • --json — Output as JSON

  • --vault <VAULT> — Vault filename

    Default value: .murk

Add a member to a group

Usage: murk group add [OPTIONS] --member <MEMBER> <NAME>

  • <NAME> — Group name
  • --member <MEMBER> — Recipient pubkey or display name to add

  • --vault <VAULT> — Vault filename

    Default value: .murk

Remove a member from a group, or delete the group entirely

Usage: murk group rm [OPTIONS] <NAME>

  • <NAME> — Group name
  • --member <MEMBER> — Recipient pubkey or display name to remove (omit to delete the group)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Verify vault integrity without exporting secrets

Usage: murk verify [OPTIONS]

  • --vault <VAULT> — Vault filename

    Default value: .murk

Review who signed the vault and what changed, then trust it on this machine

Needed once per vault on a new clone, whenever a teammate’s first signed write arrives, and whenever murk refuses a vault (an unfamiliar signer, an unsigned or rolled-back vault). Shows the signer’s key and signing-key fingerprint, the recipient changes since this machine last trusted the vault, and asks before recording it. An unsigned vault is signed with your key.

Usage: murk trust [OPTIONS]

  • --yes — Accept without asking, for scripts. Review the vault first

  • --print-key — Print your own trusted-signer entry (for MURK_TRUSTED_SIGNERS) and signing-key fingerprint (for teammates to confirm), then exit

  • --re-add <KEY> — Trust a key this machine recorded as removed from the vault again (its public key, or its name in the vault). Repeat for each key. A vault signed by or listing a removed key is never trusted without it

  • --vault <VAULT> — Vault filename

    Default value: .murk

Check the surrounding repo for hygiene issues

Usage: murk doctor [OPTIONS]

  • --vault <VAULT> — Vault filename

    Default value: .murk

Scan files for leaked secret values

Usage: murk scan [OPTIONS] [PATHS]...

  • <PATHS> — Files or directories to scan (defaults to current directory)
  • --vault <VAULT> — Vault filename

    Default value: .murk

Show secret and access changes vs a git ref (experimental)

Lists recipients, signer, signing keys, policy, grants and group members that changed, then the secrets. The vault at the ref is verified first. murk never shows a revision that this machine’s trust pin refuses.

Usage: murk diff [OPTIONS] [GIT_REF]

  • <GIT_REF> — Git ref to compare against

    Default value: HEAD

  • --show-values — Show actual values (not just secret names)

  • --json — Output JSON: {“secrets”: […], “changes”: […]} (values only with –show-values)

  • --vault <VAULT> — Vault filename

    Default value: .murk

Configure git to use murk’s merge driver for vault files named *.murk or .murk.* (experimental)

Adds *.murk merge=murk and .murk.* merge=murk to the .gitattributes at the root of the working tree, and sets merge.murk.* in git config. Changes nothing when git config already sets a merge.murk.driver that murk did not write, or when the git attributes already give vault files another merge attribute.

The driver merges three sides that murk reads as vaults. It merges a file that cannot be a vault as text. When a side is or could be a vault but murk cannot read every side, the driver exits 1 and writes both sides into the file between conflict markers. Valid JSON could be a vault only when it has a top-level recipients, secrets, meta, vault_name or vault_id key. Other text could be a vault when it starts with { or uses one of these names as a JSON key.

Usage: murk setup-merge-driver

Generate or install shell completions

Usage: murk completion <COMMAND>

  • generate — Print completions to stdout
  • install — Install completions under your home directory

Print completions to stdout

Usage: murk completion generate <SHELL>

  • <SHELL> — Shell to generate completions for

    Possible values: bash, elvish, fish, powershell, zsh

Install completions under your home directory

Writes ~/.zfunc/_murk for zsh, ~/.local/share/bash-completion/completions/murk for bash, ~/.config/fish/completions/murk.fish for fish, ~/.config/elvish/lib/murk.elv for elvish and ~/.config/powershell/_murk.ps1 for PowerShell. It replaces a file that is already there and needs HOME. For zsh and bash, murk then prints the lines to add to your shell startup file.

Usage: murk completion install <SHELL>

  • <SHELL> — Shell to install completions for

    Possible values: bash, elvish, fish, powershell, zsh