bkper 4.31.3 → 5.0.0

package/lib/docs/cli/data-management.md

@@ -188,7 +188,7 @@ Upload local files to a book and optionally route them with properties.
 # List the first page of files in a book
 bkper file list -b abc123
 
-# Fetch the next page using the cursor shown in table output or JSON
+# Fetch the next page using the cursor from the previous output
 bkper file list -b abc123 --limit 100 --cursor cursor_123
 
 # Upload a file to a book
@@ -258,9 +258,6 @@ bkper transaction list -b abc123 -q 'on:2025'
 # List transactions for a month (on:YYYY-MM)
 bkper transaction list -b abc123 -q 'on:2025-01'
 
-# List with custom properties included
-bkper transaction list -b abc123 -q 'account:Sales' -p
-
 # Fetch one page of transactions explicitly
 bkper transaction list -b abc123 -q 'on:2025' --limit 100
 
@@ -296,7 +293,6 @@ bkper transaction merge tx_123 tx_456 -b abc123
 -   `transaction list -b <bookId> -q <query>` - List transactions matching a query (auto-paginates through all results unless `--limit` or `--cursor` is provided)
     -   `--limit <number>` - Fetch one page with up to this many transactions
     -   `--cursor <cursor>` - Cursor for fetching the next page
-    -   `-p, --properties` - Include custom properties in the output
 -   `transaction create -b <bookId>` - Create a transaction
     -   `--date <date>` - Transaction date
     -   `--amount <amount>` - Transaction amount
@@ -336,11 +332,11 @@ Inspect book events and bot responses — useful for debugging automations and r
 # List recent events (one page, default limit 50)
 bkper event list -b abc123
 
-# List only events with error bot responses, as JSON (includes full botResponses)
-bkper event list -b abc123 --error --json
+# List only events with error bot responses (includes full botResponses)
+bkper event list -b abc123 --error
 
 # Filter by resource (transaction, account, or group id)
-bkper event list -b abc123 --resource tx_456 --json
+bkper event list -b abc123 --resource tx_456
 
 # Filter by event type and date range
 bkper event list -b abc123 --type TRANSACTION_POSTED --after 2026-01-01T00:00:00Z
@@ -349,13 +345,13 @@ bkper event list -b abc123 --type TRANSACTION_POSTED --after 2026-01-01T00:00:00
 bkper event list -b abc123 --limit 50 --cursor cursor_123
 
 # Replay one bot response after inspecting an error
-bkper event replay evt_789 -b abc123 --agent-id tax-bot --json
+bkper event replay evt_789 -b abc123 --agent-id tax-bot
 ```
 
 <details>
 <summary>Command reference</summary>
 
--   `event list -b <bookId>` - List one page of events in a book (includes bot responses in JSON)
+-   `event list -b <bookId>` - List one page of events in a book (includes bot responses)
     -   `--after <date>` - Start date inclusive (RFC3339)
     -   `--before <date>` - End date exclusive (RFC3339)
     -   `--resource <resourceId>` - Filter by resource ID (Transaction, Account, or Group). When set, `--error` and `--type` are ignored by the API
@@ -365,7 +361,7 @@ bkper event replay evt_789 -b abc123 --agent-id tax-bot --json
     -   `--cursor <cursor>` - Cursor for fetching the next page
 -   `event replay <eventId> -b <bookId> --agent-id <agentId>` - Replay one bot response for an event (returns the updated event with bot responses)
 
-JSON output includes the full event payload, including nested `botResponses` (`agentId`, `type`, `message`, `createdAt`), for LLM-assisted debugging.
+Output includes the full event payload, including nested `botResponses` (`agentId`, `type`, `message`, `createdAt`), for LLM-assisted debugging.
 
 </details>
 
@@ -474,53 +470,56 @@ bkper collection delete col_789
 
 ## Output Format
 
-All commands support three output formats via the `--format` global flag:
+All data commands output **JSON only**. Results go to stdout; hints (such as the next-page command), warnings, and notices go to stderr, so stdout is always parseable.
 
-| Format | Flag                       | Best for                                    |
-| ------ | -------------------------- | ------------------------------------------- |
-| Table  | `--format table` (default) | Human reading in the terminal               |
-| JSON   | `--format json`            | Programmatic access, cursors, single-item detail |
-| CSV    | `--format csv`             | LLM consumption, spreadsheets, list reports |
+| Output                                              | Shape                                                   |
+| --------------------------------------------------- | ------------------------------------------------------- |
+| Lists (`book list`, `transaction list`, batch writes, ...) | `{"items":[...]}`, plus `"cursor"` only when another page exists |
+| Single items (`get`, `create`, `update`, ...)       | One JSON object                                         |
+| Balances (`balance list`)                           | A 2D matrix: header row first, then one row per account or group |
 
 ```bash
