@agentgrant.cash/cli 1.0.0

package/.env.example

@@ -0,0 +1,21 @@
+# Grant Cash CLI — backend routing.
+#
+# Copy to `.env` (loaded from the PACKAGE ROOT only — never the cwd). Every value
+# is optional; the defaults point at production. Set these to repoint at dev /
+# staging without touching code. You do NOT need to know the final URLs to build
+# the CLI — wire them here whenever they're ready.
+
+# ── Money side (Perfolio backend — gold, portfolio, cash) ──
+GRANTCASH_API_URL=https://api.perfolio.ai/api
+GRANTCASH_FIAT_URL=https://api-fiat.perfolio.ai/api
+GRANTCASH_APP_URL=https://app.perfolio.ai
+
+# ── Agent side (Agent-mode backend — pay-per-use services, x402) ──
+# Set this to wherever the agent-mode backend lives (placeholder default).
+GRANTCASH_AGENT_URL=https://api-agent.perfolio.ai
+
+# ── Misc ──
+# Override the merged credentials file (default ~/.grant-cash/credentials.json).
+# GRANTCASH_CREDS_FILE=/path/to/credentials.json
+# Label the connecting client (shown to the user during login).
+# GRANTCASH_CLIENT="Grant Cash CLI"

package/README.md

@@ -0,0 +1,48 @@
+# Grant Cash CLI (`grant`)
+
+One CLI for your **money** (gold, via the Perfolio backend) and your **agent**
+(pay-per-use services, via the Agent-mode backend). Two engines, one wallet, one
+identity — behind a single plain-language surface. The user never sees which
+backend answered.
+
+Built on the Perfolio CLI's structure (Commander + modular `cli/commands` +
+`lib/*`), merged with the agent CLI's LLM-friendly output and verb set.
+
+## Quick start
+
+```bash
+npm install
+cp .env.example .env      # set the backend URLs (optional — prod defaults shipped)
+npm run dev -- status     # run from source
+npm run build && ./dist/cli/index.js status
+```
+
+## How routing works
+
+| Surface | Routes to | Auth |
+|---|---|---|
+| money: `portfolio`, `price`, `buy`, `sell`, `activity` | Perfolio backend (`GRANTCASH_API_URL`) | Bearer device token (`pfk_`) |
+| agent: `search`, `check`, `fetch`, `transfer`, `revoke` | Agent-mode backend (`GRANTCASH_AGENT_URL`) | `X-API-Key` (`grant_live_`) |
+
+`grant login` runs the money-side device handshake (browser sign-in + limit
+approval) and links the agent key in one step. Credentials for both live in one
+file (`~/.grant-cash/credentials.json`).
+
+## Configuration
+
+All URLs are env-driven — see [`.env.example`](.env.example). You do **not** need
+final URLs to build; set them whenever they're ready.
+
+## Skill file
+
+[`skills/grant-cash/SKILL.md`](skills/grant-cash/SKILL.md) documents the full
+command surface, workflow, and error playbook for an AI assistant.
+
+## Status
+
+Scaffold of the merged architecture with a working command set across both
+engines. Money side is gold-focused by design; borrow/earn/perps endpoints are a
+one-method-each extension on `MoneyClient`. The unified `login` links the agent
+key via `--agent-key`/`GRANTCASH_AGENT_KEY` today; once the backends share one
+connect (the planned `device/complete` carrying the partner key), a single poll
+will return both credentials and only that step changes.

package/dist/cli/commands/agent.js

