@receiptor/cli

Receiptor CLI lets you discover and run Receiptor capabilities from the terminal. It is a thin client over the Receiptor capability API, so the command surface adapts to whatever capabilities your API key can access.

Install

curl -fsSL https://receiptor.ai/install.sh | bash

Or install directly with npm:

npm install -g @receiptor/cli

For a one-off run without a global install:

npx @receiptor/cli --help

Quick Start

receiptor auth sk_your_api_key
receiptor workspace list
receiptor workspace use org_123
receiptor list
receiptor documents search --query "uber" --limit 5
receiptor files upload ./receipt.pdf

You can also inspect available resources and actions directly from the CLI:

receiptor --help
receiptor documents --help
receiptor documents search --help

Bookkeeping Skills

If you want agent-ready bookkeeping procedures alongside the Receiptor CLI, install the public bookkeeping skills library.

Recommended:

npx skills add Receiptor-AI/bookkeeping-skills

Install a single skill:

npx skills add Receiptor-AI/bookkeeping-skills --skill receipt-processing

Canonical references:

• GitHub: https://github.com/Receiptor-AI/bookkeeping-skills
• Docs: https://bookkeeping.md

Bundled CLI Skills

The CLI also ships with Receiptor-specific skills for agents that can read local skill folders.

List the bundled skills:

receiptor skills list

Install all bundled CLI skills into a project-local .agents/skills folder:

receiptor skills install

Install one bundled skill:

receiptor skills install --skill receipt-intake
receiptor skills install --skill setup-readiness

Install for a specific agent:

receiptor skills install --agent codex
receiptor skills install --agent claude-code
receiptor skills install --agent opencode

Print the target path without installing:

receiptor skills path --agent codex

Use receiptor skills --help for the full command syntax.

How It Works

The CLI has two layers:

• Built-in commands for auth, workspace selection, approvals, and capability discovery
• Dynamic capability commands exposed by the Receiptor API, using the format receiptor <resource> <action>

Examples:

receiptor documents search --query "uber"
receiptor documents get --id "abc123"
receiptor integrations list
receiptor currency convert --from USD --to EUR --amount 100
receiptor files upload ./receipt.pdf

Capability execution responses are printed as JSON, which makes the CLI easy to script in shells and CI jobs. Built-in helper commands such as auth, workspace, and list use human-readable terminal output.

The current bundled skill split is:

• setup-readiness for auth, workspace, integrations, and setup-gap review
• receipt-intake for document discovery and inspection
• categorization-review for cleanup and corrections
• spend-analysis for totals and grouped reporting

Authentication

Save an API key locally:

receiptor auth sk_your_api_key

Check status:

receiptor auth --status

The CLI stores config in:

~/.receiptor/config.json

You can override the stored API key for a single command with RECEIPTOR_API_KEY.

Workspaces

If your API key can access multiple organizations, you can inspect and switch workspace context.

Show current workspace:

receiptor workspace --status

List available workspaces:

receiptor workspace list

Select a workspace:

receiptor workspace use org_123

Clear the saved workspace:

receiptor workspace clear

You can override the saved workspace for a single command with RECEIPTOR_ORG_ID.

Built-in workspace help:

receiptor workspace --help

To inspect API-visible workspaces without changing the local CLI context:

receiptor workspaces list

Executing Capabilities

The general format is:

receiptor <resource> <action> [flags]

Examples:

receiptor documents search --query "uber" --limit 5
receiptor documents get --id "abc123"
receiptor currency convert --from USD --to EUR --amount 100
receiptor files upload ./receipt.pdf

To discover what is available to your key:

receiptor list

To inspect inputs for a specific capability:

receiptor documents search --help

That command prints the capability description, permissions, and input schema returned by the API.

Local File Uploads

For uploads from your local machine, use the built-in path adapter:

receiptor files upload ./receipt.pdf
receiptor files upload ~/Downloads/invoice.jpg

The CLI reads the file from disk, infers the MIME type from the extension, and uploads it to the public multipart file endpoint for processing. This keeps local uploads human-friendly without requiring you to paste base64 data manually.

Input Formats

The CLI accepts input in three ways.

Flags

receiptor documents search --query "uber" --limit 5 --archived false

Values are parsed with a few simple coercions:

• numbers become numbers
• true and false become booleans
• everything else stays a string

Nested object fields can be expressed with dot notation:

receiptor documents search --filters.merchant "Uber" --pagination.limit 10

Inline JSON

receiptor documents search '{"query":"uber","limit":5}'

JSON via stdin

echo '{"query":"uber","limit":5}' | receiptor documents search

If stdin is present, the CLI uses that JSON payload instead of parsing flags.

Approval Flow

Some mutation capabilities are gated. In that case the API returns an approval request instead of executing immediately.

Example:

receiptor documents bulk-edit \
  --merchant "Uber" \
  --changes '{"category":"Transport"}' \
  --dryRun false

If approval is required, the CLI prints a payload with:

• status: "approval_required"
• approvalRequestId
• capability metadata and a human-readable description

You can then inspect or resolve the request:

receiptor approval get 01J...
receiptor approval approve 01J...
receiptor approval reject 01J... --message "Not safe to run yet"

Environment Variables

The CLI supports these environment variables:

• RECEIPTOR_API_KEY: override the stored API key
• RECEIPTOR_ORG_ID: override the saved workspace/org context
• RECEIPTOR_HOST: override the API host in non-production runtimes
• RECEIPTOR_ENV: when set to production, host overrides are ignored and the default production-safe host is used
• RECEIPTOR_DISABLE_UPDATE_CHECK: disable npm update checks when set to 1 or true

Output and Scripting

Capability responses are printed as formatted JSON:

receiptor documents search --query "uber" | jq .

Because output is machine-readable, the CLI works well in shell scripts and automation.

Version And Diagnostics

Show the installed CLI version:

receiptor version
receiptor --version
receiptor -v

Print local config, auth source, host, workspace, update cache state, and basic API reachability:

receiptor doctor

The CLI also checks npm periodically and prints a non-blocking update notice to stderr when a newer version is available.

Troubleshooting

No API key configured

Run:

receiptor auth sk_your_api_key

Could not connect to ...

• verify the configured host is reachable
• if you are targeting a non-default environment, set RECEIPTOR_HOST
• retry with receiptor auth --status to confirm the active host and workspace

Selected workspace is not available to this API key

Run:

receiptor workspace list

Then switch to a workspace that your key can access.