-# Table output (default)
+# List output: one record per line inside the envelope
 bkper account list -b abc123
+# {"items":[
+# {"id":"acc-abc","name":"Cash","type":"ASSET",...},
+# {"id":"acc-def","name":"Revenue","type":"INCOMING",...}
+# ]}
+```
 
-# JSON output
-bkper account list -b abc123 --format json
-# { "items": [...] }
+**Layout:**
 
-# CSV output -- raw data, no truncation, RFC 4180
-bkper account list -b abc123 --format csv
-```
+-   Lists and balance matrices put one record or row per line, so `head`, `grep`, and `wc -l` work on records.
+-   Single items are pretty-printed on an interactive terminal and compact (one line) otherwise.
 
-**JSON list output details:**
+**Transactions** keep the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts) shape, with `creditAccount.name` and `debitAccount.name` added so the from/to flow is readable without a separate account lookup. Custom properties are always included. Inline agent logo images are omitted.
 
--   Resource list commands return an object with an `items` array: `{ "items": [...] }`.
--   Paginated list commands include `cursor` only when another page is available: `{ "items": [...], "cursor": "..." }`.
--   Use `jq '.items[]'` to iterate list output.
+**Balances** values are unformatted JSON numbers (never locale-formatted strings), dates are ISO `yyyy-MM-dd`, and account/group properties are included as extra columns. Transaction `amount` values are exact decimal strings.
 
-**CSV output details:**
+**Reshape with jq** instead of output flags:
 
--   **RFC 4180 compliant** -- proper quoting, CRLF line endings, no truncation
--   **All metadata included** -- IDs, properties, hidden properties, URLs, and timestamps are enabled
--   **Raw values** -- dates stay in ISO format, numbers are unformatted (no locale formatting)
--   **Single-item commands** (e.g. `account get`, `transaction create`) fall back to JSON since CSV adds no value for non-tabular data
+```bash
+# Iterate list items
+bkper transaction list -b abc123 -q 'on:2025-01' | jq '.items[]'
 
-**LLM-first output guidance (important):**
+# Pick columns
+bkper transaction list -b abc123 -q 'on:2025-01' | \
+  jq '.items[] | {date, amount, from: .creditAccount.name, to: .debitAccount.name, description}'
 
-When command output will be loaded into an LLM context (chat, prompt, memory, or agent reasoning), prefer:
+# Export to CSV
+bkper transaction list -b abc123 -q 'on:2025-01' | \
+  jq -r '.items[] | [.date, .amount, .creditAccount.name, .debitAccount.name, .description] | @csv'
 
--   **`--format csv` for list commands** (`balance list`, `transaction list`, `account list`, etc.).
--   **`--format json` for single-item commands** (`get`, `create`, `update`), cursor pagination, and CLI-to-CLI pipelines.
+# Balance matrix to CSV
+bkper balance list -b abc123 -q 'on:2025-12-31' | jq -r '.[] | @csv'
 
-CSV is significantly more token-efficient than JSON for tabular data, and for wide balance outputs it can reduce token usage by up to **95%**.
+# Read the next-page cursor
+bkper transaction list -b abc123 -q 'on:2025' --limit 100 | jq -r '.cursor // empty'
+```
 
