botanary 0.1.0 → 0.2.1

package/README.md

@@ -1,14 +1,16 @@
 # botanary
 
-Botanary from your terminal - a guided CLI over the same wallet and agent lanes `botanary-mcp` exposes to
-a coding agent. Shares its identity/session storage (`~/.botanary-mcp`, override with
-`BOTANARY_MCP_HOME`): log in once, from either surface, and both see it.
+Botanary from your terminal - a guided CLI over the same wallet and agent lanes `botanary-mcp` exposes to a coding agent. Shares its identity and session storage (`~/.botanary-mcp`, override with `BOTANARY_MCP_HOME`): log in once, from either surface, and both see it.
+
+## Renamed in 0.2.0
+
+`agent whoami` used to print this machine's local key readout. It now asks the backend what Botanary actually says about this agent (claimed? live? which account? which grant?), which is what the name means everywhere else. The local readout moved to `agent identity`, unchanged.
 
 ## Install
 
 ```bash
 npx botanary          # zero-install, always latest
-npm i -g botanary      # resident on PATH
+npm i -g botanary     # resident on PATH
 ```
 
 ## Use
@@ -18,13 +20,173 @@ Run `botanary` with no arguments for a guided REPL, or run any command directly:
 ```bash
 botanary login
 botanary balance
-botanary send --amount 25 --token usdc --recipient 0xAb12...9F3 --chain-id 8453
+botanary send --amount 25 --token USDC --recipient 0xAb12...9F3 --chain-id 8453
 botanary agent whoami
 botanary mcp config claude
 ```
 
