# Common CLI Workflows

Real-world multi-command patterns for accounting automation.

---

## 1. Invoice Lifecycle: Create, Finalize, Pay, Verify

Create a sales invoice, approve it, record payment, and confirm the balance.

```bash
# Create invoice as draft (fuzzy-resolves contact and account)
clio invoices create \
  --contact "Acme Corp" \
  --date 2026-03-15 \
  --due 2026-04-15 \
  --ref "INV-2026-042" \
  --lines '[{"name":"Consulting Q1","quantity":1,"unitPrice":5000,"accountResourceId":"Revenue"}]' \
  --json

# Capture the resourceId from output
INVOICE_ID=$(clio invoices search --reference INV-2026-042 --json | jq -r '.data[0].resourceId')

# Finalize (approve) the invoice
clio invoices draft finalize "$INVOICE_ID"

# Record payment against the invoice
clio invoices pay "$INVOICE_ID" \
  --amount 5000 \
  --transaction-amount 5000 \
  --account "Bank - SGD" \
  --method BANK_TRANSFER \
  --ref "PAY-042" \
  --date 2026-03-20

# Verify: invoice should now show status PAID
clio invoices get "$INVOICE_ID" --json | jq '{status, totalAmount, amountPaid}'
```

## 2. Bank Statement Import and Auto-Reconciliation

Import a bank statement, trigger auto-reconciliation, and review unmatched records.

```bash
# List bank accounts to find the right one
clio bank accounts --json | jq '.data[] | {resourceId, name, currencyCode}'

BANK_ID="<bank-account-resourceId>"

# Import statement file (CSV, OFX, XLS, or XLSX)
clio bank import "$BANK_ID" ./march-2026-statement.csv

# Reconciliation suggestions (READ-ONLY, per-entry; --type and --entries are required)
ENTRY_IDS=$(clio bank records "$BANK_ID" --status UNRECONCILED --limit 20 --json | jq -r '[.data[].resourceId] | join(",")')
clio bank auto-recon --account "$BANK_ID" --type MAGIC_MATCH --entries "$ENTRY_IDS"

# Review unreconciled records
clio bank records "$BANK_ID" --status UNRECONCILED --from 2026-03-01 --to 2026-03-31 --json

# Check for possible duplicates
clio bank records "$BANK_ID" --status POSSIBLE_DUPLICATE --json
```

## 3. Month-End Close Workflow

Follow the month-end playbook in the jaz-jobs skill (`references/month-end-close.md`), run reports, and create any adjusting journals.

```bash
# Run key reports for review
clio reports generate trial-balance --to 2026-03-31 --json > tb-mar.json
clio reports generate profit-loss --from 2026-03-01 --to 2026-03-31 --json > pl-mar.json
clio reports generate balance-sheet --to 2026-03-31 --json > bs-mar.json
clio reports generate bank-reconciliation-summary --to 2026-03-31 --json > recon-mar.json

# Create adjusting journal if needed
clio journals create \
  --date 2026-03-31 \
  --ref "ADJ-MAR-001" \
  --entries '[
    {"accountResourceId":"Accrued Expenses","amount":1500,"type":"DEBIT"},
    {"accountResourceId":"Consulting Expense","amount":1500,"type":"CREDIT"}
  ]' \
  --finalize

# Generate aged AR/AP reports
clio reports generate aged-receivables --to 2026-03-31 --json > aged-receivables-mar.json
clio reports generate aged-payables --to 2026-03-31 --json > aged-payables-mar.json
```

## 4. FX Transaction: Add Currency, Set Rate, Create Invoice

Handle a foreign currency invoice from start to finish.

```bash
# Add USD currency to the org (idempotent, safe to re-run)
clio currencies add USD

# Set the exchange rate for the period.
# --rate defaults to functionalToSource: 1 SGD = 0.7435 USD.
clio currency-rates add USD --rate 0.7435 --from 2026-03-01 --to 2026-03-31

# Holding an everyday "1 USD = 1.3450 SGD" quote instead? Declare the
# direction and send it as-is rather than inverting by hand.
clio currency-rates add USD --rate 1.3450 --rate-direction SOURCE_TO_FUNCTIONAL \
  --from 2026-03-01 --to 2026-03-31

# For bulk updates, prepare a JSON file and use bulk-upsert (max 500 rates/call)
clio currency-rates bulk-upsert --input rates.json

# Create an invoice in USD (org base is SGD)
clio invoices create \
  --contact "US Client Inc" \
  --date 2026-03-15 \
  --due 2026-04-15 \
  --ref "INV-USD-001" \
  --currency USD \
  --exchange-rate 0.7435 \
  --lines '[{"name":"Software License","quantity":1,"unitPrice":2000,"accountResourceId":"Revenue"}]' \
  --finalize

# Record payment (cross-currency: amount in bank currency, transaction-amount in invoice currency)
INVOICE_ID=$(clio invoices search --reference INV-USD-001 --json | jq -r '.data[0].resourceId')
clio invoices pay "$INVOICE_ID" \
  --amount 2690 \
  --transaction-amount 2000 \
  --account "Bank - SGD" \
  --method BANK_TRANSFER \
  --ref "PAY-USD-001" \
  --date 2026-04-10
```

