@candledottv/cli 0.6.1 → 0.6.2

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 (`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. MCP hosts also need Node 18+ on their own PATH, because `candle mcp` starts the server with `npx --yes @candledottv/mcp`. |
 | `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

package/dist/index.js

@@ -4893,9 +4893,10 @@ async function fetchAccount(deps, apiUrl, apiKey) {
     fetch: deps.fetch,
     env: deps.env
   });
-  const account = identity.ok ? identity.body.account : undefined;
+  const body = identity.ok ? identity.body : undefined;
+  const account = body?.account;
   if (account)
-    return { account };
+    return { account, ...body?.username ? { username: body.username } : {} };
   return { failure: identity.ok ? "no account in the response" : identity.message };
 }
 
@@ -5179,16 +5180,16 @@ function defaultProfileNameFor(apiUrl, existing) {
 function credentialEnvOverrides(env) {
   return ["CANDLE_API_KEY", "CANDLE_DEVICE_TOKEN"].filter((name) => env[name]?.trim());
 }
-function identityLine(profile, account, apiUrl, overrides) {
-  const shown = overrides?.length ? `unknown (${overrides.join(", ")} override)` : account ?? "unknown";
+function identityLine(profile, account, apiUrl, overrides, username) {
+  const shown = overrides?.length ? `unknown (${overrides.join(", ")} override)` : username && account ? `${username} (${account})` : account ?? "unknown";
   return `Profile: ${profile ?? "none"}   Account: ${shown} at ${apiUrl}`;
 }
 async function printIdentity(ctx) {
   if (ctx.json)
     return;
   const config = await ctx.deps.readConfig();
-  const account = effectiveProfileFields(config, ctx.profile).account;
-  ctx.deps.stdout.write(`${identityLine(ctx.profile, account, ctx.apiUrl, credentialEnvOverrides(ctx.deps.env))}
+  const fields = effectiveProfileFields(config, ctx.profile);
+  ctx.deps.stdout.write(`${identityLine(ctx.profile, fields.account, ctx.apiUrl, credentialEnvOverrides(ctx.deps.env), fields.username)}
 `);
 }
 function formatCacheAge(now, cachedAt) {
@@ -5384,7 +5385,7 @@ async function resolveApiKey(deps, profile) {
 }
 
 // src/version.ts
-var CLI_VERSION = "0.6.1";
+var CLI_VERSION = "0.6.2";
 
 // src/commands/auth.ts
 var DEVICE_CODE_PATH = "/api/v1/agent/device/code";
@@ -5505,8 +5506,12 @@ async function finishLogin(rawBody, ctx, requested) {
   if (body.apiKey)
     await deps.store.set(profileSecretRef(profileName, "apiKey"), body.apiKey.key);
   let account;
-  if (body.apiKey)
-    account = (await fetchAccount(deps, ctx.apiUrl, body.apiKey.key)).account;
+  let username;
+  if (body.apiKey) {
+    const lookup = await fetchAccount(deps, ctx.apiUrl, body.apiKey.key);
+    account = lookup.account;
+    username = lookup.username;
+  }
   const portalOrigin = portalOriginFrom(requested.verificationUri);
   await deps.updateProfile(profileName, {
     apiUrl: ctx.apiUrl,
@@ -5514,7 +5519,7 @@ async function finishLogin(rawBody, ctx, requested) {
     ...body.apiKey ? { keyPrefix: body.apiKey.keyPrefix, scopes: body.apiKey.scopes } : {},
     ...requested.label ? { label: requested.label } : {},
     ...portalOrigin ? { portalOrigin } : {},
-    ...account ? { account, accountCachedAt: deps.now() } : {}
+    ...account ? { account, accountCachedAt: deps.now(), username } : {}
   });
   if (!config.activeProfile)
     await deps.writeConfig({ activeProfile: profileName });
@@ -5670,8 +5675,12 @@ async function authStatus(args, ctx) {
     }));
   }
   let account;
-  if (apiKey)
-    account = (await fetchAccount(deps, apiUrl, apiKey)).account;
+  let username;
+  if (apiKey) {
+    const lookup = await fetchAccount(deps, apiUrl, apiKey);
+    account = lookup.account;
+    username = lookup.username;
+  }
   const exitCode = rows.some((row) => row.state === "FAIL") ? 1 : 0;
   const configPath = configFilePathForDisplay(deps.env);
   const fields = effectiveProfileFields(config, ctx.profile);
@@ -5692,7 +5701,9 @@ async function authStatus(args, ctx) {
 `);
     return exitCode;
   }
-  deps.stdout.write(`${identityLine(ctx.profile, account ?? fields.account, apiUrl)}
+  const shownAccount = account ?? fields.account;
+  const shownUsername = account !== undefined ? username : fields.username;
+  deps.stdout.write(`${identityLine(ctx.profile, shownAccount, apiUrl, undefined, shownUsername)}
 `);
   if (mismatch) {
     deps.stdout.write(`Profile ${ctx.profile} recorded ${cachedAccount}; this key belongs to ${account}. Run: candle profile use ${ctx.profile}
@@ -6218,8 +6229,8 @@ async function mcp(args, ctx) {
     toolAllowlist = requested.join(",");
   }
   const identityConfig = await deps.readConfig();
-  const identityAccount = effectiveProfileFields(identityConfig, ctx.profile).account;
-  deps.stderr.write(`${identityLine(ctx.profile, identityAccount, apiUrl, credentialEnvOverrides(deps.env))}
+  const identityFields = effectiveProfileFields(identityConfig, ctx.profile);
+  deps.stderr.write(`${identityLine(ctx.profile, identityFields.account, apiUrl, credentialEnvOverrides(deps.env), identityFields.username)}
 `);
   if (parsed.booleans.has("--print-config")) {
     const launchArgs = [
@@ -6364,11 +6375,13 @@ async function profileUse(args, ctx) {
   const apiUrl = ctx.apiUrlFlag ?? resolveApiUrl(profile.apiUrl, deps.env);
   const apiKey = await deps.store.get(profileSecretRef(name, "apiKey"));
   let account = profile.account;
+  let username = profile.username;
   if (apiKey) {
-    const { account: live, failure } = await fetchAccount(deps, apiUrl, apiKey);
+    const { account: live, username: liveUsername, failure } = await fetchAccount(deps, apiUrl, apiKey);
     if (live) {
       account = live;
-      await deps.updateProfile(name, { account: live, accountCachedAt: deps.now() });
+      username = liveUsername;
+      await deps.updateProfile(name, { account: live, username: liveUsername, accountCachedAt: deps.now() });
     } else {
       deps.stderr.write(`Could not refresh the account for ${name} (${failure}); keeping the cached value.
 `);
@@ -6381,7 +6394,7 @@ async function profileUse(args, ctx) {
     deps.stdout.write(`${JSON.stringify({ name, account, apiUrl })}
 `);
   else
-    deps.stdout.write(`${identityLine(name, account, apiUrl)}
+    deps.stdout.write(`${identityLine(name, account, apiUrl, undefined, username)}
 `);
   return 0;
 }
@@ -6533,7 +6546,7 @@ async function setup(args, ctx) {
     const solana = body.wallets?.solana ?? null;
     const evm = body.wallets?.evm ?? null;
     if (body.account)
-      deps.stdout.write(`${identityLine(nextCtx.profile, body.account, apiUrl)}
+      deps.stdout.write(`${identityLine(nextCtx.profile, body.account, apiUrl, undefined, body.username)}
 `);
     if (solana)
       deps.stdout.write(`Solana (send SOL here):    ${solana.address}
@@ -6545,6 +6558,8 @@ async function setup(args, ctx) {
 `);
     deps.stdout.write(`
 Tell your agent (paste into its context):
+`);
+    deps.stdout.write(`  Install the Candle CLI: curl -fsSL https://candle.tv/install.sh | bash
 `);
     deps.stdout.write(`  You operate a Candle agent account. API base URL: ${apiUrl} (send your API key in the x-api-key header).
 `);
@@ -10615,9 +10630,9 @@ Commands:
   keys create [--scopes <a,b,c>] [--label <name>]                 Create an API key
               [--expires-in <days>] [--tx-limit <usd> [--reset daily|weekly|monthly|never]]
   keys revoke <prefix>                                            Revoke an API key
-  wallets                                                         Show launch and linked wallets
-  wallets import --chain <solana|evm> [options]                   Import a wallet you own (key via --key-file or hidden prompt)
-  wallets revoke <wallet-id>                                      Revoke a linked wallet
+  wallet                                                          Show launch and linked wallets (wallets is an alias)
+  wallet import --chain <solana|evm> [options]                    Import a wallet you own (key via --key-file or hidden prompt)
+  wallet revoke <wallet-id>                                       Revoke a linked wallet
   profile list                                                    Profiles on this machine, with cached accounts
   profile add <name> --api-url <url>                              Create a profile before authenticating it
   profile use <name>                                              Make a profile the active one
@@ -10651,6 +10666,10 @@ var COMMANDS = {
   update: { bare: update }
 };
 var ROUTED_COMMANDS = new Set(Object.keys(COMMANDS));
+var ALIASES = { wallet: "wallets" };
+function canonicalCommand(word) {
+  return word !== undefined && Object.hasOwn(ALIASES, word) ? ALIASES[word] : word;
+}
 var ROUTED_SUBCOMMANDS = Object.fromEntries(Object.entries(COMMANDS).filter(([, route]) => route.subcommands !== undefined).map(([word, route]) => [word, Object.keys(route.subcommands ?? {})]));
 function routeFor(word) {
   return word !== undefined && Object.hasOwn(COMMANDS, word) ? COMMANDS[word] : undefined;
@@ -10680,7 +10699,7 @@ async function run2(argv, deps) {
   const { rest, flags } = extracted;
   const tokens = rest[0] === "candle" ? rest.slice(1) : rest;
   if (flags.version) {
-    const versionWord = tokens[0];
+    const versionWord = canonicalCommand(tokens[0]);
     if (versionWord !== undefined && ROUTED_COMMANDS.has(versionWord)) {
       const fix = "--version prints the CLI version; to pin a release use: candle update --to <tag>";
       writeUsageFailure(deps, fix, flags.json);
@@ -10694,7 +10713,8 @@ async function run2(argv, deps) {
     deps.stdout.write(HELP_TEXT);
     return 0;
   }
-  const [cmd, sub, ...cmdArgs] = tokens;
+  const [rawCmd, sub, ...cmdArgs] = tokens;
+  const cmd = canonicalCommand(rawCmd);
   const config = await migrateProfiles(deps);
   const isAuthLogin = cmd === "auth" && sub === "login";
   const isProfileCommand = cmd === "profile";
@@ -10859,5 +10879,6 @@ export {
   buildRealDeps,
   ROUTED_SUBCOMMANDS,
   ROUTED_COMMANDS,
-  NEVER_GUARDED
+  NEVER_GUARDED,
+  ALIASES
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candledottv/cli",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "The Candle CLI: authorize a device from your browser, then manage API keys, wallets, and setup health from the terminal",
   "type": "module",
   "bin": {