-Every command works both ways: answer prompts interactively, or pass flags and add `--json` for scripts
-and CI. `--json` also auto-enables whenever stdout is piped or redirected.
+Every command works both ways: answer prompts interactively, or pass flags and add `--json` for scripts and CI. `--json` also auto-enables whenever stdout is piped or redirected.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| **Wallet** | |
+| `login` | Log in as the account owner, in your browser |
+| `logout` | Revoke and clear the stored owner session |
+| `status` | Owner session and this machine's agent binding, side by side |
+| `whoami` | Who Botanary says you are, in both lanes |
+| `chains` | Every chain this backend serves, and what each can do |
+| `gas [options]` | Gas methods available for this account on a chain |
+| `balance` | What this account holds, across every chain |
+| `send [options]` | Send tokens from an account you own |
+| `activity` | Recent sends, swaps and yield transactions |
+| `markets` | Public market data: prices and symbols |
+| `yield` | Yield pools, a shortlist, and this account's positions |
+| `mandates` | What the agent lane may spend unattended (testnet only) |
+| `agents` | Connected agents and any pending approval requests |
+| `open [target]` | Open Botanary in your browser |
+| `accounts` | Manage which owner account subsequent commands use |
+| `api [options] [path]` | Read any documented GET endpoint as the owner |
+| **Agent** | |
+| `agent` | This machine's own agent identity, grant, and spend under it |
+| `agent identity` | This machine's local agent key: address, public key, fingerprint |
+| `agent whoami` | What Botanary says about this agent: claimed, live, which account |
+| `agent account [options]` | The one account this agent is bound to |
+| `agent balance` | The bound account's balance, read as this agent |
+| `agent request [options]` | Ask the owner to approve something this grant cannot cover |
+| `agent pair [options]` | Show (or rotate) the pairing code and register it with Botanary |
+| `agent grant` | This agent's current grant, rendered in plain terms |
+| `agent requests` | Every approval request this agent has filed, and the owner's verdict on each |
+| `agent spend [options]` | Spend under this agent's own grant, unattended |
+| `agent swap [options]` | Swap under this agent's own grant, unattended |
+| `agent status <opId>` | Check on a pending action this agent relayed |
+| `agent apis [options]` | Paid (x402) API endpoints this agent may call, with live price and remaining budget |
+| `agent pay [options] <endpointId>` | Call a paid API endpoint and pay for it inside the owner-committed budget |
+| `agent budget [options]` | Remaining authorizations, per-call max, expiry and epoch for this agent on a chain |
+| `agent forget` | Step 1 of 2: preview what forgetting the local identity would destroy |
+| `agent confirm-forget <token>` | Step 2 of 2: actually delete the agent key from this machine |
+| **Connect** | |
+| `mcp` | Connect a coding agent to Botanary via botanary-mcp |
+| `mcp config` | Print the install snippet for a client |
+| `mcp install` | Install botanary-mcp using that client's own CLI |
+| `mcp serve` | Run the botanary-mcp server on stdio |
+| **System** | |
+| `diagnose` | Start here when anything is unclear or an action failed |
+| `doctor` | The same readiness check as diagnose |
+| `config` | Where identity and session live, and this machine's CLI defaults |
+| `config list` | Every setting, its value, and where that value came from |
+| `config get` | Print one stored config value |
+| `config set` | Store a default for one setting |
+| `config unset` | Remove one stored default |
+| **Utilities** | |
+| `version` | Print the installed botanary CLI version |
+| `docs [topic]` | Open the Botanary documentation in your browser |
+| `completion <shell>` | Print a shell completion script (bash, zsh, fish, powershell) |
+| `prompt` | Print the full operating manual for an automation driving this CLI |
+| `update-check` | Check whether a newer botanary is published |
+
+## Non-interactive use
+
+Use `--json` to get machine-readable output, `--yes` to skip the review step on money commands, and `--dry-run` to preflight without sending. The failure contract is strict: on success, stdout is the response payload (or a plain string); on failure, stdout carries an error object.
+
+### Global options
+
+- `-v, --version` - Print the installed botanary CLI version
+- `-h, --help` - Display help for command
+- `--chain <id|key>` - Default chain: an EVM chain id (8453) or a chain key (solana)
+- `--account <accountId>` - Owner account to act as
+- `--api-url <url>` - Botanary API base URL
+- `--home <dir>` - Directory holding identity, session and CLI config
+- `--json` - Force JSON output (auto-enabled when piped)
+- `--raw` - Print the full raw JSON payload instead of a table
+- `-q, --quiet` - Suppress non-essential output
+- `--verbose` - Show detail an ordinary run leaves out
+- `--no-color` - Disable color output
+- `--reveal` - Show redacted values in plain text
+- `--no-interactive` - Disable prompts and the REPL
+- `--timeout <ms>` - Abort any single request after this many milliseconds
+- `--debug` - Log one redacted line per HTTP request to stderr
+- `-y, --yes` - Skip the review step on a command that moves funds
+- `--dry-run` - Preflight only: never create a sign request, never relay
+
+### Failure envelope
+
+On failure with `--json`, stdout carries a single JSON line. The error object always has `code` and `message`. The `hint` field is optional and must not be assumed to exist.
+
+Example:
+```json
+{"ok":false,"error":{"code":"declined","message":"...","hint":"..."}}
+```
+
+Branch on the exit code first and on `error.code` second. Never string-match a message.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error |
+| 2 | Invalid arguments |
+| 3 | Not logged in, or not paired |
+| 4 | Declined (policy, bounds, or chain tier) |
+| 5 | Pending: relayed, settlement unknown |
+| 6 | Upstream unavailable (network, RPC, bundler) |
+| 130 | Interrupted (SIGINT) |
+
+## Configuration
+
+Configuration lives in `~/.botanary-mcp/cli-config.json` (override the directory with `BOTANARY_MCP_HOME`). Six config keys control defaults:
+
+- `chainId` - Default chain for commands that ask: an EVM chain id (e.g. 8453) or a chain key (e.g. solana)
+- `accountId` - Owner account to act as by default
+- `apiUrl` - Botanary API base URL
+- `output` - `auto` (intelligent), `json`, or `raw`
+- `color` - `auto` (intelligent) or `never`
+- `confirm` - `always` (require confirmation) or `never` (auto-confirm). Set to `never` to skip review prompts by default, though `--dry-run` is always available
+
+Precedence: flag, then environment variable, then stored config, then built-in default. Run `botanary config list` to see every setting's current value and where it came from. Relevant environment variables:
+
+- `BOTANARY_CHAIN_ID` - Default chain
+- `BOTANARY_ACCOUNT_ID` - Default account
+- `BOTANARY_API_URL` - API base URL
+- `BOTANARY_JSON` - Force JSON output
+- `BOTANARY_TIMEOUT_MS` - Request timeout in milliseconds
+- `NO_COLOR` - Disable color (any value)
+- `BOTANARY_MCP_HOME` - Override identity and config storage directory
+
+## Shell completion
+
+Install the completion script your shell uses:
+
+```bash
+# zsh
+botanary completion zsh > ~/.zsh/completions/_botanary
+# or add to ~/.zshrc:
+eval "$(botanary completion zsh)"
+
+# bash
+botanary completion bash >> ~/.bashrc
+# then reload:
+source ~/.bashrc
+
+# fish
+botanary completion fish | source
+
+# PowerShell
+botanary completion powershell | Out-String | Invoke-Expression
+```
+
+## Driving it from an agent
+
+To run `botanary` non-interactively from a script or agent:
+
+1. Use `--json` on every command to get machine-readable output.
+2. Use `--yes` on any command that moves funds (send, agent spend, agent swap, etc.) to skip the review step.
+3. Use `--dry-run` first to preflight a payment without sending it.
+4. Exit code 5 means the operation was relayed but settlement is unknown. For an owner-lane `send`, poll `botanary api /userops/<opId> --json` instead of retrying. For an `agent spend`, poll `botanary agent status <opId> --json`.
+
+See `botanary prompt` for the full operating manual, including every command, every flag, and examples for every lane.
 
 ## Development
 
