# CLI Field Guide

> Maps CLI flags to API fields, lists required fields per command, and valid status values.
> This replaces the need to read the jaz-api skill for CLI-only usage.

## Flag → API Field Mapping

| CLI Flag | API Field | Notes |
|----------|-----------|-------|
| `--contact "name"` | `contactResourceId` | Fuzzy-resolved (name or UUID) |
| `--account "name"` | `accountResourceId` | Fuzzy-resolved at top level ONLY |
| `--date YYYY-MM-DD` | `valueDate` | Org-local timezone, not UTC |
| `--due YYYY-MM-DD` | `dueDate` | |
| `--ref "INV-001"` | `reference` | Must be unique per entity type |
| `--currency SGD` | `currencyCode` | Uppercase ISO 4217 |
| `--tag "Q1"` | Tag name (resolved to tag object) | |
| `--status DRAFT` | `status` | Uppercase enum |
| `--lines '[...]'` | `lineItems` array | Each needs: name, quantity, unitPrice, accountResourceId |
| `--entries '[...]'` | `journalEntries` array | Each needs: accountResourceId, debit OR credit |
| `--finalize` | `saveAsDraft: false` | Transaction commands only. CLI defaults to draft (saveAsDraft: true); master-data creates have no draft state |
| `--bank-account "name"` | `bankAccountResourceId` | Fuzzy-resolved |
| `--tax-profile "name"` | `taxProfileResourceId` | Fuzzy-resolved |

## Required Fields per Create Command

### Invoices / Bills
```
clio invoices create --contact "Acme" --date 2026-01-15 --due 2026-02-15 \
  --lines '[{"name":"Consulting","quantity":1,"unitPrice":5000,"accountResourceId":"uuid-or-exact-name"}]'
```
Required: `--contact`, `--date`, `--due`, `--lines` (each line needs name, quantity, unitPrice, accountResourceId)

### Journals
```
clio journals create --date 2026-01-15 \
  --entries '[{"accountResourceId":"uuid","debit":1000},{"accountResourceId":"uuid","credit":1000}]'
```
Required: `--date`, `--entries` (must balance: total debits = total credits)

### Contacts
```
clio contacts create --name "Acme Corp" --customer true
```
Required: `--name`. Optional: `--customer true`, `--supplier true`, `--currency SGD`

### Cash Entries (cash-in / cash-out)
```
clio cash-in create --account "Bank - SGD" --date 2026-01-15 \
  --entries '[{"accountResourceId":"uuid","debit":1000}]'
```
Required: `--account`, `--entries`, `--date`. Each entry needs accountResourceId + debit or credit.

## Status Values

| Entity | Valid Statuses |
|--------|---------------|
| Invoices | `DRAFT`, `UNPAID`, `PARTIALLY_PAID`, `PAID`, `VOID` |
| Bills | `DRAFT`, `UNPAID`, `PARTIALLY_PAID`, `PAID`, `VOID` |
| Credit Notes | `DRAFT`, `UNAPPLIED`, `PARTIALLY_APPLIED`, `APPLIED`, `VOID` |
| Journals | `DRAFT`, `ACTIVE`, `VOID` |
| Contacts | `ACTIVE`, `INACTIVE` |
| Items | `ACTIVE`, `INACTIVE` |
| Fixed Assets | `ACTIVE`, `DRAFT`, `DISPOSED`, `SOLD`, `DISCARDED`, `COMPLETED`, `ONGOING` |

Use in search: `clio invoices search --status UNPAID --json`

## CLI-Specific Gotchas

1. **Create returns minimal response**: only `{ "resourceId": "uuid" }`. Run `clio invoices get <id> --json` for full data.
2. **Line-item accounts don't fuzzy-resolve**: `--lines` JSON requires exact account name or UUID. Top-level `--account` fuzzy-resolves.
3. **Transaction creates default to draft**: invoices, bills, journals, credit notes and orders. Use `--finalize` to create as finalized (UNPAID for invoices, ACTIVE for journals). Cash entries and cash transfers are the exception: they post ACTIVE and accept no `--finalize`. Master data has no draft state either: contacts, items, accounts, tags, tax profiles and the rest are created live.
4. **`--offset` is page number (0-indexed)**: not row skip count. offset=0 + limit=100 = page 1. Exceptions, where `--offset` is a ROW offset (next page = offset + limit): `purchase-items list/search`, `currency-rates list`, `claims payouts` and `reports generate general-ledger`. Each command's `--offset` help says which it is, and `--all` pages both kinds correctly.
5. **`customer` is boolean**: `--customer true`, not `--customer "Acme"`.
6. **Dates are YYYY-MM-DD**, org-local timezone. API returns epoch ms but CLI formats them.
7. **`--all` caps at 1,000 rows**: lowered from 10,000 in 2026-04 (DEFAULT_MAX_ROWS in commands/pagination.ts). Pass `--max-rows 50000` for larger datasets, and check `truncated` in the response before treating a page as complete.
8. **JSON goes to stdout, errors to stderr**: `clio invoices list --json 2>/dev/null | jq .` is safe.
9. **`--finalize` skips draft**: creates finalized (e.g., UNPAID for invoices). Without it a TRANSACTION is DRAFT; master data is live either way, because `saveAsDraft` does not exist for those entities.
10. **Currency codes are uppercase**: `SGD` not `sgd`. API rejects lowercase.