-**Quick rule:**
+For accounting numbers, compute with a deterministic script or query rather than summing by eye. Balance values are JSON numbers, so extremely large values with many decimal places (beyond ~15 significant digits) can lose their last digits; use transaction `amount` strings when exact digits matter.
 
--   **LLM consumption of lists/reports** → CSV
--   **Programmatic processing / pipelines** → JSON
--   **Human terminal reading** → Table
+`--json` and `--format json` are accepted for compatibility and have no effect. Table and CSV output formats were removed; any other `--format` value fails with a jq hint.
 
 ---
 
@@ -564,43 +563,46 @@ echo '[{"name":"Cash","type":"ASSET"}]' | \
   bkper account create -b abc123 -p "region=LATAM"
 ```
 
-**Batch output:** write commands output created or updated resources as a flat JSON array:
+**Batch output:** write commands output created or updated resources in the same `{"items":[...]}` envelope as lists:
 
 ```bash
 bkper account create -b abc123 < accounts.json
-# Output: [{"id":"acc-abc","name":"Cash",...}, {"id":"acc-def","name":"Revenue",...}]
+# {"items":[
+# {"id":"acc-abc","name":"Cash",...},
+# {"id":"acc-def","name":"Revenue",...}
+# ]}
 ```
 
-List JSON output uses an `{ "items": [...] }` envelope, and stdin batch commands unwrap that envelope automatically for CLI-to-CLI pipes.
+Stdin accepts a single object, an array, or the `{"items":[...]}` envelope, so list and batch output can be piped directly into another command.
 
 **Piping between commands:**
 
-For resources that support stdin creation, JSON output can be piped directly into create or update commands:
+For resources that support stdin creation, output can be piped directly into create or update commands:
 
 ```bash
 # Copy all accounts from one book to another
-bkper account list -b $BOOK_A --format json | bkper account create -b $BOOK_B
+bkper account list -b $BOOK_A | bkper account create -b $BOOK_B
 
 # Copy transactions matching a query
-bkper transaction list -b $BOOK_A -q 'after:2025-01-01' --format json | \
+bkper transaction list -b $BOOK_A -q 'after:2025-01-01' | \
   bkper transaction create -b $BOOK_B
 
 # Clone accounts, then transactions
-bkper account list -b $SOURCE --format json | bkper account create -b $DEST
-bkper transaction list -b $SOURCE -q 'after:2025-01-01' --format json | \
+bkper account list -b $SOURCE | bkper account create -b $DEST
+bkper transaction list -b $SOURCE -q 'after:2025-01-01' | \
   bkper transaction create -b $DEST
 
 # Batch update: list transactions, modify, and pipe back to update
-bkper transaction list -b $BOOK -q 'after:2025-01-01' --format json | \
-  jq '[.[] | .description = "Updated: " + .description]' | \
+bkper transaction list -b $BOOK -q 'after:2025-01-01' | \
+  jq '[.items[] | .description = "Updated: " + .description]' | \
   bkper transaction update -b $BOOK
 
 # Batch update: add a property to all matching transactions
-bkper transaction list -b $BOOK -q 'account:Expenses' --format json | \
+bkper transaction list -b $BOOK -q 'account:Expenses' | \
   bkper transaction update -b $BOOK -p "reviewed=true"
 
 # Batch update checked transactions
-bkper transaction list -b $BOOK -q 'is:checked after:2025-01-01' --format json | \
+bkper transaction list -b $BOOK -q 'is:checked after:2025-01-01' | \
   bkper transaction update -b $BOOK --update-checked -p "migrated=true"
 ```
 

package/lib/docs/index.md

@@ -7,7 +7,7 @@ For Bkper data, accounting, reporting, tax, or financial-flow tasks, read `core/
 For Bkper app implementation, refactoring, or code review, always read `apps/quality.md` alongside the task-specific references. After implementation, review the changed code against the guidelines before considering the work complete.
 
 - `core/core-concepts.md` — canonical Bkper data model: resources, movements, balances, accounts, groups, books, transactions, properties, and the zero-sum invariant.
