Invoice RadarInvoice Radar

CLI

Run Invoice Radar from a terminal or an AI agent.

The Invoice Radar CLI is available on macOS and Linux. 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 → CLI & MCP Access, then enable 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

Linux

The CLI ships with both Linux packages:

  • deb: installing the package links /usr/bin/invoice-radar to the bundled CLI, so it's on your PATH right away. Enable CLI in the app so it accepts connections. The desktop app itself starts with invoice-radar-app.
  • AppImage: enabling CLI installs a small launcher at ~/.local/bin/invoice-radar that runs your AppImage. The launcher is refreshed every time you open the app, so after you move or rename the AppImage, open it once before using the CLI again. AppImages need FUSE; on Ubuntu 22.04 and later, install libfuse2 (libfuse2t64 on 24.04 and later).

The settings page shows a hint if ~/.local/bin isn't on your PATH. Some distributions only add it after you log in again.

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

Archived integrations are left out, and the list says how many there are. Add --archived to list only those, or --all to list everything with an Archived column.

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

Archive an integration you only needed once. Its documents stay, and you can restore it any time. A running integration has to stop first.

invoice-radar integrations archive <integration-id>
invoice-radar integrations restore <integration-id>

run with a plugin ID such as stripe only picks among active integrations. To run an archived one, use its ID.

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

Runs use your organization's start date, just like runs from the app. Collect from a different date:

invoice-radar run <integration-id> --start-date 2026-01-01

Each run starts by printing the plugin file, app version, browser profile, and organization it uses. When it finishes, it reports document counts, how many pages each paginated list had, and any warnings. A warning means the run recovered from an error, for example one failed loop iteration, so some documents may be missing. The exit code tells scripts and agents how the run ended:

Exit codeMeaning
0Finished cleanly, or paused at a breakpoint.
1Failed or cancelled.
2Finished with warnings or failed document downloads.
3Not signed in.

With --json, the same result is in the outcome field (ok, partial, failed, cancelled, not-authenticated, or paused), alongside warnings, pagination, and run.

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
invoice-radar docs search --attribute sent_to_accountant=true
invoice-radar docs search --integration <integration-id> --metadata accountId=4821-0937-1123
invoice-radar docs search --sort attr:cost_center --order asc

Search text also matches document notes. Results are sorted by document date, newest first. Use --sort with date, added, amount, attr:<key> for a custom attribute, or meta:<key> for an integration metadata field, and --order asc or desc. Documents without a value are always listed last. Use --integration with an integration ID from integrations list to search one integration, and --metadata key=value to match an integration-specific field.

Show document metadata or extracted PDF text:

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

Delete documents the same way as in the app. By default they move to the trash, where they can be restored for 30 days:

invoice-radar docs delete <document-id> [<document-id>...]
invoice-radar docs restore <document-id> [<document-id>...]

To delete documents for good, choose whether integrations may download them again. Permanent deletion asks for confirmation; pass --yes to skip it:

invoice-radar docs delete <document-id> --permanent
invoice-radar docs delete <document-id> --allow-redownload

--permanent keeps Invoice Radar from downloading the document again. --allow-redownload lets the next run download it again if the service still offers it. Use the ID from docs search when an invoice number matches more than one document.

Add, replace, or clear a note. Notes appear in docs show and search results, including JSON output:

invoice-radar docs note set <document-id> "Sent to accountant on Tuesday"
invoice-radar docs note clear <document-id>

Custom attributes

Create a custom field, then set it on an invoice:

invoice-radar attributes create "Sent to accountant" --type boolean
invoice-radar attributes list
invoice-radar docs attribute set <document-id> sent_to_accountant true
invoice-radar docs attribute clear <document-id> sent_to_accountant

Use --attribute key=value with docs search to find matching invoices. For yes/no fields, use true or false. Use --attribute-unset key for other field types to find invoices without a value. The filter can be combined with ordinary search text. Search results and docs show include custom attribute values, including with --json.

The available types are string, number, boolean, and enum. Selection fields use --values, for example:

invoice-radar attributes create "Accounting status" --type enum --values "Pending,Sent"
invoice-radar docs attribute set <document-id> accounting_status Sent
invoice-radar docs search --attribute accounting_status=Sent
invoice-radar docs search --attribute-unset accounting_status

Text and number fields can also be matched by exact value, such as --attribute project_code=ABC123. Add --ai and optionally --prompt "..." when creating a field if AI should fill it from documents.

Rename a field without changing its stable key, or delete one. Deleting a field keeps its existing values on documents. Creating a field with the same key later will show those values again:

invoice-radar attributes rename sent_to_accountant "Sent to bookkeeper"
invoice-radar attributes delete sent_to_accountant --yes

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

CommandWhat it does
statusChecks whether the desktop app is connected and shows the current organization.
openOpens the desktop app. --wait waits until the CLI connection is ready.
org listLists organizations.
docs importImports a local PDF invoice.
docs searchSearches saved, unsorted, or deleted documents.
docs showShows document metadata or extracted PDF text.
docs deleteMoves documents to the trash, or deletes them permanently.
docs restoreRestores documents from the trash.
docs exportExports one invoice PDF to a file.
docs syncSyncs invoices to an export destination.
integrations listLists connected integrations. --archived and --all include archived ones.
integrations availableSearches available local and remote integrations.
integrations addAdds a connected integration.
integrations showShows one connected integration.
integrations removeRemoves one connected integration.
integrations archiveArchives one connected integration. Its documents stay.
integrations restoreRestores an archived integration.
integrations autofill fieldsShows available autofill fields.
integrations autofill setStores one autofill value from stdin.
integrations config getShows saved integration config with secrets redacted.
integrations config describeShows config and autofill fields.
integrations config setSets config from key/value args, JSON stdin, or one raw stdin value.
integrations dev currentShows the active local plugin folder.
integrations dev useUses a folder for local plugin development.
integrations dev clearClears the local plugin folder.
runRuns an integration.
stopStops a running integration.
debug listLists running or paused integrations.
debug statusShows running debug status.
debug continueContinues from a breakpoint.
debug stateShows run state summary.
debug step-stateShows saved state for one step.
debug screenshotSaves a screenshot of the running browser.
debug get-htmlPrints HTML from the running browser.
debug run-jsRuns JavaScript in the running browser.
debug networkShows captured network requests.