# Bkper CLI Agent

The Bkper CLI includes a built-in terminal AI agent. Use it when you want an agent to work with local files, shell commands, scripts, tests, and Bkper CLI context in the same local environment.

This is Bkper's recommended starting point for local AI-assisted development. The canonical install, authentication, and command reference lives at [Bkper CLI](https://bkper.com/apps/bkper-cli.md).

## Use it when

- You want an agent to inspect local project files or `AGENTS.md`.
- You need shell commands, pipes, scripts, tests, or exported CSVs.
- You are building a repeatable report, import, cleanup, or integration.
- You want deterministic checks instead of raw AI answers for financial outputs.

For conversational connector access without terminal commands, use [Bkper MCP](https://bkper.com/docs/ai/bkper-mcp-server.md). For the full decision guide, see [CLI vs MCP](https://bkper.com/docs/ai/cli-vs-mcp.md).

## Install on Windows with WSL

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

1. **Install WSL**

    Open **PowerShell as Administrator** and run:

    ```powershell
    wsl --install
    ```

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

    Reference: [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install).

2. **Install Node.js**

    In the **Ubuntu terminal**, run:

    ```bash
    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](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl).

3. **Install and open Bkper**

    Still in the **Ubuntu terminal**, run:

    ```bash
    npm i -g bkper
    bkper
    ```

    If the Bkper Agent opens, the installation is working.

    Reference: [Bkper CLI](https://bkper.com/apps/bkper-cli.md).

## Quick start

1. **Authenticate with Bkper**

    ```bash
    bkper auth login
    ```

    This authenticates the CLI Agent with the preconfigured Bkper AI provider. You can instead start the agent first and use `/login`; both flows share the same local credentials and identify the authenticated account by email. See [Bkper AI Provider](https://bkper.com/docs/ai/bkper-ai-provider.md) for the client-agnostic inference interface and [Models and Usage](https://bkper.com/docs/ai/models.md) for the current portfolio, provider capabilities, rates, and allowance policy.

2. **Start the terminal agent**

    ```bash
    bkper
    ```

    or:

    ```bash
    bkper agent
    ```

3. **Optionally connect another model provider**

    Type `/connect` to choose an external subscription or API-key provider. Use `/connect <provider>` to target one directly, such as `/connect openai` or `/connect anthropic`.

[Image: Bkper CLI Agent terminal interface showing the Bkper ASCII art header, command shortcuts, context, and an active input prompt]

## Why we recommend it

The Bkper CLI Agent is powered by [Pi Agent](https://pi.dev) with Bkper context built in: core concepts, SDK references, CLI commands, and the from-to accounting model.

We chose Pi because it is:

- **Token efficient** — lean context and tool loading for longer, cheaper sessions.
- **Well implemented** — a small, reliable core instead of a heavy black box.
- **Open source** — inspectable, extensible, and easier to improve.
- **Provider agnostic** — 15+ model providers, local models, and no vendor bias.
- **Bundled with Bkper** — one install gives you the agent plus Bkper domain context.

## Model providers

The Bkper CLI Agent ships with Bkper AI already configured, so no separate model-provider setup is required. Bkper authentication supplies the same access token accepted by the client-agnostic inference provider. See [Bkper AI Provider](https://bkper.com/docs/ai/bkper-ai-provider.md) to connect another compatible client. See [Models and Usage](https://bkper.com/docs/ai/models.md) for current rates, provider capabilities, and allowance rules.

The Bkper CLI applies its own operation profile to included models:

| CLI setting                             | Value          |
| --------------------------------------- | -------------- |
| Managed context window (GPT-5.6 models) | 272,000 tokens |
| Managed context window (Grok 4.5)       | 200,000 tokens |
| Maximum output                          | 32,000 tokens  |
| Luna, Terra, and Grok startup reasoning | High           |
| Sol startup reasoning                   | Medium         |

These are Bkper CLI client settings, not server-enforced Bkper AI limits. Other Open Responses clients can choose their own lower budgets and any provider-supported reasoning effort.

To use another provider, type `/connect` and choose a subscription or API key. External provider costs and terms are governed by that provider. We recommend [OpenCode Go](https://opencode.ai/go) for low-cost open-weight models. For external frontier model access, use a [Codex subscription](https://developers.openai.com/codex/pricing) — one of the most affordable ways to use frontier models in coding agents.

The authentication commands have distinct roles:

- `/login` and `/logout` manage Bkper authentication.
- `/connect [provider]` and `/disconnect [provider]` manage external model providers.

Once authenticated, you're in an interactive session. The agent can read your project files, run CLI commands, write code, and iterate with you — all with Bkper context already loaded.

## Built-in safety

The Bkper CLI Agent is configured to work in reviewable steps: inspect context, explain plans, show commands for Bkper writes, and wait for confirmation before mutating data. You still approve changes and review financial outputs.

## Starter prompts

```text
Explain the account types in this Bkper book and list anything that looks unusual.
```

```text
Find possible duplicate transactions from last month. Do not modify anything; show me the query and reasoning first.
```

```text
Write a script that exports a monthly profit and loss report from Bkper balances. Keep the calculation deterministic and add a simple test fixture.
```

```text
Review unchecked transactions from this month and suggest what needs attention. Do not post, check, or edit transactions.
```

```text
Prepare an exploratory tax worksheet for 2025 from my Bkper data. Use Bkper as the source of truth and mark assumptions explicitly.
```

## Watch walkthroughs

Optional walkthroughs:

- [Bkper CLI Agent walkthrough](https://www.youtube.com/watch?v=gFkOZjfEOf8)
- [Bkper CLI Agent workflow example](https://www.youtube.com/watch?v=0fSyYdwwR_I)
- [Lucas Meijer on Pi's minimal, hackable design philosophy](https://www.youtube.com/watch?v=fdbXNWkpPMY)
- [Pi Agent overview and capabilities](https://www.youtube.com/watch?v=Dli5slNaJu0)
- [Pi architecture explained: agent loop, tools, TUI, and more](https://www.youtube.com/watch?v=gTeujlv8qK0)

## Security

The agent runs with your local workspace access and the Bkper permissions of the account used by `bkper auth login`. Before using it with real data, read [Bkper CLI Agent Security](https://bkper.com/docs/ai/cli-agent-security.md).

## Reference

Use [Bkper CLI](https://bkper.com/apps/bkper-cli.md) for canonical installation, authentication, CLI command reference, and current agent behavior.