-- `cli/data-management.md` — CLI reference for managing financial data and files: books, accounts, groups, files, transactions, per-account balance queries, query operators (on:, after:, before:, account:, group:), output formats (table/json/csv), human-review Bkper UI links, batch operations via stdin/piping, collections.
+- `cli/data-management.md` — CLI reference for managing financial data and files: books, accounts, groups, files, transactions, per-account balance queries, query operators (on:, after:, before:, account:, group:), JSON output shapes and jq reshaping, human-review Bkper UI links, batch operations via stdin/piping, collections.
 - `cli/app-management.md` — CLI reference for building and deploying Bkper apps: init/git clone/credential helpers, dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
 - `apps/overview.md` — Platform evaluation and capability overview: use when comparing managed Bkper hosting with self-managed infrastructure or clarifying platform responsibilities; use the task-specific app references for implementation.
 - `apps/ai.md` — Bkper AI in Platform apps: choose Jev typed evaluations or Open Responses language models, authenticate through app `/api/*` routes, discover model capabilities, validate output, and keep Book writes under deterministic application control.

package/lib/docs-compliance/live-readme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"live-readme.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/live-readme.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AA4DD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CActE;AAED,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,GACxB,mBAAmB,CAiCrB"}
+{"version":3,"file":"live-readme.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/live-readme.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AA4DD,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CActE;AAED,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,GACxB,mBAAmB,CA6BrB"}

package/lib/docs-compliance/live-readme.js

@@ -81,9 +81,6 @@ export function materializeCommand(command, config) {
             skipReason: `unresolved placeholders in command: ${materialized}`,
         };
     }
-    if (!materialized.includes('--format ')) {
-        materialized = `${materialized} --format csv`;
-    }
     return { command: materialized };
 }
 //# sourceMappingURL=live-readme.js.map

package/lib/docs-compliance/live-readme.js.map

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

package/lib/docs-compliance/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/rules.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B;AA4BD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA+F1E"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/docs-compliance/rules.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B;AA4BD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CA0G1E"}

package/lib/docs-compliance/rules.js

@@ -67,6 +67,15 @@ export function evaluateReadmeCompliance(content) {
             message: 'README should not document stdin writable fields for `bkper.Group`.',
         });
     }
