SeedPass Advanced CLI and API Documentation

Overview

Welcome to the Advanced CLI and API Documentation for SeedPass, a secure, deterministic password manager built on Bitcoin's BIP‑85 standard. This guide is designed for power users, developers, and system administrators who wish to leverage the full capabilities of SeedPass through the command line for scripting, automation, and integration.

SeedPass uses a noun-verb command structure (e.g., seedpass entry get <query>) for a clear, scalable, and discoverable interface. You can explore the available actions for any command group with the --help flag (for example, seedpass entry --help).

The commands in this document reflect the Typer-based CLI shipped with SeedPass. Each command accepts the optional --fingerprint flag to operate on a specific seed profile.

Table of Contents

1. Global Options
2. Command Group Reference
   • Entry Commands
   • Vault Commands
   • Nostr Commands
   • Config Commands
   • Fingerprint Commands
   • Utility Commands
   • API Commands
3. Detailed Command Descriptions
4. API Integration
5. Usage Guidelines

Global Options

These options can be used with any command.

Command Group Reference

Entry Commands

Manage individual entries within a vault.

Vault Commands

Manage the entire vault for a profile.

Nostr Commands

Interact with the Nostr network for backup and synchronization.

Config Commands

Manage profile‑specific settings.

Fingerprint Commands

Manage seed profiles (fingerprints).

Utility Commands

Miscellaneous helper commands.

If you see a startup warning about a script checksum mismatch, run seedpass util update-checksum or choose "Generate Script Checksum" from the Settings menu to update the stored value.

API Commands

Run or stop the local HTTP API.

Detailed Command Descriptions

entry Commands

• seedpass entry list – List entries in the vault, optionally sorted or filtered.
• seedpass entry search <query> – Search across labels, usernames, URLs and notes. Results show the entry type before each label.
• seedpass entry get <query> – Retrieve the password or TOTP code for one matching entry, depending on the entry's type.
• seedpass entry add <label> – Create a new password entry. Use --length and flags like --no-special, --special-mode safe, or --exclude-ambiguous to override the global policy.
• seedpass entry add-totp <label> – Create a TOTP entry. Use --secret to import an existing secret or --index to derive from the seed.
• seedpass entry add-ssh <label> – Create an SSH key entry derived from the seed.
• seedpass entry add-pgp <label> – Create a PGP key entry. Provide --user-id and --key-type as needed.
• seedpass entry add-nostr <label> – Create a Nostr key entry for decentralised chat.
• seedpass entry add-seed <label> – Store a derived seed phrase. Use --words to set the word count.
• seedpass entry add-key-value <label> – Store arbitrary data with --key and --value.
• seedpass entry add-managed-account <label> – Store a BIP‑85 derived account seed.
• seedpass entry modify <id> – Update an entry's fields. For key/value entries you can change the label, key and value.
• seedpass entry archive <id> – Mark an entry as archived so it is hidden from normal lists.
• seedpass entry unarchive <id> – Restore an archived entry.
• seedpass entry export-totp --file <path> – Export all stored TOTP secrets to a JSON file.
• seedpass entry totp-codes – Display all current TOTP codes with remaining time.

Example retrieving a TOTP code:

$ seedpass entry get "email"
[##########----------] 15s
Code: 123456

Viewing Entry Details

Picking an entry from entry list or entry search displays its metadata first so you can review the label, username and notes. Sensitive fields are hidden until you confirm you want to reveal them. After showing the secret, the details view offers the same actions as entry get—edit the entry, archive it or show QR codes for supported types.

vault Commands

• seedpass vault export – Export the entire vault to an encrypted JSON file.
• seedpass vault import – Import a vault from an encrypted JSON file and automatically sync via Nostr.
• seedpass vault change-password – Change the master password used for encryption.
• seedpass vault lock – Clear sensitive data from memory and require reauthentication.
• seedpass vault stats – Display statistics about the active seed profile.
• seedpass vault reveal-parent-seed – Print the parent seed or write an encrypted backup with --file.

nostr Commands

• seedpass nostr sync – Perform a two‑way sync with configured Nostr relays.
• seedpass nostr get-pubkey – Display the Nostr public key for the active profile.

config Commands

• seedpass config get <key> – Retrieve a configuration value such as kdf_iterations, backup_interval, inactivity_timeout, secret_mode_enabled, clipboard_clear_delay, additional_backup_path, relays, quick_unlock, nostr_max_retries, nostr_retry_delay, or password policy fields like min_uppercase.
• seedpass config set <key> <value> – Update a configuration option. Example: seedpass config set kdf_iterations 200000. Use keys like min_uppercase, min_lowercase, min_digits, min_special, include_special_chars, allowed_special_chars, special_mode, exclude_ambiguous, nostr_max_retries, nostr_retry_delay, or quick_unlock to adjust settings.
• seedpass config toggle-secret-mode – Interactively enable or disable Secret Mode and set the clipboard delay.
• seedpass config toggle-offline – Enable or disable offline mode to skip Nostr operations.

fingerprint Commands

• seedpass fingerprint list – List available profiles by fingerprint.
• seedpass fingerprint add – Create a new seed profile.
• seedpass fingerprint remove <fp> – Delete the specified profile.
• seedpass fingerprint switch <fp> – Switch the active profile.

util Commands

• seedpass util generate-password – Generate a strong password of the requested length.
• seedpass util verify-checksum – Verify the SeedPass script checksum.
• seedpass util update-checksum – Regenerate the script checksum file.

API Integration

SeedPass provides a small REST API for automation. Run seedpass api start to launch the server. The command prints a one‑time token which clients must include in the Authorization header.

Set the SEEDPASS_CORS_ORIGINS environment variable to a comma‑separated list of allowed origins when you need cross‑origin requests:

SEEDPASS_CORS_ORIGINS=http://localhost:3000 seedpass api start

Shut down the server with seedpass api stop.

Usage Guidelines

• Use the --help flag for details on any command.
• Set a strong master password and regularly export encrypted backups.
• Adjust configuration values like kdf_iterations, backup_interval, inactivity_timeout, secret_mode_enabled, nostr_max_retries, nostr_retry_delay, or quick_unlock through the config commands.
• Customize the global password policy with commands like config set min_uppercase 3 or config set special_mode safe. When adding a password interactively you can override these values, choose a safe special-character set, and exclude ambiguous characters.
• entry get is script‑friendly and can be piped into other commands.