@@ -0,0 +1,139 @@
+import { buildContext, emit, ui, usdcMinor, NotConnectedError } from "../../lib/index.js";
+/**
+ * Agent side — pay-per-use services routed to the Agent-mode backend. Every
+ * spend is owned by the session (delegated, revocable, guardrailed); the CLI
+ * carries only the API key. Verbs mirror the agent CLI so a model that knows it
+ * drives this with no relearning: search → check → fetch.
+ */
+export function registerAgent(program) {
+    program
+        .command("search <query>")
+        .alias("marketplace")
+        .description("Find a pay-per-use service the agent can use")
+        .option("--limit <n>", "max results", "10")
+        .action(async (query, opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.search(query, Math.max(1, Number(opts.limit) || 10));
+        emit(ctx, { results: data }, () => `${ui.title("Services")} ${ui.dim("(use --json for details)")}`);
+    });
+    program
+        .command("check <url>")
+        .description("See the exact contract for a service before paying (no charge)")
+        .action(async (url, _opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.check(url);
+        emit(ctx, { contract: data }, () => `${ui.title("Contract")} ${ui.dim("(use --json for the schema)")}`);
+    });
+    program
+        .command("fetch <url>")
+        .alias("pay")
+        .description("Pay for and run a service")
+        .option("-m, --method <method>", "HTTP method (GET|POST|PUT|DELETE|PATCH)")
+        .option("-b, --body <json>", "request body, passed through verbatim")
+        .option("--price <minor>", "spend cap in USDC minor units (inferred from the service if omitted)")
+        .option("--asset <asset>", "settlement asset (USDC|USDT)", "USDC")
+        .action(async (url, opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        // Resolve the spend cap, method, and rail from the same free `check`
+        // endpoint, so a model can call `fetch` without first running `check` and
+        // we never POST without the backend-required `expectedPriceMinor`. An
+        // explicit --price still wins; an explicit --method still wins.
+        let method = (opts.method ? String(opts.method) : "GET").toUpperCase();
+        const asset = String(opts.asset || "USDC").toUpperCase();
+        let price = opts.price;
+        try {
+            const chk = (await ctx.agent.check(url));
+            if (chk?.found) {
+                if (!opts.method && typeof chk.method === "string")
+                    method = chk.method.toUpperCase();
+                if (!price && chk.priceMinor != null)
+                    price = String(chk.priceMinor);
+            }
+        }
+        catch {
+            // check unreachable — with an explicit --price we still pay; else fail below.
+        }
+        if (!price)
+            throw new Error("Couldn't determine the price — run `grant check <url>` or pass --price <USDC minor units>.");
+        const data = await ctx.agent.fetchPay({
+            url,
+            method,
+            expectedPriceMinor: price,
+            asset,
+            // Raw string passthrough — the backend forwards it verbatim. We do NOT
+            // JSON.parse: the x402/pay schema expects `body` as a string.
+            ...(opts.body ? { body: String(opts.body) } : {}),
+        });
+        emit(ctx, { result: data }, () => ui.green("✓ Done."));
+    });
+    program
+        .command("discover <origin>")
+        .alias("add")
+        .description("Ingest any x402 service origin so the agent can find + pay its endpoints")
+        .action(async (origin, _opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.discover(origin);
+        emit(ctx, { result: data }, () => ui.green(`✓ Ingested ${origin}. Find its services with \`grant search\`.`));
+    });
+    program
+        .command("schema <slug>")
+        .description("See the exact pay contract for a catalog service by slug (no charge)")
+        .action(async (slug, _opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.schema(slug);
+        emit(ctx, { schema: data }, () => `${ui.title("Contract")} ${ui.dim("(use --json for the schema)")}`);
+    });
+    program
+        .command("redeem <code>")
+        .description("Claim an invite or bonus credit for your agent spending")
+        .action(async (code, _opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.redeem(code);
+        emit(ctx, { result: data }, () => ui.green("✓ Redeemed. Check your spending balance with `grant portfolio`."));
+    });
+    program
+        .command("upgrade")
+        .description("Get a one-time link to secure a full account and add spending funds")
+        .action(async (_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.linkCode();
+        emit(ctx, data, () => `${ui.title("Secure your account")}\n  Open this link (works once, expires in ~15 min):\n\n  ${ui.green(data.url)}\n  code: ${data.code}`);
+    });
+    program
+        .command("transfer <recipient> <amount>")
+        .description("Send money to an address (amount in USDC minor units)")
+        .option("--asset <asset>", "USDC|USDT", "USDC")
+        .action(async (recipient, amount, opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const asset = String(opts.asset || "USDC").toUpperCase();
+        const data = await ctx.agent.transfer({ recipient, amount, asset });
+        emit(ctx, { result: data }, () => ui.green(`✓ Sent ${usdcMinor(amount)} ${asset} to ${recipient}.`));
+    });
+    program
+        .command("revoke")
+        .alias("stop")
+        .description("Stop all agent spending immediately (revoke the session)")
+        .action(async (_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.revoke();
+        emit(ctx, { revoked: true, result: data }, () => ui.red("■ Stopped. Your agent can no longer spend until you reconnect."));
+    });
+}