+    const legacyOutputFormatPattern = /--format(?:\s+|=)(?:table|csv)\b/g;
+    let legacyOutputFormatMatch;
+    while ((legacyOutputFormatMatch = legacyOutputFormatPattern.exec(content)) !== null) {
+        errors.push({
+            code: 'legacy-output-format-documented',
+            message: 'Found `--format table|csv`. CLI output is JSON only; reshape with jq instead.',
+            line: getLineNumber(content, legacyOutputFormatMatch.index),
+        });
+    }
     const internalReleaseDetailPattern = /release:(patch|minor|major)|Trusted Publisher|GitHub Actions|CI\/CD|publishing policy|publish(?:ing)?\s+is\s+handled|maintainer-only procedures/i;
     const internalReleaseDetailMatch = internalReleaseDetailPattern.exec(content);
     if (internalReleaseDetailMatch) {

package/lib/docs-compliance/rules.js.map

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

package/lib/render/index.d.ts

@@ -1,5 +1,3 @@
-export { formatTable, formatItem } from './table-formatter.js';
-export { formatCsv } from './csv-formatter.js';
-export { renderTable, renderItem, renderListResult } from './output.js';
-export type { OutputFormat, ListResult } from './output.js';
+export { formatItem, formatList, formatMatrix, isInteractiveOutput, renderItem, renderList, renderMatrix, renderNotice, } from './output.js';
+export type { ListResult } from './output.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/render/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EACV,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,YAAY,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/lib/render/index.js

@@ -1,4 +1,2 @@
-export { formatTable, formatItem } from './table-formatter.js';
-export { formatCsv } from './csv-formatter.js';
-export { renderTable, renderItem, renderListResult } from './output.js';
+export { formatItem, formatList, formatMatrix, isInteractiveOutput, renderItem, renderList, renderMatrix, renderNotice, } from './output.js';
 //# sourceMappingURL=index.js.map

package/lib/render/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,UAAU,EACV,UAAU,EACV,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,UAAU,EACV,YAAY,EACZ,YAAY,GACf,MAAM,aAAa,CAAC"}

package/lib/render/output.d.ts

@@ -1,37 +1,57 @@
 /**
- * Output format type for CLI rendering.
+ * JSON-only output rendering.
+ *
+ * Contract:
+ * - stdout carries only the JSON result, so it is always parseable (e.g. by jq).
+ * - Lists use a stable `{"items":[...]}` envelope, adding `"cursor"` only when a
+ *   next page exists. Each record is compact on its own line.
+ * - Matrices (balance reports) are bare 2D arrays with one row per line.
+ * - Single items are pretty-printed only on an interactive terminal.
+ * - Hints, notices, and warnings go to stderr.
  */
-export type OutputFormat = 'table' | 'json' | 'csv';
 /**
- * Structured result from list commands, allowing cli.ts to render
- * without knowing how the data was built.
+ * Structured list result returned by list commands.
  */
-export type ListResult = {
-    kind: 'json';
+export interface ListResult {
     items: unknown[];
+    /** Cursor for the next page, present only when more results exist. */
     cursor?: string;
-} | {
-    kind: 'matrix';
-    matrix: unknown[][];
-    footer?: string;
-};
+    /** Human/agent guidance (e.g. next-page command), written to stderr. */
+    hint?: string;
+}
 /**
- * Renders a ListResult to stdout based on the active output format.
+ * Formats list items in the `{"items":[...]}` envelope, one record per line.
  */
-export declare function renderListResult(result: ListResult, format: OutputFormat): void;
+export declare function formatList(items: unknown[], cursor?: string): string;
 /**
- * Renders a 2D matrix as a formatted table, JSON, or CSV.
- *
- * @param matrix - 2D array where row 0 is headers and rows 1+ are data
- * @param format - Output format: 'table' (default), 'json', or 'csv'
+ * Formats a 2D matrix as JSON, one row per line.
+ */
+export declare function formatMatrix(matrix: unknown[][]): string;
+/**
+ * Formats a single item as pretty (2-space) or compact JSON.
+ */
+export declare function formatItem(item: object, pretty: boolean): string;
+/**
+ * Whether stdout is an interactive terminal (a human is reading).
  */
-export declare function renderTable(matrix: unknown[][], format: OutputFormat): void;
+export declare function isInteractiveOutput(): boolean;
 /**
- * Renders a single item as key-value pairs, JSON, or JSON (for CSV, since
- * single items are not tabular, CSV falls back to JSON).
+ * Renders a list result: JSON to stdout, hint to stderr.
+ */
+export declare function renderList(result: ListResult): void;
+/**
+ * Renders a 2D matrix as JSON to stdout.
+ */
+export declare function renderMatrix(matrix: unknown[][]): void;
+/**
+ * Renders a single item as JSON to stdout.
  *
  * @param item - Record to render
- * @param format - Output format: 'table' (default), 'json', or 'csv'
+ * @param pretty - Pretty-print; defaults to true only on an interactive terminal
+ */
+export declare function renderItem(item: object, pretty?: boolean): void;
+/**
+ * Renders a human-readable notice (e.g. success without a result) to stderr.
  */
-export declare function renderItem(item: object, format: OutputFormat): void;
+export declare function renderNotice(message: string): void;
 //# sourceMappingURL=output.d.ts.map

package/lib/render/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/render/output.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAU/E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAe3E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,IAAI,CAQnE"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/render/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AASD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,CAExD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAE7C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAKnD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,IAAI,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,UAAwB,GAAG,IAAI,CAE7E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD"}

package/lib/render/output.js

