CLI QA bug hunt

Read the shared QA contract first, then cli/AGENTS.md and the relevant sections of cli/README.md and cli/docs/USAGE.md. Exercise the real bea executable through subprocesses; unit tests and source inspection support a finding but do not replace a CLI journey.

Arguments: optional executable path, journey names, ledger path, server URL, wN, SHIP=1, DRY_RUN=1. Default to this checkout's uv run bea, local synthetic ledgers, and report mode. A server argument selects a hosted target; it does not turn every local journey into a cloud test. DRY_RUN=1 still allows disposable local fixture writes needed to reproduce bugs.

Prepare an isolated command environment

• Work inside cli/; use uv sync --all-groups if existing dependencies are missing. Record HEAD, dirty files, OS, Python version, executable path and bea --version. For a supplied installed binary, keep its results separate from checkout reproduction: an older release is not evidence HEAD is broken.
• Discover commands and flags from bea --help and subcommand help before scripting them. Global options precede the command, for example uv run bea --json --file /absolute/path/main.bean list transaction.
• Create a unique run directory under the gitignored repo-root .tmp/qa-<date>/ and run every command with that as the cwd, so no fixture, export, or import artifact lands in cli/ or the repo root. Set absolute BEA_CONFIG_DIR and XDG_CACHE_HOME paths inside it in the child process environment and set BEA_NO_UPDATE_NOTIFIER=1. Remove inherited BEA_FILE and BEA_TOKEN from local-test children. Do not repurpose HOME or alter the user's shell, credential store, importer memory, or global CLI installation.
• Use explicit absolute --file paths except when testing discovery. Build small synthetic fixtures with fixed dates, known balances and separate includes; retain a pristine copy for resets. Local disposable writes are part of this QA request. Treat a supplied real ledger as read-only and reproduce mutations in synthetic data. Plugins and importer configs execute Python; inspect them before running, and prefer controlled local fixtures.
• Capture argument arrays, cwd, non-secret environment overrides, stdin mode, stdout, stderr, exit code, duration, and before/after file contents or hashes. Use bounded subprocess timeouts, closing stdin for unattended cases. Use a PTY for actual interactive journeys; lack of a PTY is a coverage limit. Do not pipe through a command that hides bea's exit status.

Sweep whole journeys

Use selected journey names to narrow this table; otherwise survey the available commands and deepen failures. Report skipped groups and why.

Journey	Observable promise
discovery/init	Help, version, target precedence (--file, BEA_FILE, cwd), paths with spaces/Unicode, missing files, and split-ledger includes work as documented. Init succeeds in a fresh directory; rerunning against an existing target preserves its contents.
directives	Add then list each relevant directive; check the whole ledger and query the result in a fresh process. Cover balanced/inferred postings, metadata, escaping, date boundaries, --into, and invalid input. Rejected atomic writes leave files unchanged.
batch/import	Preview leaves the ledger unchanged; apply persists the expected rows. Repeat import checks deduplication. Cover duplicate policy, malformed rows, and documented partial acceptance. Inspect the result and file diff before retrying any failed write. Use an inspected importer and synthetic bank export.
check/format	Valid and deliberately invalid ledgers produce documented diagnostics and exit codes. Formatting preserves meaning and is idempotent; --check and --dry-run do not write. Recursive formatting's partial failures identify affected files.
list/query	Filters compose; limits, ordering and truncation agree with fixture rows. BQL results, empty results, malformed queries, decimal/date serialization and supported exports are correct. Exercise the interactive query shell only with a PTY.
reports	Overview, income statement, balance sheet and trial balance honor periods, intervals and conversion. Compare against fixed-date fixture expectations and independent BQL/Beancount inventories; preserve commodity units, cost/price distinctions and documented sign conventions.
automation	Human and JSON output convey the same supported result. Parse JSON and check stdout/stderr separation, envelope, target and exit category. Compare terminal, redirected stdin, --no-input, and CI behavior; unattended commands must not hang waiting for prompts.
cloud	On the selected server and authorized QA account, exercise status, listing, inspection and applicable auth recovery. Create/clone/delete only scoped disposable resources when authorized, inspect partial or uncertain outcomes before retrying, and verify persistence in another process.
ask/upgrade	Check help and missing-dependency/auth diagnostics locally. Live Ask sends ledger context and may use quota; use synthetic data within existing authorization. upgrade --check uses the network; actual upgrade changes the installation and requires that scope. Never upgrade the user's CLI as a routine QA step.

Use cli/docs/USAGE.md's current JSON exceptions and exit-code table as the contract. For example, ask rejects JSON, login requires interaction, and successful logout/clone need not emit JSON. A nonzero exit can accompany partial batch writes, recursive formatting, or successful remote creation followed by clone failure. Do not classify these documented behaviors as bugs.

Hosted journeys and credentials

Local journeys need no login. Inspect BEA_API_URL and BEA_DASHBOARD_URL independently; the browser sign-in origin is not the REST origin. Use the QA token from the repo-root ./.env via the child environment, or the CLI's real bea cloud login device flow with the isolated configuration directory. Do not assume cli/.env exists or load another package's credentials. Browser cookies from the shared dashboard helper are not CLI tokens. If browser login needs QA_EMAIL/QA_PASSWORD, use the shared credential rules and a verified field, then complete the device flow and check cloud status.

Keep tokens and device authorization codes out of captured transcripts. Never log an entire environment, credential file, authentication response, or raw debug transport. Without credentials, continue local and signed-out cases; mark authenticated cloud and live Ask unverified. Mock HTTP failures may prove local error handling but must be labeled simulations, not server defects.

Reproduce, research, and hand off

Repeat a candidate from pristine fixtures in a fresh process using the same executable and child environment. Check a nearby working control. Distinguish documented usage errors, invalid fixtures, missing optional extras and upstream Beancount semantics from CLI bugs. A hang needs a bounded capture and a check for an intended prompt; a data-loss claim needs before/after evidence.

Trace command registration in src/cli/main.py, behavior in src/cli/commands/, output/errors in src/cli/output.py and errors.py, and the relevant directive, report, auth or config helpers. Read nested guidance before following vendored src/fava/. Hosted commands use the generated REST client and cloud adapters: generated files are evidence, not manual fix targets. Trace server causes under backend package guidance and retain eligible REST/GraphQL/MCP parity in a proposed server fix.

Apply shared root-cause, caller search, board/history dedupe and optional pm/ship steps. In the finding record, replace route/device evidence with executable/version, OS, cwd, exact command and fixture setup, stdin/TTY mode, exit code, separate output streams and file diff. State expected behavior and its documented or independently calculated basis. Include a minimal synthetic reproducer in public filing text so ignored evidence files are not required.

Finish with findings by severity, coverage/skips, dedupe/filing status, and cleanup. Retain sanitized reproducible evidence; remove disposable credentials and stop only processes started by this run. Report remaining test resources. Do not implement fixes unless requested; if requested, add meaningful regression coverage and run make check-all inside cli/ before handoff.