json

Author: benjaminjnoack

AGENTS.md

@@ -10,6 +10,7 @@ You are Codex, based on GPT-5. You are running as a coding agent in the Codex CL
 - When multiple tool calls can be parallelized (e.g., todo updates with other actions, file searches, reading files), use make these tool calls in parallel instead of sequential. Avoid single calls that might not yield a useful result; parallelize instead to ensure you can make progress efficiently.
 - Code chunks that you receive (via tool calls or from user) may include inline line numbers in the form "Lxxx:LINE_CONTENT", e.g. "L123:LINE_CONTENT". Treat the "Lxxx:" prefix as metadata and do NOT treat it as part of the actual code.
 - Default expectation: deliver working code, not just a plan. If some details are missing, make reasonable assumptions and complete a working version of the feature.
+- Prefer machine-readable CLI output when available: `cb ... --json` and `hdb ... --json` should be the default inspection path for agent workflows, with `--json-file <path>` used when a command supports writing the same payload to disk.
 
 
 # Autonomy and Persistence

CLAUDE.md

@@ -42,6 +42,7 @@ TypeScript ESM monorepo (`module: NodeNext`). Three CLIs share a `src/shared/` l
 - `test/setup/no-network.ts` — global outbound-network block active in `vitest.config.ts`
 
 **Use explicit relative imports with `.js` specifiers** (NodeNext resolution).
+Prefer machine-readable CLI output for local inspection and automation when available: `cb ... --json` and `hdb ... --json`, plus `--json-file <path>` on commands that support file output.
 
 ### cb app boundaries
 

README.md

@@ -57,6 +57,11 @@ From source:
 - `npm run dev -- --help` (runs `cb`)
 - `npm run dev:hdb -- --help` (runs `hdb`)
 
+Machine-readable CLI output:
+
+- prefer `cb ... --json` and `hdb ... --json` when you want structured output for automation or agent workflows
+- use `--json-file <path>` on commands that expose it when you want the same payload written to disk
+
 ## Documentation
 
 - [`cb CLI README`](src/apps/cb/README.md)

src/apps/cb/README.md

@@ -90,14 +90,16 @@ Notes:
 
 - `[product]` defaults to `BTC` when omitted.
 - Use `cb <command> --help` for command-specific options.
+- Prefer `cb ... --json` when you want machine-readable output for automation or agent workflows.
 
 ## Commands
 
 ### Accounts
 
-- `cb accounts [product] [--crypto] [--cash] [--json [filepath]] [--raw] [--value]` (alias: `account`)
+- `cb accounts [product] [--crypto] [--cash] [--json] [--json-file <path>] [--raw] [--value]` (alias: `account`)
   - non-zero balances by default; hold/available are formatted to each currency's base increment using cached product metadata when present unless `--raw` is used
-  - `--json` writes all fetched accounts to `./accounts.json` by default, or to the provided filepath; export rows include currency, type, hold, and available, and honor `--crypto`, `--cash`, and `--raw`
+  - `--json` prints `{ rows, filters, meta }` for machine reading
+  - `--json-file <path>` writes the same structured payload to disk and still prints JSON to stdout
   - `--value` adds a USD value column based on current product price (forced product refresh for supported products)
   - when `[product]` is provided, matching accounts are shown with price-based USD values
 - `cb balance` (alias: `usd`)
@@ -156,6 +158,18 @@ Notes:
   - `--baseSize`, `--limitPrice`, `--stopPrice` are supported
   - `--takeProfitPrice` is rejected
 
+## Troubleshooting Workflow
+
+Prefer `cb accounts --json` when you want a stable machine-readable account snapshot for automation or agent-assisted inspection.
+
+Examples:
+
+```bash
+cb accounts --json
+cb accounts btc-usd --json
+cb accounts --crypto --raw --json-file tmp/accounts.json
+```
+
 ## Development
 
 - `npm run lint`

src/apps/cb/commands/account-handlers.ts

