npm package: @receiptor/cli
Description: Receiptor CLI for discovering and executing Receiptor capabilities from the terminal.
Latest version: 0.8.0

# @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

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

Or install directly with npm:

```bash
npm install -g @receiptor/cli
```

For a one-off run without a global install:

```bash
npx @receiptor/cli --help
```

## Quick Start

```bash
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:

```bash
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:

```bash
npx skills add Receiptor-AI/bookkeeping-skills
```

Install a single skill:

```bash
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:

```bash
receiptor skills list
```

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

```bash
receiptor skills install
```

Install one bundled skill:

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

Install for a specific agent:

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

Print the target path without installing:

```bash
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:

```bash
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:

```bash
receiptor auth sk_your_api_key
```

Check status:

```bash
receiptor auth --status
```

The CLI stores config in:

```text
~/.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:

```bash
receiptor workspace --status
```

List available workspaces:

```bash
receiptor workspace list
```

Select a workspace:

```bash
receiptor workspace use org_123
```

Clear the saved workspace:

```bash
receiptor workspace clear
```

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

Built-in workspace help:

```bash
receiptor workspace --help
```

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

```bash
receiptor workspaces list
```

## Executing Capabilities

The general format is:

```bash
receiptor <resource> <action> [flags]
```

Examples:

```bash
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:

```bash
receiptor list
```

To inspect inputs for a specific capability:

```bash
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:

```bash
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

```bash
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:

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

### Inline JSON

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

### JSON via stdin

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
receiptor version
receiptor --version
receiptor -v
```

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

```bash
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:

```bash
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:

```bash
receiptor workspace list
```

Then switch to a workspace that your key can access.