package/dist/cli/commands/auth.js

@@ -0,0 +1,248 @@
+import { buildContext, emit, ui, startDevice, waitForDevice, moneyPollIntervalMs, revokeDevice, listDevices, detectClient, openBrowser, clearCredentials, AppError, generatePkce, startAgentDevice, waitForAgentDevice, agentPollIntervalMs, } from "../../lib/index.js";
+/**
+ * `grant login` — one connect for both engines.
+ *
+ * Runs TWO device handshakes in a single pass so the user thinks about one
+ * connect, not two backends:
+ *   - MONEY side (Perfolio): `cli/device/*`, sid relayed to the browser via the
+ *     connect URL, mints a `pfk_` Bearer token.
+ *   - AGENT side (Agent-mode): PKCE S256 `onboard/privy-cli/device/*`, its sid
+ *     relayed alongside as `&agentSid=<sid>`, mints a `grant_live_` X-API-Key.
+ *
+ * The agent sid is generated first so it can be carried on the SAME browser link
+ * the user opens; the one logged-in browser session completes both backends. We
+ * then poll each backend independently (each with its own secret) and write BOTH
+ * credentials to the existing merged file. An explicit `--agent-key`/env key
+ * still short-circuits the agent handshake (manual linking).
+ *
+ * Partial-failure is never silent: if money connects but spending stays
+ * pending/expired we report "investing connected, spending pending" plus a retry
+ * hint. A `complete` with no apiKey = already provisioned → keep the existing key.
+ */
+function maskKey(k) {
+    if (!k)
+        return "(none)";
+    return k.length <= 12 ? "****" : `${k.slice(0, 9)}…${k.slice(-4)}`;
+}
+export function registerAuth(program) {
+    program
+        .command("login")
+        .description("Connect Grant Cash — your money and your agent, in one step")
+        .option("--no-open", "do not auto-open the browser; just print the URL")
+        .option("--agent-key <key>", "link your agent key (grant_live_…) in the same step")
+        .option("--timeout <seconds>", "how long to wait for the browser", "300")
+        .action(async (opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const client = detectClient();
+        const timeoutMs = Math.max(30, Number(opts.timeout) || 300) * 1000;
+        // An explicit key (flag/env) means "link this, skip the agent handshake".
+        const manualAgentKey = opts.agentKey || process.env.GRANTCASH_AGENT_KEY;
+        const runAgentFlow = !manualAgentKey;
+        // ── start BOTH handshakes (agent first so its sid rides the same link) ──
+        const start = await startDevice(ctx.urls.api, client, client);
+        // Agent side is best-effort to start: if the agent backend is unreachable
+        // we still let the money connect succeed and report spending as pending.
+        let agentPkce;
+        let agentSid;
+        let agentPollMs = 3000;
+        let agentStartError;
+        if (runAgentFlow) {
+            agentPkce = generatePkce();
+            try {
+                const aStart = await startAgentDevice(ctx.urls.agent, agentPkce, client);
+                agentSid = aStart.sid;
+                agentPollMs = agentPollIntervalMs(aStart.pollInterval);
+            }
+            catch (e) {
+                agentStartError = e;
+            }
+        }
+        // Open the Grant Cash connect screen (GRANTCASH_APP_URL) carrying the
+        // one-time money sid — NOT the backend's own URL — so sign-in happens in
+        // the Grant Cash UI. The agent sid rides the SAME link as `&agentSid` so a
+        // single logged-in browser completes both backends. The sids are the only
+        // secrets; minting still requires a logged-in browser (and, for the agent,
+        // the PKCE verifier held only in this process), so the link alone is useless.
+        let connectUrl = `${ctx.urls.app.replace(/\/$/, "")}/connect?sid=${encodeURIComponent(start.sid)}&client=${encodeURIComponent(client)}`;
+        if (agentSid)
+            connectUrl += `&agentSid=${encodeURIComponent(agentSid)}`;
+        if (!ctx.json) {
+            process.stdout.write(`\n${ui.title("Connect Grant Cash")}\n` +
+                `Open this link to sign in and approve your limits:\n\n  ${ui.green(connectUrl)}\n\n` +
+                ui.dim("Waiting for you to finish in the browser…") +
+                "\n");
+        }
+        if (opts.open !== false)
+            openBrowser(connectUrl);
+        // ── poll BOTH backends (each with its own secret) ──
+        // Money is the primary identity; the agent (spending) side is best-effort.
+        // Both polls run concurrently, but we SETTLE on money: the moment it
+        // connects we stop blocking on the agent poll (a slow/cold spending backend
+        // or a stale agent sid must never leave the terminal "still polling" after
+        // the browser has finished). The browser completes the agent device in
+        // step 1 — BEFORE it mints money in step 3 — so the agent key is almost
+        // always already waiting by the time money lands; a short grace collects it.
+        const moneyP = waitForDevice(ctx.urls.api, start.sid, moneyPollIntervalMs(start.pollInterval), timeoutMs);
+        const agentAbort = new AbortController();
+        const agentP = agentSid && agentPkce
+            ? waitForAgentDevice(ctx.urls.agent, agentSid, agentPkce.verifier, agentPollMs, timeoutMs, fetch, agentAbort.signal)
+            : Promise.resolve({ status: "expired" });
+        const result = await moneyP;
+        // Money is the primary identity — if it didn't complete, the whole login
+        // failed (mirrors the original behavior). Abort the agent poll first so the
+        // process can exit promptly instead of running to the agent timeout.
+        if (result.status !== "complete") {
+            agentAbort.abort();
+            throw new AppError(result.status === "denied"
+                ? "Connection was declined in the browser."
+                : "Connection timed out. Run `grant login` again.", { code: result.status === "denied" ? "DENIED" : "EXPIRED", recoverable: true });
+        }
+        // Money connected — settle now. Give the agent poll a short grace to also
+        // land, then stop regardless and report whatever we have (a grace timeout
+        // → "spending pending", surfaced with a retry hint below). Aborting after
+        // the race stops the background loop so the CLI exits without hanging.
+        const AGENT_SETTLE_GRACE_MS = 15_000;
+        const agentResult = await Promise.race([
+            agentP.catch(() => ({ status: "pending" })),
+            new Promise((res) => setTimeout(() => res({ status: "pending" }), AGENT_SETTLE_GRACE_MS)),
+        ]);
+        agentAbort.abort();
+        // ── resolve the agent credential ──
+        // Precedence: explicit manual key > freshly minted key > already-provisioned
+        // (complete without apiKey → keep the key already on disk).
+        const existingAgentKey = ctx.creds.agent?.apiKey;
+        let agentKey = manualAgentKey;
+        let agentState;
+        if (manualAgentKey) {
+            agentState = "linked";
+        }
+        else if (agentResult.status === "complete") {
+            if (agentResult.apiKey) {
+                agentKey = agentResult.apiKey; // one-time pickup of the new key
+                agentState = "minted";
+            }
+            else {
+                agentKey = existingAgentKey; // already provisioned — keep what we have
+                agentState = "already";
+            }
+        }
+        else {
+            agentKey = existingAgentKey; // never clobber an existing key on a miss
+            agentState = agentResult.status === "expired" ? "expired" : "pending";
+        }
+        const spendingConnected = Boolean(agentKey);
+        const next = {
+            ...ctx.creds,
+            money: {
+                token: result.result.token,
+                refreshToken: result.result.refreshToken,
+                expiresAt: result.result.expiresAt,
+                email: result.result.email,
+                walletAddress: result.result.walletAddress,
+                deviceId: result.result.deviceId,
+            },
+            ...(agentKey ? { agent: { apiKey: agentKey } } : {}),
+        };
+        ctx.save(next);
+        // Retry hint for the spending side when it didn't land this pass.
+        const retryHint = agentStartError
+            ? "Run `grant login` again to finish spending setup (the spending backend was unreachable)."
+            : "Run `grant login` again to finish spending setup.";
+        emit(ctx, {
+            connected: true,
+            money: { email: result.result.email, wallet: result.result.walletAddress },
+            agent: {
+                connected: spendingConnected,
+                state: agentState,
+                ...(agentState === "pending" || agentState === "expired"
+                    ? { hint: retryHint }
+                    : {}),
+            },
+        }, () => {
+            const moneyLine = `\n  Money:  ${result.result.email || result.result.walletAddress}`;
+            let agentLine;
+            switch (agentState) {
+                case "linked":
+                    agentLine = `\n  Agent:  ${ui.green("linked")}`;
+                    break;
+                case "minted":
+                    agentLine = `\n  Agent:  ${ui.green("connected")}`;
+                    break;
+                case "already":
+                    agentLine = `\n  Agent:  ${ui.green("connected (already set up)")}`;
+                    break;
+                default:
+                    agentLine =
+                        `\n  Agent:  ${ui.amber("spending pending")}` +
+                            `\n${ui.dim("          " + retryHint)}`;
+            }
+            const header = spendingConnected || agentState === "linked"
+                ? ui.green("✓ Connected.")
+                : ui.green("✓ Investing connected.") +
+                    ui.amber(" Spending still pending.");
+            return `\n${header}${moneyLine}${agentLine}\n`;
+        });
+    });
+    program
+        .command("logout")
+        .description("Disconnect — revoke this device and clear stored credentials")
+        .action(async (_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (ctx.creds.money?.token) {
+            await revokeDevice(ctx.urls.api, ctx.creds.money.token, ctx.creds.money.deviceId);
+        }
+        clearCredentials(ctx.credsPath);
+        emit(ctx, { disconnected: true }, () => ui.dim("Disconnected. Credentials cleared."));
+    });
+    program
+        .command("status")
+        .alias("whoami")
+        .description("Show what's connected (money + agent) and where it routes")
+        .action(async (_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const money = ctx.creds.money;
+        const agent = ctx.creds.agent;
+        emit(ctx, {
+            money: {
+                connected: Boolean(money?.token),
+                email: money?.email,
+                wallet: money?.walletAddress,
+            },
+            agent: { connected: Boolean(agent?.apiKey), key: maskKey(agent?.apiKey) },
+            routes: { api: ctx.urls.api, fiat: ctx.urls.fiat, agent: ctx.urls.agent },
+        }, () => `${ui.title("Grant Cash")}\n` +
+            `  Money:  ${money?.token ? ui.green(money.email || money.walletAddress || "connected") : ui.amber("not connected")}\n` +
+            `  Agent:  ${agent?.apiKey ? ui.green(maskKey(agent.apiKey)) : ui.amber("not connected")}\n` +
+            ui.dim(`  → money ${ctx.urls.api}\n  → agent ${ctx.urls.agent}`));
+    });
+    // ── manage connected agents/devices (money side) ──
+    const devices = program.command("devices").description("Manage connected agents/devices");
+    devices
+        .command("list")
+        .description("List devices connected to your account")
+        .action(async (_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const token = ctx.creds.money?.token;
+        if (!token)
+            throw new AppError("Not connected. Run `grant login` first.", { code: "NOT_CONNECTED" });
+        const list = await listDevices(ctx.urls.api, token);
+        emit(ctx, { devices: list }, () => {
+            if (!list.length)
+                return ui.dim("No devices connected.");
+            const rows = list.map((d) => `  ${d.deviceId.slice(0, 10).padEnd(11)} ${(d.clientName || d.deviceName || "—").padEnd(20)} ` +
+                ui.dim(`last used ${d.lastUsedAt ? new Date(d.lastUsedAt).toISOString().slice(0, 10) : "—"}`));
+            return `${ui.title("Connected devices")}\n${rows.join("\n")}`;
+        });
+    });
+    devices
+        .command("revoke <deviceId>")
+        .description("Revoke a connected device by id")
+        .action(async (deviceId, _opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const token = ctx.creds.money?.token;
+        if (!token)
+            throw new AppError("Not connected. Run `grant login` first.", { code: "NOT_CONNECTED" });
+        await revokeDevice(ctx.urls.api, token, deviceId);
+        emit(ctx, { revoked: true, deviceId }, () => ui.green(`✓ Revoked device ${deviceId}.`));
+    });
+}

