> ## 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.
# Quickstart: DualEntry CLI
> Install the DualEntry CLI, authenticate via OAuth, and run your first command in under five minutes. Covers Homebrew, uv, and CI/CD setup.
Use this guide to install the DualEntry CLI, authenticate, and run your first command in under five minutes. For the full list of resources and flags, see the [Command Reference](./cli-reference). For end-to-end task walkthroughs, see [Common Workflows](./cli-common-workflows).
## Prerequisites
Before you install the CLI, confirm you meet the two requirements below.
* **Python 3.11+** - the CLI is written in Python and requires version 3.11 or later. Homebrew installs Python automatically; for `uv` and the install script, run `python3 --version` to confirm your local version is high enough.
* **A DualEntry account** - you'll authenticate via browser-based OAuth during setup, so an active DualEntry login is required. Contact your administrator if you don't yet have one.
## Install the CLI
Pick the install method that fits your setup. Homebrew is the simplest path for most users because it manages the Python dependency for you.
### Option 1: Homebrew (recommended)
Install the CLI and its Python dependency in a single command:
```bash theme={null}
brew install dualentry/tap/dualentry
```
### Option 2: uv
If you use `uv` for Python tooling, install directly from the GitHub repository:
```bash theme={null}
uv tool install git+https://github.com/dualentry/dualentry-cli.git
```
### Option 3: Install script
Run the official install script to download and install the CLI in one step:
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/dualentry/dualentry-cli/main/install.sh | sh
```
Options 2 and 3 require Python 3.11+ to be installed on your system already.
## Enable tab completion
Tab completion makes the CLI faster to use by auto-completing resources and flags as you type. Run this once after installing:
```bash theme={null}
dualentry --install-completion
```
Restart your shell (or open a new terminal window) for completion to take effect.
## Authenticate
Log in to connect the CLI to your DualEntry account:
```bash theme={null}
dualentry auth login
```
This opens your default browser to a DualEntry OAuth page. Sign in, approve the access request, and you're done. Your credentials are stored securely in your system keychain - you won't need to log in again on this machine unless your session expires.
To verify you're authenticated, run `dualentry companies list`. If you see your company data, you're all set.
**macOS users:** The first time you run a command after logging in, macOS will show a Keychain Access prompt asking whether Python can access your `dualentry-cli` credentials. This is normal - the CLI uses your system keychain to store OAuth tokens securely. Enter your Mac login password and click **"Always Allow"** so you don't see the prompt on every command. Clicking "Allow" works too, but you'll be asked again next time.
## Run your first command
Pull a list of invoices to confirm the CLI is connected to your account:
```bash theme={null}
dualentry invoices list
```
You'll see a formatted table like the one below.
| 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 | 1,500.00 | posted |
| 15 | INV-2 | 2026-02-01 | Acme Corp | Sprocket Inc. | 2026-03-03 | USD | 3,200.00 | 3,200.00 | 0 | archived |
Each row is an invoice in your DualEntry account. The columns show the invoice number, dates, customer, amounts, and current status (`posted`, `archived`, etc.). This is the same data you'd see in the DualEntry web app, just in your terminal.
## Quick next steps
Once you've run your first command, try the actions below to explore the CLI.
Get JSON output, useful for piping into other tools or scripts:
```bash theme={null}
dualentry invoices list --format json
```
Explore other resources - the CLI covers invoices, bills, journal entries, customers, vendors, and more. The [Command Reference](./cli-reference) lists every available resource:
```bash theme={null}
dualentry bills list
dualentry customers list
dualentry journal-entries list
```
Check help for any resource - every resource command has its own help page showing available flags and subcommands:
```bash theme={null}
dualentry invoices --help
dualentry journal-entries --help
```
See all available commands at the top level:
```bash theme={null}
dualentry --help
```
For multi-step task walkthroughs (month-end review, CI/CD automation), see [Common Workflows](./cli-common-workflows).
## For CI/CD environments
In automated pipelines like GitHub Actions or Jenkins, browser-based OAuth isn't possible. Set the `X_API_KEY` environment variable instead of running `dualentry auth login`:
```bash theme={null}
export X_API_KEY="your-api-key-here"
dualentry invoices list --format json
```
The CLI uses the API key automatically and skips the OAuth flow. Store the key in your CI/CD platform's secrets manager - don't commit it to source control.
Never commit API keys to source control. Use your CI/CD platform's encrypted secrets manager and reference the key via environment variables.
## Troubleshooting
The issues below cover the most common installation and authentication problems.
* **Command not found after install** - make sure the install location is on your `PATH`. For Homebrew, this is usually automatic. For other methods, check the install output for instructions.
* **Authentication failing** - run `dualentry auth login` again. If your browser doesn't open, check that you have a default browser set.
* **Slow responses** - the CLI is at `v0.1.9`; performance on some operations is still being optimized. Large datasets may take a moment.