@candledottv/cli 0.6.1 → 0.7.0

package/README.md

@@ -7,11 +7,23 @@ health from the terminal. Zero runtime dependencies; the whole thing is one self
 ## Quick start
 
 ```
-npx @candledottv/cli auth login
+Install the Candle CLI (macOS or Linux):
+
+    curl -fsSL https://candle.tv/install.sh | bash
+
+or with Homebrew:
+
+    brew install candledottv/tap/candle
+
+Then: candle setup
 ```
 
-This runs `auth login`, which opens your browser to approve this device. Install it permanently
-with `npm install -g @candledottv/cli` and the command is just `candle`.
+`candle setup` authorizes this device from your browser, shows the agent wallets as funding
+destinations, prints the skill and MCP install lines, and runs a full health check. `candle auth
+login` on its own does just the authorization step.
+
+The npm package `@candledottv/cli` stays published for CI, programmatic use, and Windows until
+`install.ps1` ships; `npx -y @candledottv/cli@latest <command>` runs it once without installing.
 
 ### No-npm fallback
 
@@ -50,7 +62,7 @@ node packages/cli/dist/index.js auth login
 | `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 mcp [--tools <a,b,c>] [--read-only] [--print-config]` | Runs the Candle MCP server (built into this binary) 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. The server is bundled into the binary, so the host needs nothing else installed. |
 | `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. |
@@ -66,6 +78,40 @@ Every command accepts these global options:
 | `--help`, `-h` | Prints usage. |
 | `--version`, `-v` | Prints the CLI version. |
 
+## Verify a release
+
+Every release on https://github.com/candledottv/agentic/releases is built and signed by that
+repository's `release.yaml` workflow, and `install.sh` and `candle update` already check this for
+you. To check a download by hand, three commands, in increasing strength:
+
+```
+curl -fsSLO https://github.com/candledottv/agentic/releases/download/cli-v0.6.1/SHA256SUMS
+curl -fsSLO https://github.com/candledottv/agentic/releases/download/cli-v0.6.1/candle-darwin-arm64
+grep candle-darwin-arm64 SHA256SUMS | shasum -a 256 -c
+```
+
+```
+gh attestation verify candle-darwin-arm64 --repo candledottv/agentic \
+  --signer-workflow candledottv/agentic/.github/workflows/release.yaml
+```
+
+```
+curl -fsSLO https://github.com/candledottv/agentic/releases/download/cli-v0.6.1/candle-darwin-arm64.sigstore.json
+cosign verify-blob --new-bundle-format --bundle candle-darwin-arm64.sigstore.json \
+  --certificate-identity-regexp '^https://github.com/candledottv/agentic/\.github/workflows/release\.yaml@refs/tags/cli-v' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  candle-darwin-arm64
+```
+
+`--new-bundle-format` (cosign 2.2 or newer) says "expect a Sigstore bundle", which is what releases
+from 0.6.1 onward are signed as; without it cosign also accepts an older bundle format of its own,
+which `candle verify` cannot read.
+
+No cosign or gh installed? `candle verify <file> --bundle <path>` (this CLI's own command, see the
+table above) runs the same check against the trusted root compiled into the binary, no network
+call required. Full walkthrough, including the installer script's own signature and the
+transparency log: [Verify a Candle release](https://docs.candle.tv/developers/verify-a-candle-release).
+
 ## The `--json` contract
 
 For agents and scripts, `--json` guarantees: **stdout carries exactly one JSON value** -- the
@@ -172,6 +218,7 @@ the profile they were migrated into.
 | `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. |
+| `CANDLE_ALLOW_INSECURE_HTTP` | Allows an `http://` API URL pointing at a non-loopback host. The CLI attaches a device token or API key to nearly every request, so it refuses cleartext by default. Loopback (`localhost`, `127.0.0.0/8`, `::1`) is always allowed and needs no opt-in; set this only for a trusted local endpoint that is not loopback, such as a devcontainer reaching its host. |
 
 `CANDLE_DEVICE_TOKEN` and `CANDLE_API_KEY` together mean CI needs no storage backend at all: set
 both and every command works without ever touching a keychain or the encrypted file.