@@ -35,5 +197,20 @@ pnpm test
 pnpm dev     # run bin/botanary.ts directly, watching for changes
 ```
 
-`BOTANARY_MCP_HOME` and `BOTANARY_API_URL` behave exactly as documented in `botanary-mcp`'s own README -
-this package depends on that one as its engine and adds no storage or network logic of its own.
+`BOTANARY_MCP_HOME` and `BOTANARY_API_URL` behave exactly as documented in `botanary-mcp`'s own README - this package depends on that one as its engine and adds no storage or network logic of its own.
+
+## Release note
+
+`botanary` depends on `botanary-mcp` as its engine, so the two publish in a fixed order:
+
+1. `botanary-mcp@0.6.0` is published to npm. **Done** - it carries the optional login and send progress
+   callbacks this CLI needs to print a login code and an approval URL before its poll loop, rather than
+   after it.
+2. `tools/botanary-cli/package.json` depends on `^0.6.0` from the registry. **Done** - the suite and the
+   `mcp serve` smoke check both pass against the published package, not a local link.
+3. `botanary@0.2.0` publishes.
+
+Repeat that order for any future release where the CLI needs a change in the engine: a `botanary` published
+against an unpublished `botanary-mcp` installs broken.
+
+See `docs/superpowers/specs/2026-08-19-botanary-cli-completion-design.md` section 5 for the rationale.

package/dist/bin/botanary.js

@@ -1,11 +1,21 @@
 #!/usr/bin/env node
 import { createDefaultRuntime } from 'botanary-mcp';
 import { runCli } from '../src/cli.js';
-// Deliberately the only file in this package that is not unit tested directly - mirrors
-// botanary-mcp's own bin/botanary-mcp.ts, which wires the real runtime into runCli and nothing else.
+import { EXIT } from '../src/errors.js';
+// Deliberately the only file in this package that is not unit tested directly - it wires the real runtime
+// factory into runCli and traps SIGINT, and nothing else.
 const packageJson = await import('../package.json', { with: { type: 'json' } });
+// @clack/prompts leaves the cursor hidden and the terminal in raw mode if a prompt is interrupted, so a
+// bare Ctrl-C would hand back an unusable shell. Restore both, then exit with the conventional 130.
+process.on('SIGINT', () => {
+    process.stdout.write('\x1b[?25h');
+    if (process.stdin.isTTY)
+        process.stdin.setRawMode(false);
+    process.stdout.write('\n');
+    process.exit(EXIT.interrupted);
+});
 const exitCode = await runCli(process.argv.slice(2), {
-    runtime: createDefaultRuntime(),
+    createRuntime: (options) => createDefaultRuntime(options),
     cliVersion: packageJson.default.version,
 });
 process.exit(exitCode);

package/dist/bin/botanary.js.map

@@ -1 +1 @@
-{"version":3,"file":"botanary.js","sourceRoot":"","sources":["../../bin/botanary.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEvC,wFAAwF;AACxF,qGAAqG;AACrG,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;AAChF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACnD,OAAO,EAAE,oBAAoB,EAAE;IAC/B,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,OAAiB;CAClD,CAAC,CAAC;AACH,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"botanary.js","sourceRoot":"","sources":["../../bin/botanary.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC,0GAA0G;AAC1G,0DAA0D;AAC1D,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;AAEhF,wGAAwG;AACxG,oGAAoG;AACpG,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACzD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AACjC,CAAC,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IACnD,aAAa,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,oBAAoB,CAAC,OAAO,CAAC;IACzD,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,OAAiB;CAClD,CAAC,CAAC;AACH,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC"}

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "botanary",
     "type": "module",
-    "version": "0.1.0",
+    "version": "0.2.1",
     "description": "Botanary from your terminal - a guided CLI over the same wallet and agent lanes botanary-mcp exposes to a coding agent.",
     "license": "UNLICENSED",
     "homepage": "https://docs.botanary.xyz",
@@ -23,7 +23,7 @@
         "test:watch": "vitest"
     },
     "dependencies": {
-        "botanary-mcp": "^0.5.0",
+        "botanary-mcp": "^0.6.1",
         "commander": "^13.1.0",
         "@clack/prompts": "^0.9.1",
         "picocolors": "^1.1.1",

package/dist/src/app-url.js

@@ -0,0 +1,32 @@
+import { invalidArgs } from './errors.js';
+/** Surfaces `botanary open <target>` knows about. Each is a real route in the app. */
+export const APP_TARGETS = ['mandates', 'agents', 'history', 'yield', 'markets', 'settings'];
+/**
+ * The app origin for an API base URL, by dropping a leading `api.` label: `api.app.botanary.xyz` is served
+ * by Caddy in front of the same deployment as `app.botanary.xyz`.
+ *
+ * A host WITHOUT that label is returned unchanged rather than rewritten - guessing where someone's local
+ * or staging front end lives would open the wrong page silently, and a local stack can always pass
+ * `--api-url`.
+ */
+export function appOrigin(apiBaseUrl) {
+    try {
+        const url = new URL(apiBaseUrl);
+        if (url.hostname.startsWith('api.'))
+            url.hostname = url.hostname.slice('api.'.length);
+        return url.origin;
+    }
+    catch {
+        return apiBaseUrl;
+    }
+}
+export function appUrl(apiBaseUrl, target) {
+    const origin = appOrigin(apiBaseUrl);
+    if (!target)
+        return origin;
+    if (!APP_TARGETS.includes(target)) {
+        throw invalidArgs(`Unknown target "${target}". Try one of: ${APP_TARGETS.join(', ')}.`, 'Run `botanary open` with no argument to open the app root.');
+    }
+    return `${origin}/${target}`;
+}
+//# sourceMappingURL=app-url.js.map

package/dist/src/app-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-url.js","sourceRoot":"","sources":["../../src/app-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,sFAAsF;AACtF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAEtG;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,UAAkB;IAC1C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACtF,OAAO,GAAG,CAAC,MAAM,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,UAAU,CAAC;IACpB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,UAAkB,EAAE,MAAe;IACxD,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC;IAC3B,IAAI,CAAE,WAAiC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACzD,MAAM,WAAW,CACf,mBAAmB,MAAM,kBAAkB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EACpE,4DAA4D,CAC7D,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC;AAC/B,CAAC"}

package/dist/src/cli.js

@@ -1,3 +1,4 @@
+import { createDefaultRuntime } from 'botanary-mcp';
 import { CommanderError } from 'commander';
 import { createContext } from './context.js';
 import { createProgram } from './parser.js';
@@ -5,53 +6,142 @@ import { registerWalletCommands } from './commands/wallet.js';
 import { registerAgentCommands } from './commands/agent.js';
 import { registerMcpCommands } from './commands/mcp.js';
 import { registerSystemCommands } from './commands/system.js';
+import { registerUtilityCommands } from './commands/utilities.js';
 import { runRepl } from './repl.js';
-import { setColorEnabled } from './render/colors.js';
-import { isJsonMode } from './render/json-mode.js';
+import { colors, setColorEnabled } from './render/colors.js';
+import { readConfig } from './config-store.js';
+import { resolveSettings } from './settings.js';
+import { EXIT, CliError, errorEnvelope, errorLines, toCliError } from './errors.js';
+import { checkForUpdate, nagSuppressed, nagLine } from './update-check.js';
+/**
+ * Wrap fetch when, and only when, a global flag asks for it. `--timeout` needs an AbortController per
+ * request; `--debug` needs a line per request. Returns undefined otherwise so the ordinary path keeps
+ * using the platform fetch untouched.
+ *
+ * The debug line carries method, path and status only. No Botanary URL carries a credential in its query
+ * (botanary-mcp's test/no-leak.spec.ts pins that), and the bearer lives in a header this never reads.
+ */
+function wrapFetch(settings, stderr) {
+    if (settings.timeoutMs === null && !settings.debug)
+        return undefined;
+    return (async (input, init) => {
+        const started = Date.now();
+        const controller = new AbortController();
+        const timer = settings.timeoutMs === null ? null : setTimeout(() => controller.abort(), settings.timeoutMs);
+        try {
+            const response = await fetch(input, { ...init, signal: controller.signal });
+            if (settings.debug) {
+                const url = new URL(String(input instanceof Request ? input.url : input));
+                stderr(`[debug] ${init?.method ?? 'GET'} ${url.pathname}${url.search} ${response.status} ${Date.now() - started}ms`);
+            }
+            return response;
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    });
+}
+/**
+ * A courtesy line, on stderr so it can never corrupt piped output, and only where a human can act on it.
+ * The refresh is capped at 1.5s and runs at most once a day; every failure is silent. This must never be
+ * able to slow down or break a command.
+ */
+async function maybeNag(ctx, cliVersion, stderr) {
+    if (ctx.json || ctx.quiet || !ctx.interactive || nagSuppressed(process.env))
+        return;
+    try {
+        const result = await checkForUpdate(cliVersion, { fetchImpl: fetch, now: () => Date.now() });
+        if (result.newer && result.latest)
+            stderr(colors.dim(nagLine(result.latest, cliVersion)));
+    }
+    catch {
+        // Never let a courtesy check affect the command's outcome.
+    }
+}
 export async function runCli(argv, deps) {
     const stderr = deps.stderr ?? ((line) => process.stderr.write(`${line}\n`));
+    // Detect JSON mode early, before option parsing can throw, so an error envelope is always available.
+    // Check for explicit --json flag or non-TTY stdout (piped mode auto-enables JSON).
+    const jsonModeFromArgv = argv.includes('--json');
+    const jsonModeFromPipe = !process.stdout.isTTY;
+    const jsonModeEarly = jsonModeFromArgv || jsonModeFromPipe;
     const program = createProgram();
-    program.version(deps.cliVersion, '-V, --version', 'Print the installed botanary-cli version');
+    program.version(deps.cliVersion, '-v, --version', 'Print the installed botanary CLI version');
     registerWalletCommands(program);
     registerAgentCommands(program);
     registerMcpCommands(program);
     registerSystemCommands(program, deps.cliVersion);
+    registerUtilityCommands(program, deps.cliVersion);
     program.exitOverride();
+    let ctx = null;
     try {
         program.parseOptions(argv);
         const opts = program.opts();
-        // colors.ts's own default (pc.isColorSupported) already correctly auto-detects whether stdout is
-        // a real color-capable terminal - only override it to force OFF when the user explicitly opted
-        // out (--no-color, which commander surfaces as opts.color === false - not merely "falsy", since
-        // commander defaults opts.color to true when the flag isn't passed) or set NO_COLOR. Never force
-        // it ON: that was the bug - it made every ordinary invocation ignore the real TTY/pipe state.
-        if (opts.color === false || process.env.NO_COLOR) {
-            setColorEnabled(false);
+        // `-V` is the hidden alias for `-v` (commander allows one short flag per option), answered before
+        // any dispatch.
+        if (opts.V) {
+            process.stdout.write(`${deps.cliVersion}\n`);
+            return EXIT.ok;
+        }
+        // --home must land in the environment BEFORE anything resolves a path: the config file, the identity
+        // keystore and the session store all read botanaryMcpHome() at call time.
+        if (typeof opts.home === 'string' && opts.home) {
+            process.env.BOTANARY_MCP_HOME = opts.home;
         }
-        const ctx = createContext(deps.runtime, {
-            ...opts,
-            json: isJsonMode({ json: opts.json }, process.stdout),
-            interactive: opts.interactive === false ? false : !!process.stdin.isTTY && !!process.stdout.isTTY,
+        const settings = resolveSettings({
+            opts,
+            env: process.env,
+            file: await readConfig(),
+            stdout: process.stdout,
+            stdin: process.stdin,
         });
+        setColorEnabled(settings.color);
+        const runtime = deps.runtime ??
+            (deps.createRuntime ?? ((o) => createDefaultRuntime(o)))({
+                ...(settings.apiUrl ? { baseUrl: settings.apiUrl } : {}),
+                ...(() => {
+                    const wrapped = wrapFetch(settings, stderr);
+                    return wrapped ? { fetch: wrapped } : {};
+                })(),
+            });
+        ctx = createContext(runtime, settings);
         program.opts = () => ({ ...opts, __ctx: ctx });
-        if (argv.length === 0 && process.stdout.isTTY && !ctx.noInteractive) {
-            const session = await deps.runtime.walletSession();
-            const hasAgent = await deps.runtime.store.hasIdentity();
+        if (argv.length === 0 && process.stdout.isTTY && ctx.interactive) {
+            const session = await runtime.walletSession();
+            const hasAgent = await runtime.store.hasIdentity();
             await runRepl(program, { loggedIn: !!session, hasAgent });
-            return 0;
+            return EXIT.ok;
         }
         await program.parseAsync(argv, { from: 'user' });
-        return 0;
+        await maybeNag(ctx, deps.cliVersion, stderr);
+        return ctx.outcome.exit;
     }
     catch (e) {
         if (e instanceof CommanderError) {
-            if (e.exitCode !== 0) {
-                stderr(e.message);
+            // Map usage errors (unknown command, unknown option, missing argument) to exit 2.
+            // Keep exit 0 for --help and --version (commander reports those as errors too).
+            const isUsageError = e.code === 'commander.unknownCommand' || e.code === 'commander.unknownOption' || e.code === 'commander.missingMandatoryOptionValue';
+            if (isUsageError) {
+                if (jsonModeEarly) {
+                    console.log(JSON.stringify(errorEnvelope(new CliError(e.message, 'invalid_args', EXIT.invalidArgs))));
+                }
+                return EXIT.invalidArgs;
             }
+            // Help and version are exit 0
+            if (e.code === 'commander.help' || e.code === 'commander.version') {
+                return EXIT.ok;
+            }
+            // Fallback for any other CommanderError
             return e.exitCode;
         }
-        stderr(e instanceof Error ? e.message : String(e));
-        return 1;
+        const err = toCliError(e);
+        if (ctx?.json || jsonModeEarly) {
+            console.log(JSON.stringify(errorEnvelope(err)));
+        }
+        for (const line of errorLines(err))
+            stderr(line);
+        return err.exit;
     }
 }
 //# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}