@candledottv/cli 0.5.0 → 0.6.0

package/README.md

@@ -38,21 +38,30 @@ node packages/cli/dist/index.js auth login
 | Command | What it does |
 | --- | --- |
 | `candle setup [--no-browser]` | The onboarding wizard: authorizes this device (skipped when already authorized), prints the agent wallets as funding destinations plus the paste-into-your-agent brief, shows the skill/MCP install lines, runs the full doctor check (setup's exit code is doctor's), and links the web console. Safe to re-run. |
-| `candle auth login [--scopes <a,b,c>] [--label <name>] [--no-browser]` | Authorizes this device: prints a code, opens (or prints) an approval URL, polls until approved, then stores the resulting device token and API key. |
+| `candle auth login [--profile <name>] [--scopes <a,b,c>] [--label <name>] [--no-browser]` | Authorizes this device: prints a code, opens (or prints) an approval URL, polls until approved, then stores the resulting device token and API key. |
 | `candle auth status` | Shows which storage backend is in use, both credential prefixes, the config file path, and a live validity check for each credential. |
 | `candle auth logout [--keep-key]` | Revokes the stored API key (skipped with `--keep-key`), clears local credentials and config, and prints the portal URL for revoking the device itself. |
 | `candle keys list` | Lists this account's API keys: prefix, scopes, environment, timestamps, and which device minted each one. |
 | `candle keys create [--scopes <a,b,c>] [--label <name>] [--expires-in <days>] [--tx-limit <usd> [--reset daily\|weekly\|monthly\|never]]` | Creates a new API key and prints the plaintext exactly once, with the same optional name, expiration, and USD transaction limit the portal's create form takes. Stored locally only if the CLI does not already hold a working key. |
 | `candle keys revoke <prefix>` | Revokes an API key by prefix. Revoking the CLI's own stored key also clears it locally. |
-| `candle wallets` | Shows the account's embedded (launch) wallets and any linked wallets, using the API key. |
-| `candle mcp [--tools <a,b,c>] [--read-only] [--print-config]` | Runs the Candle MCP server (`npx @candledottv/mcp`) with this CLI's stored API key and API URL in its environment, so an MCP client config is just `{"command": "candle", "args": ["mcp"]}`. `--read-only` starts it with no key and only the three keyless read tools; `--tools` pins an explicit allowlist; `--print-config` prints the ready-to-paste client block instead of launching. |
+| `candle wallets` | Shows the account's embedded (launch) wallets and any linked wallets, using the API key, with a `Signer` column saying whether this machine holds each linked wallet's signing key. |
+| `candle profile list` | Lists profiles on this machine, with cached accounts. |
+| `candle profile add <name> --api-url <url>` | Creates a profile before authenticating it. |
+| `candle profile use <name>` | Makes a profile the active one. |
+| `candle profile rename <old> <new>` | Renames a profile. |
+| `candle profile remove <name> --yes` | Deletes a profile and its stored credentials. |
+| `candle mcp [--tools <a,b,c>] [--read-only] [--print-config]` | Runs the Candle MCP server (`npx @candledottv/mcp`) with this CLI's stored API key and API URL in its environment, so an MCP client config is just `{"mcpServers": {"candle": {"command": "/Users/you/.local/bin/candle", "args": ["mcp"]}}}` -- the absolute path, because GUI hosts launch servers with the app's environment and never see your PATH. Run `--print-config` to print that block filled in for this install. `--read-only` starts it with no key and only the four keyless read tools; `--tools` pins an explicit allowlist. |
 | `candle doctor` | Runs a full health check (runtime, backend, credentials, API reachability, credential validity, wallet delegation) as a PASS/FAIL/SKIP table. Exits nonzero on any FAIL. |
+| `candle verify <file> --bundle <path> [--identity <uri>] [--issuer <url>]` | Verifies a release asset's Sigstore bundle against the trusted root compiled into this binary. No network, no credentials, and nothing else installed: the bundle carries the certificate and the transparency-log entry. `--identity` defaults to the release identity for the version in a `latest.json` sitting beside the bundle; `--issuer` defaults to GitHub Actions'. Prints `verified: <identity>` and exits 0, or the reason on stderr and exits 1. |
+| `candle update [--check] [--to <tag>]` | Replaces this binary with the latest signed release. The download is renamed over the running binary only after its SHA-256 matches both SHA256SUMS and `latest.json` AND its Sigstore bundle verifies in process against that exact version's release workflow. `--check` reports what is available and installs nothing; `--to <tag>` pins a release (an older one installs, with a warning). A Homebrew or npm install is left alone, with the command that owns it printed instead. |
 
 Every command accepts these global options:
 
 | Flag | Effect |
 | --- | --- |
 | `--api-url <url>` | Overrides the API base URL for this invocation, beating `CANDLE_API_URL` and the stored config value. |
+| `--profile <name>` | Act as a named profile; see Profiles below. |
+| `--no-verify-account` | Skips the check that the stored key belongs to the profile's account. |
 | `--json` | Machine-readable output instead of a formatted table or summary, generally the underlying API response. One exception: `auth login`'s JSON output still omits the plaintext device token and API key, matching its human-readable summary, since login never displays either value in any mode. |
 | `--help`, `-h` | Prints usage. |
 | `--version`, `-v` | Prints the CLI version. |
@@ -104,6 +113,55 @@ The CLI picks the best available backend for your machine, in this order:
 
 `candle auth status` and `candle doctor` both report which backend is active.
 
+## Profiles
+
+One machine can hold credentials for several accounts and hosts. `auth login` creates a profile
+implicitly when none is already selected, named from `--profile <name>` or derived from the API
+host (`staging`, `production`, or the hostname, de-duplicated with a numeric suffix). Which profile a command acts as, highest
+wins: `--profile`, `CANDLE_PROFILE`, the `activeProfile` in `config.json`, the sole profile. With
+several profiles and none selected the CLI refuses and lists them; guessing is how a wallet
+import once landed on the wrong account.
+
+Re-running `auth login` refreshes the profile you are already on, in place: the same name, the
+same refs, a new device token and key. Use `--profile <new name>` to add another instead.
+`auth logout` removes the acting profile's entry and its stored credentials, and clears
+`activeProfile` when it pointed there. `candle profile list` shows every profile with its cached
+account and how old that cache is (no network call); `profile use <name>` makes one active and
+refreshes its account from the API; `profile add <name> --api-url <url>` creates one before
+authenticating it; `profile rename` and `profile remove <name> --yes` do what they say. Removing a
+profile deletes its two stored credentials and nothing else; imported wallet signers belong to the
+wallet, not the profile. `candle wallets` marks, per linked wallet, whether this machine holds its
+signer (`stored`, `none`, or `stale` for a revoked wallet whose signer is still here).
+
+Every authenticated command prints `Profile: <name>   Account: <account> at <api url>` before its
+own output (`--json` output is unchanged except `auth status`, `auth login` and `doctor`, which
+carry `profile` and `account`; `auth status` and `doctor` also carry `cachedAccount`, the account
+the profile recorded, whenever a profile is resolved; scripts get identity from
+`auth status --json`). The account is cached
+at login from the API. Where the line is printed from that cache and `CANDLE_API_KEY` or
+`CANDLE_DEVICE_TOKEN` is overriding the stored credential, it reads
+`Account: unknown (CANDLE_API_KEY override)` rather than naming an account that credential was
+never checked against; `auth status` and `setup` look the account up live and print what they
+get, and `auth status` and `doctor` name the account the profile recorded beside it when the two
+differ (not under an env credential override, where the live answer is not the profile's key's).
+Before an authenticated command acts, the CLI asks the profile's stored key which account it
+belongs to and **refuses** if the answer differs from the account the profile recorded, naming
+both and the repairs in order of cost. A key that was legitimately re-issued is repaired with
+`candle profile use <name>`, which re-caches the account; `candle auth login --profile <name>`
+re-authenticates instead; `--no-verify-account` skips the check for one invocation without
+repairing anything. An unreachable API turns the check into a warning, never a failure. The
+check is skipped when
+`CANDLE_API_KEY` or `CANDLE_DEVICE_TOKEN` is overriding the stored credential, when a profile has
+no cached account or no stored key, and for the commands that only read the identity or repair it:
+`auth login`, `auth status`, `auth logout`, `doctor`, `verify` (which acts as no identity at all:
+two files and a signature) and the `profile` commands. `setup` is guarded, because it skips its
+login step whenever credentials are already stored.
+
+A pre-profile install is migrated on first run: profile `default` is created from the existing
+settings and the two credentials are copied to `profile:default:*` refs. The old refs and fields
+are left in place so an older CLI keeps working, until an `auth logout` clears them along with
+the profile they were migrated into.
+
 ## Environment variables
 
 | Variable | Effect |
@@ -111,6 +169,7 @@ The CLI picks the best available backend for your machine, in this order:
 | `CANDLE_DEVICE_TOKEN` | Overrides the stored device token for this process. Every command that needs the device token checks this first, before the store. |
 | `CANDLE_API_KEY` | Overrides the stored API key for this process, same precedence as above. |
 | `CANDLE_API_URL` | Overrides the API base URL, beating the stored config value (but not an explicit `--api-url` flag). |
+| `CANDLE_PROFILE` | Selects the profile when `--profile` is not given. |
 | `CANDLE_KEYRING_PASSPHRASE` | The passphrase for the encrypted-file backend. Without it, a non-interactive process (no TTY) fails with a clear error rather than falling back to writing plaintext; an interactive session is prompted instead. |
 | `CANDLE_CONFIG_DIR` | Overrides where the CLI keeps its config and encrypted-file credentials (default `~/.config/candle`). Mainly a testing seam. |