@@ -1,54 +1,74 @@
-import { formatTable, formatItem } from './table-formatter.js';
-import { formatCsv } from './csv-formatter.js';
 /**
- * Renders a ListResult to stdout based on the active output format.
+ * JSON-only output rendering.
+ *
+ * Contract:
+ * - stdout carries only the JSON result, so it is always parseable (e.g. by jq).
+ * - Lists use a stable `{"items":[...]}` envelope, adding `"cursor"` only when a
+ *   next page exists. Each record is compact on its own line.
+ * - Matrices (balance reports) are bare 2D arrays with one row per line.
+ * - Single items are pretty-printed only on an interactive terminal.
+ * - Hints, notices, and warnings go to stderr.
  */
-export function renderListResult(result, format) {
-    if (result.kind === 'json') {
-        const payload = result.cursor ? { items: result.items, cursor: result.cursor } : result.items;
-        console.log(JSON.stringify(payload, null, 2));
-        return;
-    }
-    renderTable(result.matrix, format);
-    if (result.footer && format === 'table') {
-        console.log(result.footer);
-    }
+/**
+ * Serializes lines as a JSON array body with one entry per line.
+ */
+function formatLines(lines) {
+    return lines.length > 0 ? `[\n${lines.join(',\n')}\n]` : '[]';
 }
 /**
- * Renders a 2D matrix as a formatted table, JSON, or CSV.
- *
- * @param matrix - 2D array where row 0 is headers and rows 1+ are data
- * @param format - Output format: 'table' (default), 'json', or 'csv'
- */
-export function renderTable(matrix, format) {
-    switch (format) {
-        case 'json':
-            console.log(JSON.stringify(matrix, null, 2));
-            return;
-        case 'csv': {
-            const csv = formatCsv(matrix);
-            console.log(csv || 'No results found.');
-            return;
-        }
-        default: {
-            const formatted = formatTable(matrix);
-            console.log(formatted || 'No results found.');
-        }
+ * Formats list items in the `{"items":[...]}` envelope, one record per line.
+ */
+export function formatList(items, cursor) {
+    const body = formatLines(items.map(item => JSON.stringify(item)));
+    const cursorPart = cursor !== undefined ? `,"cursor":${JSON.stringify(cursor)}` : '';
+    return `{"items":${body}${cursorPart}}`;
+}
+/**
+ * Formats a 2D matrix as JSON, one row per line.
+ */
+export function formatMatrix(matrix) {
+    return formatLines(matrix.map(row => JSON.stringify(row)));
+}
+/**
+ * Formats a single item as pretty (2-space) or compact JSON.
+ */
+export function formatItem(item, pretty) {
+    return pretty ? JSON.stringify(item, null, 2) : JSON.stringify(item);
+}
+/**
+ * Whether stdout is an interactive terminal (a human is reading).
+ */
+export function isInteractiveOutput() {
+    return process.stdout.isTTY === true;
+}
+/**
+ * Renders a list result: JSON to stdout, hint to stderr.
+ */
+export function renderList(result) {
+    console.log(formatList(result.items, result.cursor));
+    if (result.hint) {
+        console.error(result.hint);
     }
 }
 /**
- * Renders a single item as key-value pairs, JSON, or JSON (for CSV, since
- * single items are not tabular, CSV falls back to JSON).
+ * Renders a 2D matrix as JSON to stdout.
+ */
+export function renderMatrix(matrix) {
+    console.log(formatMatrix(matrix));
+}
+/**
+ * Renders a single item as JSON to stdout.
  *
  * @param item - Record to render
- * @param format - Output format: 'table' (default), 'json', or 'csv'
+ * @param pretty - Pretty-print; defaults to true only on an interactive terminal
  */
-export function renderItem(item, format) {
-    if (format === 'json' || format === 'csv') {
-        console.log(JSON.stringify(item, null, 2));
-        return;
-    }
-    const formatted = formatItem(item);
-    console.log(formatted || 'No results found.');
+export function renderItem(item, pretty = isInteractiveOutput()) {
+    console.log(formatItem(item, pretty));
+}
+/**
+ * Renders a human-readable notice (e.g. success without a result) to stderr.
+ */
+export function renderNotice(message) {
+    console.error(message);
 }
 //# sourceMappingURL=output.js.map

package/lib/render/output.js.map

@@ -1 +1 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/render/output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAe/C;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAkB,EAAE,MAAoB;IACrE,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC9F,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9C,OAAO;IACX,CAAC;IACD,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,MAAmB,EAAE,MAAoB;IACjE,QAAQ,MAAM,EAAE,CAAC;QACb,KAAK,MAAM;YACP,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAC7C,OAAO;QACX,KAAK,KAAK,CAAC,CAAC,CAAC;YACT,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAC;YACxC,OAAO;QACX,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACN,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;YACtC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAC;QAClD,CAAC;IACL,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAoB;IACzD,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3C,OAAO;IACX,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,CAAC,IAA+B,CAAC,CAAC;IAC9D,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,mBAAmB,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/render/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH;;GAEG;AACH,SAAS,WAAW,CAAC,KAAe;IAChC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAgB,EAAE,MAAe;IACxD,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClE,MAAM,UAAU,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,OAAO,YAAY,IAAI,GAAG,UAAU,GAAG,CAAC;AAC5C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC5C,OAAO,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAe;IACpD,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AACzE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IAC/B,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,MAAkB;IACzC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAmB;IAC5C,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,MAAM,GAAG,mBAAmB,EAAE;IACnE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe;IACxC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC3B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.31.3",
+    "version": "5.0.0",
     "description": "Official Bkper CLI for accounting data, automation, apps, and AI agents",
     "bin": {
         "bkper": "./lib/cli.js"

package/lib/render/csv-formatter.d.ts

@@ -1,15 +0,0 @@
-/**
- * Formats a 2D matrix into an RFC 4180 compliant CSV string.
- *
- * - Row 0 is treated as headers, rows 1+ as data (all rendered identically)
- * - Uses CRLF line endings per RFC 4180
- * - Fields containing commas, double quotes, or newlines are quoted
- * - Double quotes are escaped by doubling them ("")
- * - null/undefined cells are rendered as empty strings
- * - No truncation is applied to any field
- *
- * @param matrix - 2D array where row 0 is headers and rows 1+ are data
- * @returns RFC 4180 CSV string
- */
-export declare function formatCsv(matrix: unknown[][]): string;
-//# sourceMappingURL=csv-formatter.d.ts.map

package/lib/render/csv-formatter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"csv-formatter.d.ts","sourceRoot":"","sources":["../../src/render/csv-formatter.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,MAAM,CAMrD"}

package/lib/render/csv-formatter.js

@@ -1,37 +0,0 @@
-/**
- * Formats a field value according to RFC 4180 rules.
- *
- * - null/undefined become empty string
- * - Fields containing commas, double quotes, or newlines are wrapped in double quotes
- * - Double quotes within a field are escaped by doubling them ("")
- */
-function formatField(value) {
-    if (value == null) {
-        return '';
-    }
-    const str = String(value);
-    if (str.includes('"') || str.includes(',') || str.includes('\n') || str.includes('\r')) {
-        return '"' + str.replace(/"/g, '""') + '"';
-    }
-    return str;
-}
-/**
- * Formats a 2D matrix into an RFC 4180 compliant CSV string.
- *
- * - Row 0 is treated as headers, rows 1+ as data (all rendered identically)
- * - Uses CRLF line endings per RFC 4180
- * - Fields containing commas, double quotes, or newlines are quoted
- * - Double quotes are escaped by doubling them ("")
- * - null/undefined cells are rendered as empty strings
- * - No truncation is applied to any field
- *
- * @param matrix - 2D array where row 0 is headers and rows 1+ are data
- * @returns RFC 4180 CSV string
- */
-export function formatCsv(matrix) {
-    if (!matrix || matrix.length === 0) {
-        return '';
-    }
-    return matrix.map(row => row.map(formatField).join(',')).join('\r\n');
-}
-//# sourceMappingURL=csv-formatter.js.map