From a33f67781b09f707cbaf466df01f76021a54fddd Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Wed, 9 Jul 2025 09:51:01 -0400 Subject: [PATCH] docs: update CLI and API usage --- docs/README.md | 4 +++- docs/advanced_cli.md | 54 ++++++++++++++++++++------------------------ 2 files changed, 28 insertions(+), 30 deletions(-) diff --git a/docs/README.md b/docs/README.md index bd25730..000d23d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,4 +14,6 @@ $ seedpass totp "email" Code: 123456 ``` -See [advanced_cli.md](advanced_cli.md) (future feature set) for details on the upcoming advanced CLI. +## CLI and API Reference + +See [advanced_cli.md](advanced_cli.md) for a list of command examples and instructions on running the local API. When starting the API, set `SEEDPASS_CORS_ORIGINS` if you need to allow requests from specific web origins. diff --git a/docs/advanced_cli.md b/docs/advanced_cli.md index 0ed3070..193de5b 100644 --- a/docs/advanced_cli.md +++ b/docs/advanced_cli.md @@ -6,7 +6,7 @@ Welcome to the **Advanced CLI and API Documentation** for **SeedPass**, a secure SeedPass uses a `noun-verb` command structure (e.g., `seedpass entry get `) 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`). -> **Note:** These commands describe planned functionality. The advanced CLI is not yet part of the stable release but will follow the current SeedPass design of fingerprint-based profiles and a local API for secure integrations. +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. --- @@ -20,8 +20,9 @@ SeedPass uses a `noun-verb` command structure (e.g., `seedpass entry get - [Config Commands](#config-commands) - [Fingerprint Commands](#fingerprint-commands) - [Utility Commands](#utility-commands) + - [API Commands](#api-commands) 3. [Detailed Command Descriptions](#detailed-command-descriptions) -4. [Planned API Integration](#planned-api-integration) +4. [API Integration](#api-integration) 5. [Usage Guidelines](#usage-guidelines) --- @@ -45,12 +46,9 @@ Manage individual entries within a vault. | Action | Command | Examples | | :--- | :--- | :--- | -| Add a new entry | `entry add` | `seedpass entry add --type password --label "GitHub" --username "user" --length 20` | -| Retrieve an entry's secret | `entry get` | `seedpass entry get "GitHub"` | | List entries | `entry list` | `seedpass entry list --sort label` | | Search for entries | `entry search` | `seedpass entry search "GitHub"` | -| Modify an entry | `entry modify` | `seedpass entry modify "GitHub" --notes "New note"` | -| Delete an entry | `entry delete` | `seedpass entry delete "GitHub"` | +| Retrieve an entry's secret | `entry get` | `seedpass entry get "GitHub"` | ### Vault Commands @@ -59,8 +57,6 @@ Manage the entire vault for a profile. | Action | Command | Examples | | :--- | :--- | :--- | | Export the vault | `vault export` | `seedpass vault export --file backup.json` | -| Import a vault | `vault import` | `seedpass vault import --file backup.json` | -| Change master password | `vault changepw` | `seedpass vault changepw` | ### Nostr Commands @@ -70,7 +66,6 @@ Interact with the Nostr network for backup and synchronization. | :--- | :--- | :--- | | Sync with relays | `nostr sync` | `seedpass nostr sync` | | Get public key | `nostr get-pubkey` | `seedpass nostr get-pubkey` | -| Manage relays | `nostr relays` | `seedpass nostr relays --add wss://relay.example.com` | ### Config Commands @@ -79,7 +74,6 @@ Manage profile‑specific settings. | Action | Command | Examples | | :--- | :--- | :--- | | Get a setting value | `config get` | `seedpass config get inactivity_timeout` | -| Set a setting value | `config set` | `seedpass config set secret_mode true` | ### Fingerprint Commands @@ -87,10 +81,7 @@ Manage seed profiles (fingerprints). | Action | Command | Examples | | :--- | :--- | :--- | -| Add a new profile | `fingerprint add` | `seedpass fingerprint add` | | List all profiles | `fingerprint list` | `seedpass fingerprint list` | -| Remove a profile | `fingerprint remove` | `seedpass fingerprint remove ` | -| Set active profile | `fingerprint use` | `seedpass fingerprint use ` | ### Utility Commands @@ -99,7 +90,15 @@ Miscellaneous helper commands. | Action | Command | Examples | | :--- | :--- | :--- | | Generate a password | `util generate-password` | `seedpass util generate-password --length 24` | -| Verify script checksum | `util verify-checksum` | `seedpass util verify-checksum` | + +### API Commands + +Run or stop the local HTTP API. + +| Action | Command | Examples | +| :--- | :--- | :--- | +| Start the API | `api start` | `seedpass api start --host 0.0.0.0 --port 8000` | +| Stop the API | `api stop` | `seedpass api stop` | --- @@ -107,47 +106,44 @@ Miscellaneous helper commands. ### `entry` Commands -- **`seedpass entry add`** – Add a new entry. Use `--type` to specify `password`, `totp`, `ssh`, `pgp`, `nostr`, `key-value`, or `managed-account`. Include `--tags tag1,tag2` to categorize the entry. -- **`seedpass entry get `** – Retrieve the primary secret for one matching entry. - **`seedpass entry list`** – List entries in the vault, optionally sorted or filtered. -- **`seedpass entry search `** – Search across labels, usernames, URLs, notes, and tags. -- **`seedpass entry modify `** – Update fields on an existing entry. Use `--archive` to hide or `--restore` to un‑archive. Specify `--tags tag1,tag2` to replace the entry's tags. -- **`seedpass entry delete `** – Permanently delete an entry after confirmation. +- **`seedpass entry search `** – Search across labels, usernames, URLs and notes. +- **`seedpass entry get `** – Retrieve the primary secret for one matching entry. ### `vault` Commands - **`seedpass vault export`** – Export the entire vault to an encrypted JSON file. -- **`seedpass vault import`** – Import entries from an exported file, replacing the current vault after creating a backup. -- **`seedpass vault changepw`** – Interactively change the master password for the current profile. ### `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. -- **`seedpass nostr relays`** – Manage the relay list (`--list`, `--add`, `--remove`, `--reset`). ### `config` Commands - **`seedpass config get `** – Retrieve a configuration value such as `inactivity_timeout`, `secret_mode`, or `auto_sync`. -- **`seedpass config set `** – Set a configuration value for the active profile. ### `fingerprint` Commands -- **`seedpass fingerprint add`** – Add a new seed profile (interactive or via `--import-seed`). - **`seedpass fingerprint list`** – List available profiles by fingerprint. -- **`seedpass fingerprint remove `** – Delete a profile and its data after confirmation. -- **`seedpass fingerprint use `** – Make the given fingerprint active in the current shell session. ### `util` Commands - **`seedpass util generate-password`** – Generate a strong password of the requested length. -- **`seedpass util verify-checksum`** – Verify the program checksum for integrity. --- -## Planned API Integration +## API Integration -The advanced CLI will act as a client for a locally hosted REST API. Starting the API loads the vault into memory after prompting for the master password and prints a temporary API key. Third‑party clients include this key in the `Authorization` header when calling endpoints such as `GET /api/v1/entry?query=GitHub`. The server automatically shuts down after a period of inactivity or when `seedpass api stop` is run. +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: + +```bash +SEEDPASS_CORS_ORIGINS=http://localhost:3000 seedpass api start +``` + +Shut down the server with `seedpass api stop`. ---