package/dist/cli/commands/meta.js

@@ -0,0 +1,77 @@
+import { fileURLToPath } from "node:url";
+import { buildContext, emit, ui } from "../../lib/index.js";
+/** The agent-facing workflow + error playbook, so a model can self-orient. */
+const WORKFLOW = [
+    "status — confirm what's connected (money + agent) before acting.",
+    "portfolio — combined worth: gold, cash, bitcoin, ethereum, perps, predictions, earn + agent spending money.",
+    "prices / price — live prices. assets / markets — what you can hold / borrow against.",
+    "buy <asset> --amount <cash> / sell <asset> --for <cash> / convert — trade gold, cash, bitcoin, ethereum. quote — preview.",
+    "borrow / repay / add-collateral / remove-collateral / leverage / close — cash borrowed against an asset.",
+    "earn list / position / deposit / withdraw — yield on cash & crypto via vaults.",
+    "hl … — Hyperliquid perps (markets, status, open, close, leverage, tpsl, deposit, withdraw).",
+    "polymarket markets / bet / cashout / redeem / wallet / provision / deposit / withdraw / positions / history — prediction markets.",
+    "kyc / fiat / withdraw / gift / beneficiaries / settings — identity, cash-out, gifting, preferences.",
+    "search <q> — find a pay-per-use service. discover <origin> — ingest a new x402 origin. check <url> / schema <slug> — see exact contract (no charge).",
+    "fetch <url> -b '<json>' — pay for and run a service. transfer <addr> <minor> — send money. redeem <code> — claim credit. upgrade — secure full account.",
+    "devices list / devices revoke <id> — manage connected agents.",
+    "activity — one feed of money moves + live-service spend. tx status / history — on-chain tx state.",
+    "revoke — stop ALL agent spend immediately (terminal).",
+];
+const ERROR_CODES = [
+    { code: "NOT_CONNECTED", recoverable: false, action: "Run `grant login`." },
+    { code: "NO_SESSION", recoverable: false, action: "No spending permission set — `grant login` and approve limits." },
+    { code: "GUARDRAIL_DENIED", recoverable: false, action: "STOP. The user's caps forbid this — don't retry. Tell the user." },
+    { code: "SIGNER_REVOKED", recoverable: false, action: "STOP. The session was revoked — re-authorize via `grant login`." },
+    { code: "SCHEMA_VALIDATION_FAILED", recoverable: true, action: "Free reject. Run `grant check <url>` and rebuild --body, then retry." },
+    { code: "BACKEND_UNREACHABLE", recoverable: false, action: "Wrong/dead base URL — check GRANTCASH_* env / `grant config show`." },
+    { code: "NETWORK", recoverable: true, action: "Transient — retry once." },
+];
+export function registerMeta(program) {
+    program
+        .command("instructions")
+        .description("How an agent should drive this CLI (workflow + error playbook)")
+        .action((_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        emit(ctx, { workflow: WORKFLOW, errorCodes: ERROR_CODES }, () => `${ui.title("Grant Cash — agent workflow")}\n` +
+            WORKFLOW.map((w, i) => `  ${i + 1}. ${w}`).join("\n") +
+            `\n\n${ui.title("Error playbook")}\n` +
+            ERROR_CODES.map((e) => `  ${e.code} ${ui.dim(e.recoverable ? "(retry ok)" : "(terminal)")} — ${e.action}`).join("\n"));
+    });
+    const config = program.command("config").description("Inspect or set CLI configuration");
+    config
+        .command("show")
+        .description("Show resolved routes and connection state")
+        .action((_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const key = ctx.creds.agent?.apiKey;
+        emit(ctx, {
+            routes: ctx.urls,
+            money: { connected: Boolean(ctx.creds.money?.token) },
+            agent: { connected: Boolean(key) },
+            credsPath: ctx.credsPath,
+        }, () => `${ui.title("Routes")}\n` +
+            `  money api   ${ctx.urls.api}\n` +
+            `  money fiat  ${ctx.urls.fiat}\n` +
+            `  agent       ${ctx.urls.agent}\n` +
+            ui.dim(`  creds       ${ctx.credsPath}`));
+    });
+    config
+        .command("set-agent-key <key>")
+        .description("Link your agent key (grant_live_…)")
+        .action((key, _opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const next = { ...ctx.creds, agent: { apiKey: key } };
+        ctx.save(next);
+        emit(ctx, { linked: true }, () => ui.green("✓ Agent key linked."));
+    });
+    program
+        .command("install")
+        .description("Where to find the skill file + how to connect an assistant")
+        .action((_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const skill = fileURLToPath(new URL("../../../skills/grant-cash/SKILL.md", import.meta.url));
+        emit(ctx, { skillFile: skill }, () => `${ui.title("Connect an assistant")}\n` +
+            `  Skill file: ${skill}\n` +
+            ui.dim("  Point your assistant at the skill file, or use the Grant Cash MCP."));
+    });
+}

