Passlane

Use passlane (a Keepass-backed password manager + authenticator CLI) to retrieve credentials, payment cards, secure notes, and generate TOTP codes for automation — e.g. programmatically logging into websites and APIs. Use when the user wants to script a login, fetch a password or 2FA code from their vault, audit stored credentials, or build automations that authenticate using passlane.

passlane is a command-line password manager and authenticator that stores data in the Keepass encrypted format. It holds credentials (service/username/password), payment cards, secure notes, and TOTP authenticators (time-based 2FA codes). It exposes scripting-friendly output (--json, --out, --once, --code) so agents can read secrets and feed them into automations without touching the clipboard or any interactive UI.

There are two separate vaults, each with its own master password:

• the main vault — credentials, payment cards, secure notes
• the TOTP vault — authenticator secrets (addressed with the -o flag on most commands)

Prerequisite: the vault must be unlocked

Non-interactive use requires the master password to be stored in the OS keychain. The user runs these one-time, interactive setup commands themselves:

passlane unlock      # store the main vault master password in the OS keychain
passlane unlock -o   # store the TOTP vault master password in the OS keychain
passlane lock        # remove stored master passwords (re-locks)

There is no environment variable or stdin to supply the master password. If the vault is locked, passlane will block on an interactive prompt — which hangs unattended automation. So:

If a passlane command blocks or fails because the vault is locked, stop and ask the user to run passlane unlock (and passlane unlock -o for 2FA codes). Do not try to supply the master password yourself.

Reading secrets (the core of automation)

Two commands are built for scripts and print to stdout:

passlane list [REGEXP] [--json] [-v]

Machine-readable listing. Default lists credentials; add a type flag to list something else: -p payment cards, -n notes, -o TOTP entries. An optional REGEXP filters by service/issuer.

• passlane list --json — JSON envelope (best for parsing with jq).
• passlane list github --json — only entries matching github.
• passlane list -v — plain text including passwords.

WARNING: list --json and list -v print passwords in cleartext to stdout. Default plain list (no -v) shows service/username/note only — no password.

passlane show <REGEXP> --out

Print a single matched password to stdout — no clipboard, no countdown, exits immediately. Use this when you need exactly one secret.

passlane show '^github\.com$' --out

Rule of thumb: use list --json | jq for structured extraction or multiple fields; use show --out for one password.

JSON output reference

Every --json response is an envelope:

{ "type": "credentials", "count": 2, "entries": [ ... ] }

Entry fields by type:

type	entry fields
credentials	uuid, service, username, password, note (optional), last_modified
payment_cards	id, name, name_on_card, number, cvv, expiry ({month, year}), color?, billing_address?, last_modified
notes	id, title, content, last_modified
totp	id, label, issuer, secret, algorithm, period, digits, last_modified
totp_codes	label, issuer, code, valid_for_seconds — never includes the stored secret

TOTP / 2FA codes

Most logins need a fresh time-based code. Two ways to get one:

passlane show -o --once <REGEXP> — recommended for a single code

Prints the one matching current code to stdout and exits.

passlane show -o --once github   # -> 447091

• Zero matches → exit code 1, stderr: No matching OTP authorizer found.
• Multiple matches → exit code 1, stderr: Multiple OTP authorizers match: <labels>. Refine the search pattern to match exactly one.

Because ambiguity is an error, anchor your pattern (e.g. '^GitHub$') so it matches exactly one authorizer.

passlane list -o --code [REGEXP] [--json] — multiple codes / expiry window

Outputs the current code for every matching authorizer. With --json, each entry includes valid_for_seconds so you know how long the code stays valid.

passlane list -o --code --json

TOTP codes are valid only for a few seconds. Fetch them just before use and never cache them. Re-fetch on each retry.

Other commands

Command	Notes
passlane gen [--out]	Generate a random password. --out prints to stdout (otherwise copies to clipboard).
passlane add [-p|-n|-o] [-g] [-l]	Add a credential/card/note/TOTP. Interactive (prompts).
passlane edit <REGEXP> [-p|-n|-o]	Edit an entry. Interactive.
passlane delete <REGEXP> [-c|-p|-n|-o]	Delete entries. Interactive.
passlane csv <FILE>	Import credentials from a CSV file.
passlane export [-p|-n|-o] <FILE>	Export the vault to CSV.
passlane passwd [-o]	Change a vault's master password. Interactive.
passlane completions [SHELL]	Generate shell completions (bash/zsh/fish).
passlane init	First-time setup. Interactive.
passlane repl	Interactive REPL (also launched by running passlane with no args).

add, edit, delete, passwd, init, and repl are prompt-driven and not suited to unattended automation — only the reading commands above are.

Safety rules

• Never echo retrieved passwords or TOTP codes into chat, logs, or files you commit.
• Pipe secrets directly into the consuming command, or capture into a shell variable with VAR=$(passlane ...) — avoid inlining a secret into a command line where it lands in shell history or process listings.
• Fetch TOTP codes just-in-time, immediately before the request that uses them.
• Match patterns precisely (anchored regex) so show -o --once and show --out resolve to exactly one entry.
• Treat exit code 1 as actionable: a locked vault, no match, or ambiguous match. Check it and react rather than proceeding with empty output.

Worked examples

For ready-to-adapt scripts — API login with basic auth + TOTP, single-secret extraction, browser login combined with the playwright-cli skill, and a read-only credential audit — read references/automation-examples.md when you are actually building an automation.