Documents
Upload, download, and manage receipts and attachments
document list
List documents.
expensicat document list| Flag | Description |
|---|---|
--cursor <string> | Pagination cursor |
--limit <number> | Page size |
document show
Get a document by ID.
expensicat document show doc_abc123| Arg | Description |
|---|---|
<id> | Document ID |
document upload
Upload a single file or an entire folder of documents. Files are uploaded to the team's vault bucket and then linked as document records.
# Single file
expensicat document upload ./invoice.pdf --category invoice
# Whole folder, 5 uploads in parallel
expensicat document upload ~/receipts-q1 --concurrency 5
# Recursive walk + glob filter
expensicat document upload ~/receipts-2026 --recursive --pattern '*.pdf'
# Agent pattern: stream JSONL results for piping
expensicat document upload ./receipts --json | jq '.data.documentId'| Arg | Description |
|---|---|
<path> | Path to a file or a folder of files |
| Flag | Description |
|---|---|
--category <c> | receipt, invoice, contract, tax, insurance, legal, report, bank_statement, or other (default) |
--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 /api/v1/storage/object/vault/{orgId}/imports/cli/… first, then POST /api/v1/documents links the uploaded path to a document record with the chosen category.
Skipped automatically when walking a folder: hidden files (.name), symlinks (to avoid walk loops), zero-byte files, and node_modules/.git directories under --recursive.
Exit codes: 0 if every file succeeded, 9 (PARTIAL_FAILURE) if some succeeded and some failed, 1 if all failed, 2 for usage errors (invalid --category, missing path, empty folder).
document download
Download a document to a file or stdout.
# Save to a file
expensicat document download doc_abc123 -o ./invoice.pdf
# Stream to stdout (pipe into anything)
expensicat document download doc_abc123 > ./invoice.pdf| Arg | Description |
|---|---|
<id> | Document ID |
| Flag | Description |
|---|---|
-o, --output <path> | Output file path; streams to stdout if omitted |
document delete
Soft-delete a document. Prompts for confirmation in a terminal; pass --yes to skip.
expensicat document delete doc_abc123
expensicat document rm doc_abc123 --yes # alias + skip prompt| Arg | Description |
|---|---|
<id> | Document ID |
| Flag | Description |
|---|---|
-y, --yes | Skip the confirmation prompt (required for non-interactive use) |
document restore
Restore a soft-deleted document.
expensicat document restore doc_abc123| Arg | Description |
|---|---|
<id> | Document ID |