CLI Scripting & Piping

The Bkper CLI is designed for scripting. Every command supports multiple output formats, and write commands accept piped JSON input — making it easy to build data pipelines, batch operations, and automated workflows.

Output formats

All commands support three output formats via the --format global flag:

Format	Flag	Best for
Table	--format table (default)	Human reading in the terminal
JSON	--format json	Programmatic access, single-item detail
CSV	--format csv	Spreadsheets, AI agents, data pipelines

# Table output (default)
bkper account list -b abc123

# JSON output
bkper account list -b abc123 --format json

# CSV output -- raw data, no truncation, RFC 4180
bkper account list -b abc123 --format csv

CSV output details:

• RFC 4180 compliant — proper quoting, CRLF line endings, no truncation
• All metadata included — IDs, properties, hidden properties, URLs, and timestamps
• Raw values — dates in ISO format, numbers unformatted

AI agent guidance

When using the CLI from an AI agent or automated script:

• Use --format csv for list commands — CSV is 3-5x more token-efficient than JSON for tabular data
• Use --format json for single-item commands (get, create, update)
• Pipe data in via stdin for batch operations

Batch operations

Write commands (account create, group create, transaction create, transaction update) accept JSON piped via stdin. The input format follows the Bkper API Types — a single JSON object or an array of objects.

Creating in batch

# Create transactions from JSON
echo '[{
  "date": "2025-01-15",
  "amount": "100.50",
  "creditAccount": {"name": "Bank Account"},
  "debitAccount": {"name": "Office Supplies"},
  "description": "Printer paper",
  "properties": {"invoice": "INV-001"}
}]' | bkper transaction create -b abc123

# Create accounts
echo '[{"name":"Cash","type":"ASSET"},{"name":"Revenue","type":"INCOMING"}]' | \
  bkper account create -b abc123

# Create groups
echo '[{"name":"Fixed Costs","hidden":true}]' | \
  bkper group create -b abc123

# Pipe from any script that outputs JSON
python export_bank.py | bkper transaction create -b abc123

Batch results are output as a flat JSON array:

bkper account create -b abc123 < accounts.json
# [{"id":"acc-abc","name":"Cash",...}, {"id":"acc-def","name":"Revenue",...}]

Adding properties via CLI flag

The --property flag can add or override properties from the stdin payload:

echo '[{"name":"Cash","type":"ASSET"}]' | \
  bkper account create -b abc123 -p "region=LATAM"

Piping between commands

All JSON output is designed to feed directly into other commands. This is the most powerful pattern — combining commands into pipelines:

Copy data between books

# Copy all accounts from one book to another
bkper account list -b $BOOK_A --format json | bkper account create -b $BOOK_B

# Copy all groups
bkper group list -b $BOOK_A --format json | bkper group create -b $BOOK_B

# Copy transactions matching a query
bkper transaction list -b $BOOK_A -q "after:2025-01-01" --format json | \
  bkper transaction create -b $BOOK_B

Clone a full chart of accounts

# Groups first, then accounts, then transactions
bkper group list -b $SOURCE --format json | bkper group create -b $DEST
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 transaction create -b $DEST

Batch updates with jq

Use jq to transform data between commands:

# List transactions, modify descriptions, pipe back to update
bkper transaction list -b $BOOK -q "after:2025-01-01" --format json | \
  jq '[.[] | .description = "Updated: " + .description]' | \
  bkper transaction update -b $BOOK

# Add a property to all matching transactions
bkper transaction list -b $BOOK -q "account:Expenses" --format json | \
  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 update -b $BOOK --update-checked -p "migrated=true"

Shell script examples

Daily export

#!/bin/bash
# Export yesterday's transactions to CSV
DATE=$(date -d "yesterday" +%Y-%m-%d)
bkper transaction list -b $BOOK_ID \
  -q "after:$DATE before:$DATE" \
  --format csv > "export-$DATE.csv"

Bulk categorization

#!/bin/bash
# Add a property to all uncategorized transactions
bkper transaction list -b $BOOK_ID \
  -q "account:Uncategorized" \
  --format json | \
  bkper transaction update -b $BOOK_ID -p "needs_review=true"

Combining with other tools

The CLI works with standard Unix tools:

# Count transactions matching a query
bkper transaction list -b $BOOK_ID -q "after:2025-01-01" --format csv | wc -l

# Extract specific fields with jq
bkper account list -b $BOOK_ID --format json | \
  jq '[.[] | {name, balance}]'

# Sort by amount
bkper transaction list -b $BOOK_ID --format json | \
  jq 'sort_by(.amount | tonumber) | reverse'

Full CLI reference

For the complete command reference including all options, see the bkper-cli app page or run bkper --help.