> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dualentry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# DualEntry CLI Reference
> Full DualEntry CLI reference: every resource, subcommand, flag, exit code, environment variable, and config file option, with syntax examples for each command.
Use this page as a scannable reference for the DualEntry CLI. For getting started, see the [Quickstart Guide](/developers/guides/cli/quickstart).
## Global options
The flags below apply to every CLI invocation, regardless of subcommand.
| Flag | Description |
| ---------------------- | -------------------------------------------------------------------- |
| `--version`, `-v` | Print the CLI version and exit |
| `--help` | Show help for any command or subcommand |
| `--install-completion` | Install shell tab completion |
| `--show-completion` | Print the shell completion script instead of installing it |
| `--retry` | Retry transient errors (429, 502, 503, 504) with exponential backoff |
`dualentry --help` is the fastest way to see all available commands. You can also run `dualentry [resource] --help` for help on a specific resource.
## Authentication commands
The authentication commands manage how the CLI connects to your DualEntry account.
| Command | Description |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `dualentry auth login` | Opens your browser for OAuth login. Credentials are stored in your system keychain. |
| `dualentry auth logout` | Clears the stored credentials. |
| `dualentry auth status` | Shows whether you are currently authenticated. |
| `dualentry health` | Checks that the CLI can reach the API. |
Login runs the OAuth flow against `/public/v2/oauth/authorize/` and `/public/v2/oauth/token/`, then stores the resulting API key in your system keychain. On a machine with no usable keychain, the CLI falls back to a file, so treat that file as a credential if you are working on a shared host.
For CI/CD or headless environments, set the `X_API_KEY` environment variable instead. See [Configuration](#configuration) below.
## Resource commands
The Resource commands section lists all CLI resources grouped by domain.
### Standard subcommands
Most resources support these subcommands:
| Subcommand | What it does |
| ---------- | --------------------------------------------------------------- |
| `list` | Show all records for this resource (paginated table by default) |
| `get` | Retrieve a single record |
| `create` | Create a new record |
| `update` | Update an existing record |
Run `dualentry [resource] --help` to see the exact flags and required arguments for each subcommand; they vary by resource.
### Creating and updating records
`create` and `update` both read the record body from a JSON file; there is no way to pass fields directly as flags:
```bash theme={null}
dualentry invoices create --file invoice.json
dualentry invoices update 135934 --file invoice.json
```
Unlike `get`, `update` does not strip a display prefix like `IN-` from its record-ID argument; pass the bare number or ID `get` shows you, not the prefixed one.
| Flag | Short | Description |
| ------------- | ----- | ------------------------------------------ |
| `--file PATH` | `-f` | Required. JSON file with the record's data |
### Read-only resources
Several resources are read-only or non-editable and drop `create` and/or `update`: `accounts`, `companies`, `budgets`, `paper-checks`, `depreciation-books`, and `workflows` support only `list` and `get`. `inbox` is more restricted still, supporting only `list`, with no `get`.
### Looking up records by number or ID
On resources that carry a record number, `get` accepts either a number or an ID and works out which you gave it. Two explicit forms are available when you want to be unambiguous:
| Subcommand | What it does |
| ------------ | ------------------------- |
| `get-number` | Retrieve by record number |
| `get-id` | Retrieve by internal ID |
### Resource-specific subcommands
A few subcommands are resource-specific rather than universal:
| Subcommand | Available on |
| ---------- | ----------------------------------------------------------------- |
| `delete` | The three `recurring` resources: invoices, bills, journal entries |
| `validate` | `intercompany-journal-entries` |
| `post` | `intercompany-journal-entries` |
| `template` | `intercompany-journal-entries` |
`delete` is real on recurring records and removes the schedule. It is not available on posted transactions, so do not assume the absence of a delete command elsewhere protects a recurring template.
### Intercompany journal entry helpers
`intercompany-journal-entries validate` checks a JSON file offline (line items present, debits equal credits, at least two companies) unless you pass `--online`, which also confirms every `company_id` in the file is one you can access:
```bash theme={null}
dualentry intercompany-journal-entries validate --file ije.json --online
```
`intercompany-journal-entries template` writes a sample payload to stdout, or to a file with `--output`/`-o`.
### Receivables
| Command | Description |
| -------------------------------------------- | --------------------------------------- |
| `dualentry invoices` | Manage invoices |
| `dualentry sales-orders` | Manage sales orders |
| `dualentry customer-payments` | Manage customer payments |
| `dualentry customer-credits` | Manage customer credits |
| `dualentry customer-prepayments` | Manage customer prepayments |
| `dualentry customer-prepayment-applications` | Manage customer prepayment applications |
| `dualentry customer-deposits` | Manage customer deposits |
| `dualentry customer-refunds` | Manage customer refunds |
| `dualentry cash-sales` | Manage cash sales |
### Payables
| Command | Description |
| ------------------------------------------ | ------------------------------------- |
| `dualentry bills` | Manage bills |
| `dualentry purchase-orders` | Manage purchase orders |
| `dualentry vendor-payments` | Manage vendor payments |
| `dualentry vendor-credits` | Manage vendor credits |
| `dualentry vendor-prepayments` | Manage vendor prepayments |
| `dualentry vendor-prepayment-applications` | Manage vendor prepayment applications |
| `dualentry vendor-refunds` | Manage vendor refunds |
| `dualentry direct-expenses` | Manage direct expenses |
### Accounting
| Command | Description |
| ---------------------------------------- | ---------------------------------------------------------------------------- |
| `dualentry journal-entries` | Manage journal entries |
| `dualentry intercompany-journal-entries` | Manage intercompany journal entries; adds `validate`, `post`, and `template` |
| `dualentry bank-transfers` | Manage bank transfers |
| `dualentry fixed-assets` | Manage fixed assets |
| `dualentry depreciation-books` | Manage depreciation books |
| `dualentry paper-checks` | Manage paper checks |
| `dualentry inbox` | Manage inbox records |
### Master data
| Command | Description |
| --------------------------- | ------------------------ |
| `dualentry customers` | Manage customers |
| `dualentry vendors` | Manage vendors |
| `dualentry items` | Manage items |
| `dualentry accounts` | Manage chart of accounts |
| `dualentry companies` | Manage companies |
| `dualentry classifications` | Manage classifications |
### Automation
| Command | Description |
| --------------------- | ------------------------------------------------ |
| `dualentry recurring` | Manage recurring records (invoices, bills, etc.) |
| `dualentry contracts` | Manage contracts |
| `dualentry budgets` | Manage budgets |
| `dualentry workflows` | Manage workflows |
### Bank matching
`dualentry bank-match` doesn't follow the `list`/`get`/`create`/`update` shape above. It has its own subcommands for reconciling bank-feed rows against DualEntry transactions.
| Command | Description |
| --------------------------------------------- | ------------------------------------------------------------------- |
| `dualentry bank-match status-counts` | Show how many bank rows sit in each pipeline stage |
| `dualentry bank-match bank-transactions list` | List bank-feed transactions |
| `dualentry bank-match bank-transactions get` | Get one bank-feed transaction by ID |
| `dualentry bank-match suggestions list` | List suggested matches for bank-feed rows |
| `dualentry bank-match suggestions get` | Get one suggestion by ID |
| `dualentry bank-match match` | Confirm a match between a bank-feed row and a DualEntry transaction |
| `dualentry bank-match unmatch` | Undo a confirmed match |
| `dualentry bank-match template` | Output a sample match JSON payload |
`bank-transactions list` accepts `--financial-account-id`, `--matching-status`, `--date-from`, `--date-to`, `--is-posted`/`--not-posted`, and `--include-expired`, plus the standard `--limit`/`--offset`/`--all`. `suggestions list` accepts `--financial-transaction-id`, `--suggestion-type` (`match` or `create`), and `--highest-ranked`.
`match` confirms a 1:1 or partial match with `--financial-transaction-id` plus exactly one of `--transaction-id` or `--entry-id`, or a full 1:1/M:N body via `--file`/`-f` (these are mutually exclusive). `unmatch` takes exactly one of `--financial-transaction-id` or `--match-group-id`; unmatching any member dissolves the whole group. `template` writes to stdout or `--output`/`-o`, and accepts `--type`/`-t` (`1:1`, `m:n`, or `partial`).
```bash theme={null}
dualentry bank-match bank-transactions list --matching-status unprocessed
dualentry bank-match match --financial-transaction-id 42 --transaction-id 100
dualentry bank-match unmatch --match-group-id 7
```
## Common flags
The flags below work across multiple resource commands and control output format, pagination, and filtering.
### Output format
The output format flag toggles between human-readable tables and machine-readable JSON.
| Flag | Description |
| --------------- | -------------------------------------------------- |
| `--format json` | Output as JSON instead of the default table format |
* **Table format** (default): a human-readable, column-aligned table rendered with Rich. Best for quick lookups in the terminal.
* **JSON format**: raw JSON output. Best for scripting, piping to `jq`, or feeding into other tools.
The example below shows both output modes for the same command:
```bash theme={null}
# Table output (default)
dualentry invoices list
# JSON output
dualentry invoices list --format json
```
### Pagination
Three flags control how much a `list` command returns.
| Flag | Short | Description |
| ------------ | ----- | ----------------------------------------------- |
| `--limit N` | `-l` | Number of records per page |
| `--offset N` | | Skip this many records before returning results |
| `--all` | `-a` | Fetch every page instead of just the first |
By default, `list` commands return one page. Use `--all` when you need the complete dataset:
```bash theme={null}
dualentry invoices list --all
```
`--limit` and `--offset` page through a fixed range in a single request. `--all` fetches every page automatically, issuing one request per page, which is slower than a single page on a large resource.
### Filtering
Four filters are available on most `list` commands, though a few resources with hand-rolled `list` commands (for example `accounts`) only support `--search`, and `depreciation-books list` supports none of them:
| Flag | Short | Description |
| ------------------------- | ----- | ---------------------------------------------------------- |
| `--search TEXT` | `-s` | Free-text search across the resource |
| `--status STATUS` | | Filter by record status (for example `posted`, `archived`) |
| `--start-date YYYY-MM-DD` | | Filter records on or after this date |
| `--end-date YYYY-MM-DD` | | Filter records on or before this date |
Three more are entity filters, and these do vary by resource, because a resource only exposes the ones that make sense for it:
| Flag | Short | Available on |
| --------------- | ----- | -------------------------------------------------------------------------------------- |
| `--company ID` | `-c` | Most resources |
| `--customer ID` | | Receivables resources, plus journal entries, fixed assets, paper checks, and contracts |
| `--vendor ID` | | Payables resources, plus journal entries, fixed assets, and paper checks |
Run `dualentry [resource] list --help` to see which entity filters a specific resource accepts.
```bash theme={null}
dualentry journal-entries list --start-date 2026-03-01 --end-date 2026-03-31
dualentry bills list --status posted
```
## Configuration
The configuration commands and environment variables below control how the CLI connects to DualEntry.
### Viewing config
Display your current configuration, including API URL and auth state, with the following command:
```bash theme={null}
dualentry config show
```
### Setting a custom API URL
`config set-url` persists a custom API base URL to your config file (`~/.dualentry/config.toml`), as an alternative to setting `DUALENTRY_API_URL` every session. Every organization, sandbox or production, is reached at the same `https://api.dualentry.com` by default; which one you're working against depends on the API key you authenticate with, not the URL (see [Authentication](/developers/guides/api/authentication)). `config set-url` exists as an escape hatch for pointing the CLI at a different host entirely:
```bash theme={null}
dualentry config set-url https://your-custom-host.example.com
```
A `DUALENTRY_API_URL` environment variable, when set, overrides whatever this stores.
### Environment variables
Set the variables below to override default CLI behavior, primarily for CI/CD or non-production environments.
| Variable | Description | Default |
| ------------------- | -------------------------------------------------------------------- | --------------------------- |
| `X_API_KEY` | API key for authentication. Skips OAuth when set. Use this in CI/CD. | (none) |
| `DUALENTRY_API_URL` | Override the API base URL. | `https://api.dualentry.com` |
```bash theme={null}
# Use an API key instead of OAuth
export X_API_KEY="your-api-key-here"
```
## Exit codes
The CLI returns `0` on success and `1` on any error, including a failed request, a missing argument, or an authentication failure. Check the process exit code in scripts rather than parsing output.
## Example output
The columns below appear in the table output of `dualentry invoices list`: record ID, document number, dates, company, counterparty, currency, financial amounts, and status. Other resources follow a similar table layout with columns relevant to that record type.
```text theme={null}
ID # Date Company Customer Due Date Currency Amount Paid Due Status
─── ──── ────────── ────────── ───────────── ────────── ──────── ──────── ────── ──────── ────────
12 INV-1 2026-01-15 Acme Corp Widget Co. 2026-02-14 USD 1,500.00 0.00 1,500.00 posted
15 INV-2 2026-02-01 Acme Corp Sprocket Inc. 2026-03-03 USD 3,200.00 3,200 0.00 archived
```
## Known limitations
The CLI is early-stage software. The current limitations are:
* **Early version**: the CLI is at `v0.1.18` at the time of writing; expect evolving commands and occasional rough edges.
* **Delete is limited to recurring records**: no other resource supports `delete`, and several (see [Resource commands](#resource-commands)) don't even support `create` or `update`.
* **Performance**: some operations may be slow, especially on large datasets.
* **Python 3.11+ required**: Homebrew handles this automatically; other install methods require you to have Python 3.11+ already installed.