package/dist/cli/commands/money.js

@@ -0,0 +1,85 @@
+import { buildContext, emit, ui, usdcMinor, } from "../../lib/index.js";
+/**
+ * Money side — gold price + the combined activity feed.
+ *
+ * Buying/selling moved to the generalized multi-asset `trade` commands
+ * (`grant buy <asset>` / `grant sell <asset>` / `grant convert`), ported from
+ * the standalone Perfolio CLI so the merged CLI trades gold, bitcoin, ethereum
+ * and cash — not just gold. `price` (today's gold price) and `activity` (the
+ * unified money + spending feed) stay here.
+ */
+/** A compact one-line render for a money (Perfolio) tx-history row. Defensive about shape. */
+function moneyRow(raw) {
+    const t = (raw ?? {});
+    const date = typeof t.createdAt === "string" ? t.createdAt.slice(0, 10) : "—";
+    const type = t.type ?? "tx";
+    const status = t.status ?? "—";
+    const meta = t.metadata ?? {};
+    const detail = [meta.sellToken, meta.buyToken].filter(Boolean).join("→") || t.txHash || "";
+    return `  ${date}  ${type.padEnd(10)} ${status.padEnd(11)} ${detail}`;
+}
+/** A compact one-line render for an agent (spending) tx row. Defensive about shape. */
+function agentRow(raw) {
+    const t = (raw ?? {});
+    const ts = typeof t.createdAt === "number" ? new Date(t.createdAt).toISOString().slice(0, 10) : "—";
+    const amount = typeof t.amount === "string" ? t.amount : usdcMinor(t.amount);
+    const asset = t.asset ?? "USDC";
+    const status = t.status ?? "—";
+    const who = t.vendorSlug ?? t.recipient ?? "";
+    return `  ${ts}  ${String(amount).padStart(8)} ${asset}  ${status.padEnd(11)} ${who}`;
+}
+function asArray(v, key) {
+    if (Array.isArray(v))
+        return v;
+    const obj = (v ?? {});
+    return Array.isArray(obj[key]) ? obj[key] : [];
+}
+export function registerMoney(program) {
+    program
+        .command("price")
+        .alias("gold")
+        .description("Today's gold price (see `grant prices` for every asset)")
+        .action(async (_opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const data = await ctx.money.getGoldPrice();
+        emit(ctx, { gold: data }, () => {
+            const p = data.price ?? data.usd;
+            return `${ui.title("Gold")}  ${p != null ? ui.green(`$${p}`) : JSON.stringify(data)}`;
+        });
+    });
+    program
+        .command("activity")
+        .alias("history")
+        .description("One feed — money moves and your agent's live work")
+        .option("--limit <n>", "how many items", "20")
+        .action(async (opts, cmd) => {
+        const ctx = buildContext(cmd);
+        const limit = Math.max(1, Number(opts.limit) || 20);
+        const [moneyR, agentR] = await Promise.allSettled([
+            ctx.money.connected ? ctx.money.getTxHistory(limit) : Promise.resolve(null),
+            ctx.agent.connected ? ctx.agent.transactions(limit) : Promise.resolve(null),
+        ]);
+        const money = moneyR.status === "fulfilled" ? moneyR.value : null;
+        const agent = agentR.status === "fulfilled" ? agentR.value : null;
+        emit(ctx, { money, agent }, () => {
+            if (!ctx.money.connected && !ctx.agent.connected)
+                return "Not connected yet. Run `grant login`.";
+            const lines = [ui.title("Activity")];
+            const moneyRows = asArray(money, "data");
+            const agentRows = asArray(agent, "transactions");
+            if (moneyRows.length) {
+                lines.push(ui.dim("  Money"));
+                for (const r of moneyRows)
+                    lines.push(moneyRow(r));
+            }
+            if (agentRows.length) {
+                lines.push(ui.dim("  Spending"));
+                for (const r of agentRows)
+                    lines.push(agentRow(r));
+            }
+            if (!moneyRows.length && !agentRows.length)
+                lines.push(ui.dim("  Nothing yet."));
+            return lines.join("\n");
+        });
+    });
+}