CLI

The Invoice Radar CLI is currently macOS only. Linux and Windows support is on the roadmap.

Overview

The Invoice Radar CLI turns the desktop app into a scriptable invoice collection backend for terminals and AI agents.

Use it to:

Fetch invoices from any connected service on demand
Search, export, and sync your documents
Hand the keys to an AI agent so it can collect invoices for you
Build and test new plugins against real billing platforms

Install

Open Invoice Radar and go to Settings → General → CLI Access, then enable Invoice Radar CLI.

Verify it's working:

invoice-radar status

If your shell can't find invoice-radar, add this to your shell profile and reopen the terminal:

export PATH="$HOME/.local/bin:$PATH"

If the desktop app isn't running, this opens it and waits until it's ready:

invoice-radar open --wait

Quickstart

Add an integration, run it, and export an invoice:

invoice-radar integrations available stripe
invoice-radar integrations add stripe
invoice-radar run stripe
invoice-radar docs search stripe --limit 5
invoice-radar docs export <document-id> ./invoice.pdf

Targeting an organization

Most commands use the organization selected in the desktop app. To target a different one:

invoice-radar --org <org-id> docs search aws

JSON output

For machine-readable output, add --json:

invoice-radar --json docs search aws

Managing integrations

List connected integrations:

invoice-radar integrations list

Browse available integrations:

invoice-radar integrations available
invoice-radar integrations available stripe

Add an integration:

invoice-radar integrations add stripe

The display name defaults to the integration name, for example Stripe. To use a custom name:

invoice-radar integrations add stripe --name "Stripe EU"

Show or remove one:

invoice-radar integrations show <integration-id>
invoice-radar integrations remove <integration-id> --yes

Running integrations

Run the full integration flow:

invoice-radar run <integration-id>

<integration-id> can be an instance ID, or a plugin ID when only one instance matches.

Run only one mode:

invoice-radar run <integration-id> --mode check-auth
invoice-radar run <integration-id> --mode start-auth
invoice-radar run <integration-id> --mode config-options
invoice-radar run <integration-id> --mode documents

Debug a run:

invoice-radar run <integration-id> --debug
invoice-radar run <integration-id> --keep-browser-open
invoice-radar run <integration-id> --verbose

Pause at a breakpoint. The value is a JSON array of step locations — each entry pauses before the step at index for length steps:

invoice-radar run <integration-id> \
  --breakpoint '[{"index":0,"length":1,"type":"step"}]'

Stop a running integration:

invoice-radar stop <integration-id>

Documents

Import a local PDF:

invoice-radar docs import ./invoice.pdf

Search documents:

invoice-radar docs search "aws" --limit 25
invoice-radar docs search "aws" --unsorted
invoice-radar docs search "aws" --include-deleted
invoice-radar docs search "aws" --deleted

Show document metadata or extracted PDF text:

invoice-radar docs show <document-id>
invoice-radar docs show <document-id> --text

Export a PDF:

invoice-radar docs export <document-id> ./out/invoice.pdf
invoice-radar docs export <document-id> ./out/invoice.pdf --force
invoice-radar docs export <document-id> ./out/invoice.pdf --dry-run

Sync unsynced invoices to an export destination:

invoice-radar docs sync --destination <destination-id>
invoice-radar docs sync --destination <destination-id> --invoice <document-id>
invoice-radar docs sync --destination <destination-id> --force

CLI export is not available for trial organizations when the export would need a watermark.

Config and autofill

Integration config

Show, describe, or set saved config:

invoice-radar integrations config get <integration-id>
invoice-radar integrations config describe <integration-id>
invoice-radar integrations config set <integration-id> accountId=acct_123 enabled=true

Pipe JSON:

printf '%s' '{"accountId":"acct_123","mailboxes":["Invoices"]}' \
  | invoice-radar integrations config set <integration-id>

Pipe one raw value for one key:

printf '%s' "$PASSWORD" \
  | invoice-radar integrations config set <integration-id> autofill.password

Replace the full config instead of merging:

printf '%s' '{"accountId":"acct_123"}' \
  | invoice-radar integrations config set <integration-id> --replace

Autofill

Autofill lets Invoice Radar fill login forms. Plugins can expose username, password, OTP, and submit fields. To see what an integration supports:

invoice-radar integrations autofill fields <integration-id>

Store autofill values in the app config by piping through stdin:

printf '%s' "$USERNAME"   | invoice-radar integrations autofill set <integration-id> username
printf '%s' "$PASSWORD"   | invoice-radar integrations autofill set <integration-id> password
printf '%s' "$OTP_SECRET" | invoice-radar integrations autofill set <integration-id> otpSecret

Use otpSecret for a saved TOTP secret. The CLI also accepts otp as a short alias.

For one run only, pass values as environment variables:

IR_AUTOFILL_USERNAME="me@example.com" \
IR_AUTOFILL_PASSWORD="$PASSWORD" \
IR_AUTOFILL_OTP_SECRET="$OTP_SECRET" \
invoice-radar run <integration-id>

Or pipe a JSON object into run — useful for agents that keep secrets in their own vault:

printf '%s' '{"autofill.username":"me@example.com","autofill.password":"secret"}' \
  | invoice-radar run <integration-id>

When both are present, stdin JSON overrides IR_AUTOFILL_* environment variables for the same field.

Using the CLI from an agent

An agent can use Invoice Radar as a tool instead of visiting every billing site manually. First make sure CLI access is enabled, or start the app through the CLI:

invoice-radar open --wait

For an existing integration, the typical agent loop is:

invoice-radar run <integration-id>
invoice-radar docs search "<vendor or invoice id>" --json
invoice-radar docs export <invoice-id> ./out/invoice.pdf

If a platform is not supported yet, the agent can create a plugin JSON file, point Invoice Radar at the folder, add the local integration, and test it:

invoice-radar integrations dev use ./invoice-radar-plugins
invoice-radar integrations available example
invoice-radar integrations add example
invoice-radar run example --debug

Local plugin development

Use a folder of local plugin JSON files:

invoice-radar integrations dev use ./plugins

Check or clear the active plugin folder:

invoice-radar integrations dev current
invoice-radar integrations dev clear

Local plugins show up in integrations available, so an agent can create or edit a plugin, test it, inspect the run, and keep improving it.

Debugging

A typical debug loop: pause a run at a breakpoint, take a screenshot or inspect state, then continue.

List running or paused integrations:

invoice-radar debug list

Show run status and state:

invoice-radar debug status <integration-id>
invoice-radar debug state <integration-id>
invoice-radar debug step-state <integration-id> s-0

Continue after a breakpoint:

invoice-radar debug continue <integration-id>

Inspect the browser:

invoice-radar debug screenshot <integration-id> --out ./screen.png
invoice-radar debug get-html <integration-id>
invoice-radar debug get-html <integration-id> --selector "#app"
invoice-radar debug run-js <integration-id> --script "document.title"
invoice-radar debug network <integration-id> --limit 50
invoice-radar debug network <integration-id> --url invoices --method GET --detailed

Command reference

Command	What it does
`status`	Checks whether the desktop app is connected and shows the current organization.
`open`	Opens the desktop app. `--wait` waits until the CLI connection is ready.
`org list`	Lists organizations.
`docs import`	Imports a local PDF invoice.
`docs search`	Searches saved, unsorted, or deleted documents.
`docs show`	Shows document metadata or extracted PDF text.
`docs export`	Exports one invoice PDF to a file.
`docs sync`	Syncs invoices to an export destination.
`integrations list`	Lists connected integrations.
`integrations available`	Searches available local and remote integrations.
`integrations add`	Adds a connected integration.
`integrations show`	Shows one connected integration.
`integrations remove`	Removes one connected integration.
`integrations autofill fields`	Shows available autofill fields.
`integrations autofill set`	Stores one autofill value from stdin.
`integrations config get`	Shows saved integration config with secrets redacted.
`integrations config describe`	Shows config and autofill fields.
`integrations config set`	Sets config from key/value args, JSON stdin, or one raw stdin value.
`integrations dev current`	Shows the active local plugin folder.
`integrations dev use`	Uses a folder for local plugin development.
`integrations dev clear`	Clears the local plugin folder.
`run`	Runs an integration.
`stop`	Stops a running integration.
`debug list`	Lists running or paused integrations.
`debug status`	Shows running debug status.
`debug continue`	Continues from a breakpoint.
`debug state`	Shows run state summary.
`debug step-state`	Shows saved state for one step.
`debug screenshot`	Saves a screenshot of the running browser.
`debug get-html`	Prints HTML from the running browser.
`debug run-js`	Runs JavaScript in the running browser.
`debug network`	Shows captured network requests.

Getting help

Run any command with --help to see its flags. For bugs or feature requests, open an issue on GitHub or reach us through the in-app support chat.

On this page