ChooseFIRE CLI

Command-line tools for ChooseFIRE data operations.

This CLI is intentionally thin: it calls approved ChooseFIRE backend endpoints and prints stable JSON for humans, scripts, and AI agents. It does not read or upload the rich local FIRE workspace.

Setup

Install the public package globally, then run it with the short choosefire command:

npm install --global @yigemo/choosefire
choosefire --help

For local development:

pnpm install
pnpm build

Log in through Accounts:

choosefire auth login

The CLI opens your browser, completes Accounts login, receives the callback on 127.0.0.1:8787, and stores audience-separated legacy and workspace credentials in:

~/.choosefire/config.json

For local backend development, only set the API base URL:

export CHOOSEFIRE_API_BASE_URL=http://localhost:3000

Account workspace transport and account authority remain unavailable. Keep the flag off unless the 5A4 evidence gate and enablement owner explicitly approve a controlled synthetic-account drill; real accounts and real financial data are not authorized:

export CHOOSEFIRE_ACCOUNT_WORKSPACE_ENABLED=true
export CHOOSEFIRE_OIDC_CLIENT_ID=choosefire-cli
choosefire auth login --json

Commands

choosefire auth status --json
choosefire auth login --json
choosefire auth logout --json
choosefire workspace initialize --idempotency-key <key> --json
choosefire workspace snapshot --json
choosefire workspace summary --json
choosefire workspace activity --limit 50 [--cursor <cursor>] --json
choosefire workspace fact-record --expected-version <n> --idempotency-key <key> --field household.total_assets --amount 100.5 --currency CNY [--status confirmed|estimated] [--as-of <iso>] --json
choosefire household summary --json
choosefire wealth overview --json
choosefire wealth account-show --account-id <uuid> --json
choosefire wealth holding-create --command-id <uuid> --holding-id <uuid> --account-id <uuid> --name "Global Equity ETF" --currency CNY --expected-workspace-version <n> --idempotency-key <key> [--instrument-ref ETF-EXAMPLE-001] [--quantity 12.5 --quantity-as-of <iso>] --json
choosefire wealth holding-update --command-id <uuid> --holding-id <uuid> --name "Global Equity ETF" --currency CNY --expected-object-revision <n> --expected-workspace-version <n> --idempotency-key <key> [--quantity 13.5 --quantity-as-of <iso>] --json
choosefire wealth holding-archive --command-id <uuid> --holding-id <uuid> --reason "Position closed" --expected-object-revision <n> --expected-workspace-version <n> --idempotency-key <key> --json
choosefire transaction cash-flow --cash-flow-id <uuid> --account-id <uuid> --direction in --amount 2500 --currency CNY --occurred-at <iso> --expected-workspace-version <n> --idempotency-key <key> --json
choosefire transaction create --transaction-id <uuid> --account-id <uuid> --holding-id <uuid> --type buy --amount 1000 --currency CNY --quantity 10 --price 100 --trade-at <iso> --expected-workspace-version <n> --idempotency-key <key> --json
choosefire transaction update --transaction-id <uuid> --account-id <uuid> --holding-id <uuid> --type buy --amount 1100 --currency CNY --quantity 10 --price 110 --trade-at <iso> --expected-object-revision <n> --expected-workspace-version <n> --idempotency-key <key> --json
choosefire transaction archive --transaction-id <uuid> --reason "Duplicate import" --expected-object-revision <n> --expected-workspace-version <n> --idempotency-key <key> --json
choosefire transaction timeline --account-id <uuid> [--holding-id <uuid>] --json
choosefire update show --json
choosefire update extract --currency CNY --text "本月工资 3 万，支出 1.2 万，证券账户现在 45 万" --json
choosefire update preview --file update-draft.json --version <n> --json
choosefire update confirm --candidate <uuid> --version <n> --json
choosefire plan list --json
choosefire plan get <plan-id> --json
choosefire plan update-inputs <plan-id> --annual-return 0.035 --annual-inflation 0.04 --expected-updated-at <iso> --dry-run --json
choosefire plan duplicate <plan-id> --name "Conservative" --set annualReturn=0.035 --expected-updated-at <iso> --dry-run --json
choosefire plan set-default <plan-id> --expected-updated-at <iso> --dry-run --json
choosefire plan archive <plan-id> --expected-updated-at <iso> --reason "cleanup" --dry-run --json
choosefire asset upsert --plan <plan-id> --account-id asset-bank --amount 300000 --expected-return 0.02 --expected-updated-at <iso> --dry-run --json
choosefire asset remove --plan <plan-id> --account-id asset-bank --reason "duplicate account" --expected-updated-at <iso> --dry-run --json
choosefire visual dataset --plan <plan-id> --kind overview --json

The workspace, household, wealth, transaction, and update operations use the workspace bearer only, validate every request and response against the checked-in contract, never retry mutations, and never fall back to the legacy token or local files. Workspace and family-wealth v2 are enabled by default now that the production capability is public; set CHOOSEFIRE_ACCOUNT_WORKSPACE_ENABLED=false or CHOOSEFIRE_FAMILY_WEALTH_V2_ENABLED=false for an explicit rollback/compatibility run. update extract infers a baseline for a new workspace and otherwise starts after the latest confirmed period, so the short command normally needs only currency and narrative. Extraction returns an editable draft; update preview freezes it as a pending candidate, and only update confirm writes valuations and the cash-flow summary. Holding and investment transaction commands are available only for detailed accounts. Buy, sell, subscribe, and redeem require a holding, quantity, and price; deposits and withdrawals remain external cash flows. When a mutation outcome is unknown, first read the latest projection and then explicitly retry the exact serialized body with the original command ID and idempotency key to recover the receipt-first outcome. Never generate a new ID or key for that recovery attempt. The JSON error includes this exact recovery material and action.

Existing legacy plan write commands still default to dry-run unless --apply is passed. For CLI and MCP sources, --expected-updated-at should be provided to avoid overwriting newer data.

Development

pnpm dev -- plan list --json
pnpm typecheck
pnpm build
pnpm test
pnpm contract:choosefire-workspace:check

The portable CI suite excludes only the dedicated Batch 5A4 execution-closure evidence test, which is pinned to its approved macOS/arm64/Xcode toolchain:

pnpm ci
pnpm test:batch5a4:closure

Release

Releases are published from GitHub Actions through npm Trusted Publishing. From an up-to-date, clean main branch, bump the version and push its release commit and annotated tag with:

pnpm release patch

The vX.Y.Z tag must match package.json. GitHub Actions reruns the portable CI suite before publishing @yigemo/choosefire to npm.