teamtinvio/jaz-ai / .agents/skills/cli
jaz-cli
VerifiedUse this skill when running Clio CLI commands, building shell scripts with Clio, debugging auth issues, understanding --json output, paginating results, or chaining multi-step accounting workflows from the terminal. Covers auth precedence, output formats, entity resolution, and common workflow patterns. Also use when the user asks how to use clio, what commands are available, or how to automate accounting tasks from the command line. Covers all 77 command groups and 477 tools, including employee-expense claims.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 24.8 KB |
| references/agent-gotchas.md | markdown | 6.6 KB |
| references/command-catalog.md | markdown | 49.2 KB |
| references/common-workflows.md | markdown | 8.7 KB |
| references/error-recovery.md | markdown | 5.9 KB |
| references/field-guide.md | markdown | 4.6 KB |
| references/output-shapes.md | markdown | 4.0 KB |
references/field-guide.md
View on GitHub# 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |