A unified interface for Bkper. Use bkper in two complementary ways:

• Ask the Bkper 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, built-in agent, or external AI tools — managing financial data, building apps, and automating workflows.

Install & Authenticate

Prerequisites

• Node.js >= 22.19.0
• Windows: install with WSL — the agent relies on Linux tooling that doesn't work reliably in PowerShell

Install (choose one)

npm i -g bkper

bun add -g bkper

pnpm add -g bkper

yarn global add bkper

Install on Windows with WSL

Run Bkper inside WSL rather than PowerShell. If WSL is not set up yet:

1. Open PowerShell as Administrator and install WSL:

   wsl --install

   Restart Windows if prompted, then open Ubuntu from the Start menu and create your Linux username and password.

   Reference: Install WSL.

2. In the Ubuntu terminal, install Node.js:

   sudo apt update
   sudo apt install -y curl
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
   source ~/.bashrc
   nvm install --lts

   Reference: Set up Node.js on WSL.

3. Still in the Ubuntu terminal, install and open Bkper:

   npm i -g bkper
   bkper

If the Bkper Agent opens, the installation is working.

Authenticate with Bkper

bkper auth login

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

Get started

Ask the Bkper Agent

bkper

Run bkper to open the built-in Bkper Agent in your terminal.

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 with Codex works very well. Claude subscriptions are also supported if Claude is your preferred frontier model. For open-weights models, OpenCode Go is a great option.

Safe starting prompts:

Help me setup a chart of accounts for my business

Find possible duplicate transactions from last month

Review unchecked transactions from this month and suggest what needs attention

Show me a balance sheet for my book for last year

Show me profit and loss for my book for last month

Prepare an exploratory tax worksheet for 2025

Run CLI commands

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

# 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:

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

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

→ See Data Management and App Management below for full references.

Use Bkper from your existing agent

Install and authenticate the CLI first:

bkper auth login

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

codex plugin marketplace add bkper/bkper-cli

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

/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:

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 instead.

Advanced agent options

bkper agent starts the same built-in agent experience as bkper.

Advanced users can pass supported agent-runtime flags through:

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.

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. The new session is linked to the original, with the relevant context drafted in the input editor for you to adjust or submit.

Auto-handoff is enabled by default and offers a handoff shortly before context compaction. Auto-handoff and Auto-compact are independent and can each be turned on or off from /settings.

Data Management

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

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

App Management

Build, deploy, and manage Bkper apps.

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

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:

# 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 library:

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

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

Next steps

• Developer Docs — full platform documentation
• App Template — scaffold a Bkper app in minutes
• Full CLI reference — data management, app building, taxes, and financial statements