[Developer Docs]: https://bkper.com/docs
[CLI Docs]: https://bkper.com/docs/build/tools/cli
[App Template]: https://github.com/bkper/bkper-app-template
[Pi]: https://pi.dev/

The official Bkper CLI is published on npm as [`bkper`](https://www.npmjs.com/package/bkper). Use it in two complementary ways:

-   **Ask Bkper CLI Agent** — run `bkper` for guided, interactive help in your terminal
-   **Run CLI commands** — run `bkper <command>` for scripts, exports, automations, and app workflows

With one tool, you can work with Bkper from your terminal, Bkper CLI Agent, or external AI tools — managing financial data, building apps, and automating workflows.

[![npm](https://img.shields.io/npm/v/bkper?color=%235889e4)](https://www.npmjs.com/package/bkper)

## Install & Authenticate

### Prerequisites

-   [Node.js](https://nodejs.org/) >= 22.19.0
-   Windows, macOS, Linux, or WSL

### Install (choose one)

```bash tab="npm"
npm install -g bkper
```

```bash tab="bun"
bun add -g bkper
```

```bash tab="pnpm"
pnpm add -g bkper
```

```bash tab="yarn"
yarn global add bkper
```

Or run it without a global installation:

```bash
npx bkper
```

The package and executable are both named `bkper`. See the [CLI Docs] for the dedicated command-line guide.

### Install on Windows

After installing Node.js, run Bkper directly from PowerShell:

```powershell
npm install -g bkper
bkper
```

Bkper CLI Agent uses PowerShell natively on Windows. WSL remains supported and uses Bash.

### Authenticate with Bkper

```bash
bkper auth login
```

`bkper auth login` connects the CLI to your Bkper account. The same local authentication can be used by direct CLI commands, Bkper CLI Agent, external coding agents, scripts, and local app development.

---

## Get started

### Ask Bkper CLI Agent

```bash
bkper
```

Run `bkper` to open Bkper CLI Agent in your terminal.

![Bkper CLI Agent TUI](https://raw.githubusercontent.com/bkper/bkper-cli/main/assets/bkper-agent-cli.png)

`bkper auth login` and `/login` inside the agent both connect to your Bkper account and enable the included Bkper AI models. Both flows show which account email is authenticated.

To use another model provider, type `/connect` and choose a subscription or API-key provider. You can also target one directly, such as `/connect openai` or `/connect anthropic`. Use `/disconnect` for external providers; `/logout` signs out of Bkper.

For external frontier models, an existing [ChatGPT Plus/Pro subscription](https://chatgpt.com/pricing/) with Codex works very well. [Claude subscriptions](https://claude.com/pricing) are also supported if Claude is your preferred frontier model. For open-weights models, [OpenCode Go](https://opencode.ai/go) is a great option.

### Safe starting prompts:

```text
Help me setup a chart of accounts for my business
```

```text
Find possible duplicate transactions from last month
```

```text
Review unchecked transactions from this month and suggest what needs attention
```

```text
Show me a balance sheet for my book for last year
```

```text
Show me profit and loss for my book for last month
```

```text
Prepare an exploratory tax worksheet for 2025
```

### Run CLI commands

Use direct commands for scripts, exports, automation, and repeatable workflows.

```bash
# List your books
bkper book list

# Query transactions
bkper transaction list -b <bookId> -q 'on:2026-06' --format csv

# Query balances
bkper balance list -b <bookId> -q 'on:2026-06-30'
```

Capture a receipt as a draft, then review and complete it in Bkper or with the agent:

```bash
bkper transaction create -b <bookId> --file ./receipt.pdf
```

For AI-derived transactions, set `draft: true` to bypass Book auto-posting. They stay out of balances until explicitly posted:

```bash
printf '%s\n' '[{"date":"2026-08-18","amount":"25.50","creditAccount":{"name":"Bank Account"},"debitAccount":{"name":"Meals"},"description":"Extracted receipt","draft":true}]' |
    bkper transaction create -b <bookId>
```

> Run `bkper --help` or `bkper <command> --help` for built-in documentation on any command.

→ See [Data Management](#data-management) and [App Management](#app-management) below for full references.

---

## Use Bkper from your existing agent

For assistant-led setup, follow [Use Bkper with ChatGPT or Claude](https://bkper.com/docs/ai/chatgpt-and-claude).

To configure an existing agent manually, authenticate the CLI first:

```bash
bkper auth login
```

For Codex, add this repository as a plugin marketplace, then install the `bkper-cli` plugin from Codex's plugin directory:

```bash
codex plugin marketplace add bkper/bkper-cli
```

For Claude Code, install the Bkper CLI plugin from this repository's Claude marketplace:

```text
/plugin marketplace add bkper/bkper-cli
/plugin install bkper-cli@bkper
```

For other coding agents — OpenCode, OpenClaw, Hermes Agent, Cursor, or similar tools — install the Bkper CLI skill in that agent environment:

```bash
npx skills add bkper/bkper-cli --skill bkper-cli
```

The plugins and skill help external agents use the local `bkper` CLI with Bkper context, CLI references, and safety guidance.

For general Bkper Q&A without local tool access, use the published docs and [`llms.txt`](https://bkper.com/llms.txt) instead.

---

## Advanced agent options

`bkper agent` starts the same Bkper CLI Agent experience as `bkper`.

Advanced users can pass supported agent-runtime flags through:

```bash
bkper agent <args>
bkper agent --help
```

`bkper agent` keeps Bkper defaults, including the Bkper system prompt, unless you explicitly override them. For the underlying agent runtime reference, see [Pi][Pi].

When the selected model cannot read images, the agent briefly uses Bkper's default model to transcribe attached or opened images, then continues with the selected model; a status message is shown while this happens.

Use `/handoff <goal>` to continue long-running work in a new focused session. If you omit the goal, the agent opens an empty goal editor. Pressing `Ctrl+H` opens that editor with your current input text as the goal. The new session is linked to the original, with the relevant context drafted in the input editor for you to adjust or submit.

Press `Ctrl+R` in the standard or handoff input to fuzzy-search recently submitted inputs. Search history starts with inputs submitted after this feature is installed; it does not scan existing sessions. The handoff search omits Bash commands. Press `Ctrl+Alt+R` to open the session tree.

---

## Data Management

Manage books, files, accounts, transactions, events, and balances.

```bash
bkper book list
bkper account list -b <bookId>
bkper file list -b <bookId> --limit 100
bkper transaction list -b <bookId> -q 'on:2026' --format csv
bkper event list -b <bookId> --error --json
bkper balance list -b <bookId> -q 'on:2026-12-31' --format csv
```

→ [Full Data Management reference](https://github.com/bkper/bkper-cli/blob/main/skill/references/cli/data-management.md)

---

## App Management

Build, deploy, and manage Bkper apps. Sync and deploy require clean, committed source stored in Bkper-managed Git (recommended) or in the current branch's external upstream.

```bash
bkper app init my-app
cd my-app
bkper app get my-app --json
bkper app dev
bkper app sync
bkper app deploy
bkper app logs --last 50
bkper app logs my-app --level error
```

`bkper app logs` reads recent app logs kept for 15 days. Run it inside an app directory, or pass an app id like `bkper app logs my-app`. Use `--level warn` or `--level error` to focus on requests with warnings or errors. The default output is human-readable, and JSON is available with `--json`.

→ [Full App Management reference](https://github.com/bkper/bkper-cli/blob/main/skill/references/cli/app-management.md)

---

## Programmatic access

Use the CLI as the authentication bridge for scripts and direct API calls.

### Access Token

Use the access token for direct API calls from any tool. This requires a prior `bkper auth login`, and `bkper auth token` does not start an interactive login flow:

```bash
# Print the current access token
TOKEN=$(bkper auth token)

# Use it with curl, httpie, or any HTTP client
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.bkper.app/v5/books | jq '.items[].name'
```

### Library

The `getOAuthToken` function returns a Promise that resolves to a valid OAuth token, for use with the [`bkper-js`](https://github.com/bkper/bkper-js) library:

```javascript
import { Bkper } from 'bkper-js';
import { getOAuthToken } from 'bkper';

Bkper.setConfig({
    oauthTokenProvider: async () => getOAuthToken(),
});
```

---

## Next steps

-   [Developer Docs][Developer Docs] — full platform documentation
-   [App Template][App Template] — scaffold a Bkper app in minutes
-   [Full CLI reference](https://github.com/bkper/bkper-cli/tree/main/skill/references) — data management, app building, taxes, and financial statements