@@ -1,4 +1,4 @@
-import { writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import type { AccountsOptions } from "./schemas/command-options.js";
@@ -31,6 +31,25 @@ type AccountExportRow = {
   type: CoinbaseAccount["type"];
   hold: string;
   available: string;
+  price?: string | null;
+  holdValueUsd?: string | null;
+  availableValueUsd?: string | null;
+  totalValueUsd?: string | null;
+};
+
+type AccountsJsonPayload = {
+  rows: AccountExportRow[];
+  filters: {
+    product: string | null;
+    currency: string | null;
+    crypto: boolean;
+    cash: boolean;
+    raw: boolean;
+    value: boolean;
+  };
+  meta: {
+    rowCount: number;
+  };
 };
 
 function formatAccountSize(value: string, baseIncrement: string, raw: boolean | undefined): string {
@@ -94,15 +113,89 @@ function toAccountBalanceRow(
   };
 }
 
-function writeAccountsJson(accounts: AccountExportRow[], jsonOption: boolean | string | undefined) {
-  if (!jsonOption) {
-    return;
-  }
-  const outputPath = typeof jsonOption === "string" && jsonOption.length > 0
-    ? path.resolve(process.cwd(), jsonOption)
-    : path.join(process.cwd(), "accounts.json");
-  writeFileSync(outputPath, `${JSON.stringify(accounts, null, 2)}\n`);
-  console.log(`Wrote accounts JSON to ${outputPath}`);
+function buildAccountsJsonPayload(
+  rows: AccountExportRow[],
+  options: AccountsOptions,
+  product: string | null,
+): AccountsJsonPayload {
+  return {
+    rows,
+    filters: {
+      product,
+      currency: product ? product.split("-")[0] ?? null : null,
+      crypto: Boolean(options.crypto),
+      cash: Boolean(options.cash),
+      raw: Boolean(options.raw),
+      value: Boolean(options.value),
+    },
+    meta: {
+      rowCount: rows.length,
+    },
+  };
+}
+
+function printAccountsJson(payload: AccountsJsonPayload): void {
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+function writeAccountsJsonFile(payload: AccountsJsonPayload, jsonFile: string): void {
+  const outputPath = path.resolve(process.cwd(), jsonFile);
+  mkdirSync(path.dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function buildProductJsonRows(
+  accounts: CoinbaseAccount[],
+  price: string,
+  priceIncrement: string,
+): AccountExportRow[] {
+  return accounts.map((acc) => {
+    const hold = acc.hold.value;
+    const available = acc.available_balance.value;
+    const holdValueUsd = toIncrement(priceIncrement, parseFloat(hold) * parseFloat(price));
+    const availableValueUsd = toIncrement(priceIncrement, parseFloat(available) * parseFloat(price));
+    return {
+      currency: acc.currency,
+      type: acc.type,
+      price,
+      hold,
+      available,
+      holdValueUsd,
+      availableValueUsd,
+      totalValueUsd: toIncrement(
+        priceIncrement,
+        parseFloat(holdValueUsd) + parseFloat(availableValueUsd),
+      ),
+    };
+  });
+}
+
+function buildAccountJsonRows(
+  accounts: CoinbaseAccount[],
+  metadataByCurrency: Map<string, AccountDisplayMetadata>,
+  options: AccountsOptions,
+): AccountExportRow[] {
+  return accounts.map((account) => {
+    const metadata = getAccountMetadata(metadataByCurrency, account.currency);
+    const row = toAccountBalanceRow(account, metadataByCurrency, options.raw);
+    const totalSize = parseFloat(account.hold.value) + parseFloat(account.available_balance.value);
+    return {
+      currency: account.currency,
+      type: account.type,
+      hold: row.Hold,
+      available: row.Available,
+      price: options.value ? metadata.price : null,
+      holdValueUsd: options.value && metadata.price !== null
+        ? toIncrement(metadata.priceIncrement, parseFloat(account.hold.value) * parseFloat(metadata.price))
+        : null,
+      availableValueUsd: options.value && metadata.price !== null
+        ? toIncrement(metadata.priceIncrement, parseFloat(account.available_balance.value) * parseFloat(metadata.price))
+        : null,
+      totalValueUsd: options.value && metadata.price !== null
+        ? toIncrement(metadata.priceIncrement, totalSize * parseFloat(metadata.price))
+        : null,
+    };
+  });
 }
 
 async function getSupportedProduct(
@@ -167,22 +260,7 @@ export async function handleAccountsAction(
 ): Promise<void> {
   const allAccounts = await requestAccounts();
   const filteredAccounts = filterAccounts(allAccounts, options);
-
-  if (options.json) {
-    const metadataByCurrency = await buildMetadataByCurrency(filteredAccounts, false);
-    writeAccountsJson(
-      filteredAccounts.map((account) => {
-        const row = toAccountBalanceRow(account, metadataByCurrency, options.raw);
-        return {
-          currency: account.currency,
-          type: account.type,
-          hold: row.Hold,
-          available: row.Available,
-        };
-      }),
-      options.json,
-    );
-  }
+  const wantsJson = options.json || Boolean(options.jsonFile);
 
   let accounts = filteredAccounts;
 
@@ -193,6 +271,18 @@ export async function handleAccountsAction(
     }
     accounts = accounts.filter((acc) => acc.currency.toUpperCase() === currency);
     const { price, price_increment } = await getProductInfo(product);
+    if (wantsJson) {
+      const payload = buildAccountsJsonPayload(
+        buildProductJsonRows(accounts, price, price_increment),
+        options,
+        product,
+      );
+      if (options.jsonFile) {
+        writeAccountsJsonFile(payload, options.jsonFile);
+      }
+      printAccountsJson(payload);
+      return;
+    }
     console.table(
       accounts.map((acc) => {
         const hold = acc.hold.value;
@@ -215,6 +305,18 @@ export async function handleAccountsAction(
       return acc.available_balance.value !== "0" || acc.hold.value !== "0";
     });
     const metadataByCurrency = await buildMetadataByCurrency(accounts, options.value === true);
+    if (wantsJson) {
+      const payload = buildAccountsJsonPayload(
+        buildAccountJsonRows(accounts, metadataByCurrency, options),
+        options,
+        product,
+      );
+      if (options.jsonFile) {
+        writeAccountsJsonFile(payload, options.jsonFile);
+      }
+      printAccountsJson(payload);
+      return;
+    }
 
     console.table(
       accounts.map((acc) => {

src/apps/cb/commands/register/register-accounts.ts

@@ -15,7 +15,8 @@ export function registerAccountsCommands(program: Command) {
     .description("List account balances (non-zero only unless [product] is provided)")
     .option("--crypto", "Show only crypto accounts", false)
     .option("--cash", "Show only fiat (cash) accounts; ignored if --crypto is also set", false)
-    .option("--json [filepath]", "Write account balances JSON to a file (defaults to ./accounts.json)")
+    .option("--json", "Print machine-readable JSON output", false)
+    .option("--json-file <path>", "Write machine-readable JSON output to <path>")
     .option("--raw", "Show hold and available sizes without increment-based rounding", false)
     .option("--value", "Show estimated USD value using current product prices", false)
     .action(

src/apps/cb/commands/schemas/command-options.ts

@@ -5,7 +5,8 @@ export const AccountsOptionsSchema = z
   .object({
     crypto: z.boolean().optional(),
     cash: z.boolean().optional(),
-    json: z.union([z.boolean(), z.string()]).optional(),
+    json: z.boolean().optional(),
+    jsonFile: z.string().trim().min(1).optional(),
     raw: z.boolean().optional(),
     value: z.boolean().optional(),
   })

src/apps/hdb/README.md

@@ -75,12 +75,15 @@ Install binary in your shell:
 - `hdb coinbase balances list <asset>`
   - `asset` supports colon-separated values
   - `--json` prints structured troubleshooting output
+  - `--json-file <path>` writes the same structured payload to disk
   - `--current` live check requires `--remote`
 - `hdb coinbase balances snapshot`
   - `--json` prints structured troubleshooting output
+  - `--json-file <path>` writes the same structured payload to disk
   - `--current` live check requires `--remote`
 - `hdb coinbase balances trace <asset>`
   - `--json` prints structured troubleshooting output
+  - `--json-file <path>` writes the same structured payload to disk
 - `hdb coinbase balances rebuild`
 - `hdb coinbase lots analyze <asset>`
 - `hdb coinbase lots analyze-all`
@@ -120,6 +123,8 @@ Coinbase migration status and next slices are tracked in:
 ### CoinTracker
 
 - `hdb cointracker balances list [currency]`
+  - `--json` prints `{ rows, filters, meta }`
+  - `--json-file <path>` writes the same structured payload to disk
 - `hdb cointracker balances rebuild`
 - `hdb cointracker gains list [assets]`
   - export flags: `--csv`, `--f8949`, `--headers`, `--pages`