passlane

intent

passlane is a command-line password manager and authenticator that stores data in keepass encrypted format. use it to retrieve credentials (service/username/password), payment cards, secure notes, and generate TOTP authenticator codes for unattended automation. reach for passlane when you need to script a login, fetch a password or 2FA code from a vault, audit stored credentials, or build automations that authenticate using stored secrets. the tool outputs machine-readable JSON and plaintext to stdout, making it suitable for piping into other commands or capturing into variables without touching the clipboard or interactive UI.

inputs

passlane CLI: must be installed and in PATH. (passlane --version to verify.)

two separate encrypted vaults, each requiring a master password:

• main vault: credentials, payment cards, secure notes
• TOTP vault: authenticator secrets (accessed with -o flag)

OS keychain integration: master passwords must be stored in the system keychain for non-interactive use. the user sets this up once with passlane unlock and passlane unlock -o. if vaults are locked, passlane will block on an interactive prompt and hang unattended automation.

external connection: none required beyond local vault files and OS keychain. passlane does not reach out to remote servers.

edge cases to handle:

• vault locked (missing keychain entry): passlane will prompt interactively and hang
• TOTP code expiry: codes are valid for only a few seconds; fetch just-in-time and re-fetch on retry
• network timeouts: not applicable; passlane is local-only
• rate limits: not applicable; passlane is local-only
• regex ambiguity: multiple matches on show --once or show --out will error with exit code 1
• zero matches: exit code 1, stderr message

procedure

step 1: verify vault unlock status

run passlane list --json with no arguments. if it prompts for a master password or errors with "vault locked", stop and ask the user to run passlane unlock (and passlane unlock -o if 2FA codes are needed). do not attempt to supply the master password yourself; there is no environment variable or stdin method.

input: passlane CLI, OS keychain state output: either JSON envelope or exit code 1 with stderr indicating lock status

step 2: list or search secrets (if multiple entries needed or audit required)

run passlane list [REGEXP] --json [-v] to retrieve structured data.

• passlane list --json lists all credentials
• passlane list github --json filters entries matching "github"
• passlane list -p --json lists payment cards
• passlane list -n --json lists secure notes
• passlane list -o --json lists TOTP authorizers (metadata only, secrets hidden)

input: optional REGEXP filter, vault type flag (-p, -n, -o) output: JSON envelope with type, count, and entries array; passwords included in plaintext only if -v flag is used

step 3a: retrieve a single password (recommended for one credential)

run passlane show '<REGEXP>' --out to print exactly one password to stdout.

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

use anchored regex (^...$) to guarantee a single match. if zero or multiple matches, exit code is 1 and stderr describes the problem.

input: REGEXP pattern (anchored recommended), --out flag output: password printed to stdout (no newline by default); exit code 0 on success, 1 on error

step 3b: retrieve a single TOTP code (recommended for one 2FA code)

run passlane show -o --once '<REGEXP>' to fetch the current time-based code.

passlane show -o --once '^GitHub$'

codes are valid only for seconds; fetch immediately before use.

input: REGEXP pattern (anchored), -o flag, --once flag output: 6-digit code (or configured digit count) to stdout; exit code 0 on success, 1 on zero or multiple matches

step 3c: retrieve multiple TOTP codes (if auditing or batch operations)

run passlane list -o --code --json to get all current codes with expiry information.

passlane list -o --code --json | jq '.entries[]'

each entry includes valid_for_seconds so you know how long each code remains valid. never cache TOTP codes; re-fetch on each use or retry.

input: -o flag, --code flag, --json flag output: JSON envelope with totp_codes type; entries include label, issuer, code, valid_for_seconds (secret never included)

step 4: parse and use the retrieved secret

capture the output into a shell variable or pipe directly to the consuming command. do not echo it to stdout, logs, or files that will be committed.

PASSWORD=$(passlane show '^api\.service$' --out)
curl -u "user:$PASSWORD" https://api.service.com/endpoint

# or pipe directly (preferred for sensitive data)
passlane show '^api\.service$' --out | xargs -I {} curl -u "user:{}" https://api.service.com/endpoint

input: output from step 2, 3a, 3b, or 3c output: secret injected into consuming command or stored in shell variable (never logged or echoed)

decision points

if vault is locked: stop immediately. ask the user to run passlane unlock (main vault) and passlane unlock -o (TOTP vault if needed). do not retry or supply a master password.

if you need multiple secrets or structured audit data: use passlane list --json [REGEXP] and pipe to jq for extraction. this is more efficient than calling show multiple times.

if you need exactly one password: use passlane show '<REGEXP>' --out. anchor the regex to guarantee a single match; if multiple match, the command fails with exit code 1.

if you need exactly one TOTP code: use passlane show -o --once '<REGEXP>'. must be anchored to match exactly one authorizer. if multiple match or none match, exit code is 1.

if you need multiple TOTP codes or must know expiry windows: use passlane list -o --code --json. codes are valid only for a few seconds, so fetch just before use and never cache.

if a read command exits with code 1: the vault is locked, the pattern matched zero entries, or the pattern is ambiguous (multiple matches). check stderr, refine your regex (anchor it), and retry, or ask the user to unlock the vault.

if you need to generate a random password programmatically: run passlane gen --out to stdout. this does not interact with the vault.

output contract

passlane list --json returns:

{
  "type": "credentials",
  "count": 2,
  "entries": [
    {
      "uuid": "...",
      "service": "github.com",
      "username": "user@example.com",
      "password": "...",
      "note": "...",
      "last_modified": "2024-01-15T10:30:00Z"
    }
  ]
}

passlane show --out returns: plaintext password to stdout (no trailing newline).

passlane show -o --once returns: 6-digit (or configured) TOTP code to stdout (no trailing newline).

passlane list -o --code --json returns:

{
  "type": "totp_codes",
  "count": 1,
  "entries": [
    {
      "label": "GitHub",
      "issuer": "github.com",
      "code": "447091",
      "valid_for_seconds": 27
    }
  ]
}

exit codes:

• 0: success
• 1: vault locked, no matches, ambiguous matches, or other error (check stderr)

no files created or modified unless explicitly running add, edit, delete, or export (which are interactive and not recommended for automation).

outcome signal

• success: command exits with code 0 and outputs plaintext (password, code, or JSON) to stdout. secret is captured in a variable or piped to the consuming command without being echoed.
• vault unlocked: first call to passlane list --json succeeds and returns entries without prompting.
• secret retrieved: password or TOTP code is correctly injected into the login request, API call, or downstream command and the authentication succeeds.
• TOTP code validity: code is used within the valid_for_seconds window and not cached or re-used across retries.
• failure mode is clear: if exit code is 1, stderr explicitly says whether the vault is locked, the pattern matched zero entries, or multiple entries matched. act on that feedback and retry or ask the user to unlock.

credits: original skill by passlane team. enriched and restructured per implexa standards.