Crate murk_cli 

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

This library provides the core functionality for murk: vault I/O, age encryption, BIP39 key recovery, and secret management. The CLI binary wraps this library.

Re-exports

pub use error::MurkError;

pub use github::GitHubError;

pub use github::fetch_keys;

pub use crypto::MurkIdentity;

pub use crypto::MurkRecipient;

Modules

cli

CLI command model: the clap Parser/Subcommand types.

connect

Wiring murk mcp into AI-editor MCP client configs — the engine behind murk agent connect / murk agent disconnect.

crypto

edit

Edit buffer parsing and diff logic for murk edit.

error

Unified error type for the murk library.

github

GitHub SSH key fetching for murk authorize github:username.

hardening

Process hardening: best-effort defense-in-depth measures.

pins

Trust-on-first-use pinning of a vault’s signer registry.

recovery

scan

Scan files for leaked secret values.

signing

Ed25519 signatures over the vault — integrity against an active attacker with write access to the repo.

types

vault

Structs

AgentPlan

Schema-only view of a vault, suitable for agent prompt context.

AgentPlanKey

One key in the schema. Mirrors info::InfoEntry minus any field that names a recipient or carries recipient-derived metadata.

DiffEntry

A single entry in a secret diff.

DiscoveredKey

A key discovered from the environment or .env file.

InfoEntry

A single key entry in the vault info output.

InitStatus

Status of an existing vault relative to a given key.

MergeDriverOutput

Output of the merge driver: the merge result and whether meta was regenerated.

RecipientEntry

A single recipient entry with resolved display info.

RevokeResult

Result of revoking a recipient.

VaultInfo

Aggregated vault information for display.

Enums

CommitSignature

Signature status of the most recent commit that modified path.

DiffKind

The kind of change in a diff entry.

EnvrcStatus

Status of .envrc after writing.

KeySource

Where the resolved key came from.

MergeDriverSetupStep

A step completed during merge driver setup.

RotationIssue

A rotation-hygiene problem found by rotation_health.

Constants

EXPIRY_WARN_DAYS

Days of lead time before a hard expires_at is flagged as “expiring soon”.

Functions

add_grouped_secret

Add or update a secret encrypted to a named group. The operator must be a member of the group (so they can read it and re-encrypt it later). Assigning a secret to a group makes the group its sole base tier: any existing shared value and other group assignments are dropped so non-members can’t read it. Returns true if the key was new (no existing schema entry).

add_member

Add a member to a group. The group must exist, the operator must already be a member (so they can re-encrypt the group’s secrets), and the new member must be an authorized recipient. Returns true if the member was added (false if already present).

add_secret

Add or update a secret in the working state. If scoped is true, stores in scoped (encrypted to self only). Returns true if the key was new (no existing schema entry).

agent_key_file_path

Compute the file path for an agent grant key: ~/.config/murk/agent-keys/<vault-hash>-<name>.

agent_keys_dir

Return ~/.config/murk/agent-keys/, creating it if needed (dir 0700).

agent_plan

Build an AgentPlan from a vault’s schema. If tags is non-empty an entry is included only when it carries one of the requested tags.

authorize_recipient

Add a recipient to the vault. Returns an error if the pubkey is invalid or already present.

check_agent_keys

Check that every key in keys is permitted to agents by the vault’s policy.

check_init_status

Check whether a secret key is authorized in an existing vault.

create_grant

Create an agent grant in the working state. The caller mints the ephemeral identity, adds agent_pubkey to the vault recipients, and registers its display name before calling this. Encrypts a private copy of each scope key’s shared value to the agent and records the grant metadata.

create_group

Create a new empty group, seeded with the creator as its first member so they can always read and re-encrypt it. Errors if the name is invalid or the group already exists.

create_vault

Create a new vault with a single recipient.

decrypt_meta

Decrypt the meta blob from a vault, returning the deserialized Meta if possible.

decrypt_value

Decrypt a base64-encoded ciphertext and return plaintext bytes.

decrypt_vault

Decrypt a vault using the given identity. Verifies integrity, decrypts all shared and scoped values, and returns the working state.

decrypt_vault_values

Decrypt all shared secret values from a vault.

delete_group

Delete a group. Refuses if any secret is still assigned to it — the caller should reassign or remove those secrets first, so no data is silently orphaned (group ciphertext would become unreadable).

describe_key

Update a key’s plaintext schema metadata.

diff_secrets

Compare two sets of secret values and return the differences.

discover_existing_key

Try to find an existing age key from the environment.

dotenv_has_murk_key

Check whether .env already contains a MURK_KEY line.

encrypt_value

Encrypt a value and return base64-encoded ciphertext.

enforce_agent_policy

Apply check_agent_keys when the caller is a granted agent, or when the operator has opted into self-scope (crate::hardening::self_scope).

export_secrets

Build shell-escaped export key-value pairs for eval $(murk export). Wraps values in single quotes with embedded quote escaping.

format_agent_plan_text

Format an AgentPlan as plain text (no ANSI). Columns are aligned.

format_diff_lines

Format diff entries as display lines. Returns plain-text lines (no ANSI colors) suitable for testing.

format_info_lines

Format vault info as plain-text lines (no ANSI colors). has_meta indicates whether scoped/tag columns should be shown.

format_recipient_lines

Group recipient entries by display name and format for display. Returns plain-text lines (no ANSI colors).

get_secret

Look up a decrypted value. Resolution order, highest priority first: a personal scoped override, then a named-group value we can read, then the shared (everyone) value.

import_secrets

Import multiple secrets at once.

is_agent_identity

True when pubkey identifies a granted agent for this decrypted vault state.

is_agent_key_allowed

Whether key may be read under the agent allow-tag policy: always true when the vault has no policy, otherwise true only if the key carries an allowed tag. The public, per-key form of check_agent_keys, used by self-scope filtering (e.g. murk export).

is_valid_key_name

Check whether a key name is a valid shell identifier (safe for export KEY=...). Must start with a letter or underscore, and contain only [A-Za-z0-9_].

key_file_path

Compute the key file path for a vault: ~/.config/murk/keys/<hash>.

key_type_label

Return the key type label for a pubkey string.

last_commit_signature

Return the signature status of the last commit touching path, or None when git is unavailable, the repo has no such commit, or the path is untracked — i.e. there is no git anchor to check.

lifecycle_segment

Build the at-a-glance lifecycle segment shown after each info row, e.g. rotate 90d expires 2026-09-01. Returns an empty string when neither is set. The expiry is shown as a bare date (the stored time is end-of-day). Public schema, so this renders without a key — same as tags.

list_keys

Return key names from the vault schema, optionally filtered by tags.

list_recipients

List all recipients in the vault with optional name resolution.

load_vault

Resolve the key from the environment, read the vault, and decrypt it.

mark_revoked

Mark keys as owing a post-revoke rotation, stamping each with revoked_at.

parse_and_decrypt_values

Parse a vault from its JSON string and decrypt all shared values.

parse_env

Parse a .env file into key-value pairs. Skips comments, blank lines, MURK_* keys, and strips quotes and export prefixes.

parse_ttl

Parse a TTL like 90s, 30m, 2h, or 7d into a Duration. A bare number is rejected — the unit must be explicit so 2 is never ambiguous.

read_vault

Read a vault file from disk.

remove_grant

Remove a grant by name, returning its metadata so the caller can revoke the agent recipient (which clears its private entries) and rotate the scope.

remove_member

Remove a member from a group. The operator must be a member. Refuses to remove the last member (the group’s secrets would become unreadable). Returns true if the member was removed (false if not present).

remove_secret

Remove a secret from the working state and schema.

resolve_key

Resolve the secret key, checking in order:

resolve_key_for_vault

Resolve the secret key for a specific vault.

resolve_key_with_source

Resolve the secret key and report where it came from.

resolve_member

Resolve a member spec (a pubkey or a display name) to a recipient pubkey. The result must be an authorized recipient of the vault.

resolve_secrets

Merge private overrides over shared values and filter by tag. Returns raw (unescaped) values suitable for env var injection.

resolve_vault_path

Resolve a vault path argument, walking up parent directories to discover the vault.

revoke_recipient

Remove a recipient from the vault. recipient can be a pubkey or a display name.

rotation_health

Evaluate per-key rotation hygiene against now.

run_merge_driver

Run the three-way merge driver on vault contents (as strings).

save_vault

Save the vault: compare against original state and only re-encrypt changed values. Unchanged values keep their original ciphertext for minimal git diffs.

setup_merge_driver

Configure git to use murk’s custom merge driver for .murk files.

truncate_pubkey

Truncate a pubkey for display, keeping start and end.

validate_grant_name

Validate a grant name: 1–64 chars of [A-Za-z0-9_-].

validate_group_name

Validate a group name: 1–64 chars of [A-Za-z0-9_-], not reserved.

vault_info

Compute vault info from raw vault bytes.

warn_env_permissions

Warn if .env has loose permissions (Unix only).

write_envrc

Write a .envrc file for direnv integration.

write_key_ref_to_dotenv

Write a MURK_KEY_FILE reference to .env, removing any existing MURK_KEY/MURK_KEY_FILE lines.

write_key_to_dotenv

Write a MURK_KEY to .env, removing any existing MURK_KEY lines. On Unix, sets file permissions to 600 atomically at creation time to prevent a TOCTOU window where the secret key is world-readable. On non-Unix platforms, permissions are not hardened.

write_key_to_file

Write a secret key to a file with restricted permissions.