## 5. Equipment Purchase with Depreciation

Register a fixed asset, cross-check its depreciation schedule, and (for a declining-balance method only) post the charges into a capsule.

```bash
# Register the asset. Jaz posts straight-line depreciation itself: do not also journal it.
clio fixed-assets create \
  --name "Office Printer" \
  --type "Office Equipment" \
  --amount 3600 \
  --date 2026-01-01 \
  --depreciation-start 2026-01-01 \
  --asset-account "$ASSET_ACCOUNT_ID" \
  --depreciation-method STRAIGHT_LINE \
  --effective-life 36 \
  --residual 0

# Cross-check the schedule (offline, no auth). --life is in YEARS; --method is sl, ddb or 150db.
clio calc depreciation \
  --cost 3600 \
  --salvage 0 \
  --life 3 \
  --method sl \
  --frequency monthly \
  --currency SGD \
  --json

# Declining balance (ddb / 150db) is not a register method: register the asset with
# --depreciation-method NO_DEPRECIATION, then post each period's charge from the calculator yourself.
clio capsules types --json
clio capsules create --type "$CAPSULE_TYPE_ID" --title "Office Printer depreciation" --json
clio journals create --input dep-2026-01.json --json   # body: valueDate, journalEntries, capsuleResourceId
```

## 6. Search, Filter, and Bulk-Update Workflow

Find transactions matching criteria and bulk-update them.

```bash
# Search invoices via structured --query syntax (see api skill: references/search-syntax.md)
clio invoices search --query "customer:acme AND status:unpaid AND \$500+" --json

# Or with discrete flags
clio invoices search --contact-name "Acme Corp" --status DRAFT --from 2026-01-01 --json

# Extract IDs of matching drafts
DRAFT_IDS=$(clio invoices search --status DRAFT --from 2026-03-01 --to 2026-03-31 --json \
  | jq -r '[.data[].resourceId] | join(",")')

# Bulk-update: set tag and due date on all matching invoices
clio quick-fix invoices --ids "$DRAFT_IDS" --tag "Q1-Review" --due 2026-04-30

# Bulk-update line items (e.g., reassign account)
clio quick-fix invoices --line-items --ids "$LINE_ITEM_IDS" \
  --account "<target-account-resourceId>"

# Find & fix (recode) across record types: no ID list needed. Preview moves every
# journal and cash entry line on the old account to the new one, writing nothing
clio ledger-find-fix preview --level LINE_ITEMS \
  --filter '{"types":["JOURNAL","CASH_ENTRY"],"organizationAccountResourceId":{"eq":"<old-account-resourceId>"}}' \
  --change '{"organizationAccountResourceId":"<new-account-resourceId>"}'

# Apply the preview once you have checked it (-- because a previewId can start with "-")
clio ledger-find-fix apply -- "<previewId>"
```

## 7. Multi-Org Management

Manage multiple organizations from one machine.

```bash
# Prefer OAuth: clio auth login, then pin --org oauth:<resourceId> per call.
# Optional alternative: add multiple org keys
clio auth add jk-sg-key-here --as acme-sg
clio auth add jk-ph-key-here --as acme-ph
clio auth add jk-us-key-here --as acme-us

# List all profiles
clio auth list

# Switch active org
clio auth switch acme-sg
clio auth whoami

# Run commands against specific orgs without switching
clio invoices list --org acme-ph --json > ph-invoices.json
clio invoices list --org acme-us --json > us-invoices.json

# Pin an org for the session (all commands use this until unpin)
export JAZ_ORG=acme-sg
clio invoices list     # Uses acme-sg
clio contacts list     # Uses acme-sg

# Unpin
clio auth unpin
# Or: unset JAZ_ORG

# Generate shell exports for scripting
eval "$(clio auth shell-init)"
```

## 8. Document Collection and AI Extraction

Ingest documents, extract data via AI, and review results.

```bash
# Scan and classify a folder of mixed PDFs (invoices, bills, bank statements); add --upload to send them to Jaz
clio jobs document-collection ingest --source ./client-docs --json

# Or extract a single document (file, URL, or raw HTML)
clio magic create --file ./invoice-from-supplier.pdf --type bill --json

# From raw HTML, e.g. an email body (rendered to a PDF, then extracted)
clio magic create --html @./email-body.html --type invoice --json

# Check workflow status
clio magic status "wf-id-1,wf-id-2,wf-id-3" --json

# Search past magic workflows
clio magic status <workflowIds> --json   # comma-separated ids from `magic create`

# For encrypted PDFs: embed the password in the filename via __pw__
clio magic create --file ./encrypted-file__pw__secret123.pdf --type invoice --json
```