secretpath

secretpath resolves application secrets from a short, explicit provider path:

1. 1Password CLI references through op read
2. Environment variables

It is designed for CLIs and local automation that should prefer 1Password when available, fall back to environment variables when appropriate, and report where the secret came from without logging the secret itself.

secretpath never writes resolved secret values to disk. Its cache is process-local memory only.

Install

pip install secretpath

For local development:

uv sync
uv run pytest
uv run ruff check src tests

Quick Start

from secretpath import resolve_secret

result = resolve_secret(
    "Canvas API key",
    provider="auto",
    op_reference="op://Vault/Canvas/credential",
    env_var="CANVAS_API_KEY",
)

api_key = result.value
print(f"Using API key from {result.source}")

Use environment variables to avoid putting op://... references in project files:

result = resolve_secret(
    "ANTHROPIC_API_KEY",
    provider_env="MYAPP_SECRET_PROVIDER",
    op_reference_env="MYAPP_ANTHROPIC_API_KEY_OP_REFERENCE",
)

For prefix-based project conventions:

from secretpath import resolve_env_secret

result = resolve_env_secret("ANTHROPIC_API_KEY", prefix="PIPYER")

That reads:

• PIPYER_SECRET_PROVIDER
• PIPYER_ANTHROPIC_API_KEY_OP_REFERENCE
• ANTHROPIC_API_KEY

For application doctor commands, reuse the same sanitized setup diagnostics as the CLI:

from secretpath import doctor_report

payload = doctor_report(check_resolution=True)

The payload reports provider availability, config files, permissions, configured secret names, optional resolution status, and issues without resolved secret values or direct op://... references.

Named Config

Local .secretpath.toml and global ~/.config/secretpath/config.toml files can store secret lookup metadata. They should contain references and environment variable names, not resolved secret values.

[defaults]
provider = "auto"

[secrets.canvas]
env_var = "CANVAS_API_KEY"
op_reference = "op://Vault/Canvas/credential"

[secrets.anthropic]
env_var = "ANTHROPIC_API_KEY"
op_reference_env = "MYAPP_ANTHROPIC_API_KEY_OP_REFERENCE"

Then:

from secretpath import resolve_named_secret

result = resolve_named_secret("canvas")

See docs/config.md for precedence and file discovery.

CLI

The CLI checks whether a secret resolves without printing the secret:

secretpath check canvas
sp check canvas
secretpath check canvas --json
secretpath list
secretpath config path
secretpath config init
secretpath config show
secretpath doctor
secretpath doctor --check
sp direnv init openai anthropic
secretpath check ANTHROPIC_API_KEY --prefix PIPYER
secretpath check API_KEY --no-config --env-var API_KEY
python -m secretpath check canvas

sp is a short alias for the secretpath command.

See docs/cli.md.

Behavior

• provider="auto" tries 1password first, then env.
• provider="1password" only tries op read.
• provider="env" only reads the environment variable.
• env_var defaults to name.
• environment-sourced results report env:<env_var>, such as env:CANVAS_API_KEY.
• required=False returns a SecretMiss with non-secret attempt metadata.
• resolved values are cached in process memory by default.
• clear_cache() clears the process-local cache.
• clear_cache(name) clears entries for one logical secret name.

Error messages name providers tried, but intentionally avoid including op://... references, environment variable names, raw op stderr, or secret values.

Documentation

• API reference
• Configuration files
• CLI usage
• Integration patterns
• Security model

Why No Durable Secret Cache?

secretpath treats 1Password or the environment as the durable authority. A disk cache would create another secret store with weaker rotation and audit semantics. The built-in cache is intentionally limited to the current Python process.