Inbox
Manage inbox items from expenses, receipts, and imported documents
Inbox items are financial records from manual entry, receipts, and imported documents that are not tied to a bank transaction yet.
inbox list
List inbox items.
expensicat inbox list
expensicat inbox list --type expense --status pending| Flag | Description |
|---|---|
--type <string> | expense or income |
--status <string> | Inbox item status |
--cursor <string> | Pagination cursor |
--limit <number> | Page size |
inbox show
Get an inbox item by ID.
expensicat inbox show inb_abc123| Arg | Description |
|---|---|
<id> | Inbox item ID |
inbox create
Create an inbox item. Interactive when fields are missing, or pipe JSONL via --batch - for bulk creates.
expensicat inbox create --date 2026-04-15 --amount 129.00 --type expense --description "AWS bill"
cat inbox.jsonl | expensicat inbox create --batch - --concurrency 5| Flag | Description |
|---|---|
--date <string> | Date (YYYY-MM-DD, required) |
--amount <number> | Amount (required) |
--description <string> | Description |
--currency <string> | Currency code; defaults to EUR |
--type <string> | expense or income; defaults to expense |
--batch <path|-> | Read items from a file or stdin — see Batch input |
inbox update
Update an inbox item.
expensicat inbox update inb_abc123 --amount 149.99 --category-id cat_software| Arg | Description |
|---|---|
<id> | Inbox item ID |
| Flag | Description |
|---|---|
--description <string> | New description |
--amount <number> | New amount |
--category-id <string> | Assign a category |
inbox delete
Delete an inbox item. Prompts for confirmation in a terminal; pass --yes to skip.
expensicat inbox delete inb_abc123
expensicat inbox rm inb_abc123 --yes # alias + skip prompt| Arg | Description |
|---|---|
<id> | Inbox item ID |
| Flag | Description |
|---|---|
-y, --yes | Skip the confirmation prompt (required for non-interactive use) |
inbox upload
Upload a receipt (or a whole folder of receipts) and create inbox items from them. The CLI uploads each file to the team's vault, creates a receipt document, and then creates an inbox item linked to the document. OCR runs server-side and auto-fills amount, currency, date, vendor, and category.
# One receipt
expensicat inbox upload ./receipt.pdf --type debit
# Whole folder, 3 uploads in parallel
expensicat inbox upload ~/receipts-q1 --concurrency 3
# Recursive + glob filter, emit JSONL for piping
expensicat inbox upload ~/receipts --recursive --pattern '*.pdf' --json| Arg | Description |
|---|---|
<path> | Path to a receipt file or a folder of receipts |
| Flag | Description |
|---|---|
--type <type> | debit (expense, default) or credit (income) |
--concurrency <n> | Parallel uploads, 1–10 (default 3) |
--recursive | Walk subdirectories when the target is a folder |
--pattern <glob> | Filter files by filename glob (e.g. '*.pdf'). Default * |
--fail-fast | Stop at the first failure instead of collecting all errors |
--json | Emit one JSONL result per file (for pipelines) |
Under the hood: each file is PUT to vault → POST /api/v1/documents (category receipt) → POST /api/v1/inbox with the primary_document_id. OCR fires automatically on the inbox endpoint when no amount is provided.
Skipped automatically when walking a folder: hidden files, symlinks, zero-byte files, and node_modules/.git under --recursive.
Exit codes match document upload — 0 / 9 / 1 / 2.