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.

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.