# 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. For installation, authentication, and the command reference, see [Bkper CLI](http://preview.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](http://preview.bkper.com/docs/ai/bkper-mcp-server.md). For the full decision guide, see [CLI vs MCP](http://preview.bkper.com/docs/ai/cli-vs-mcp.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](http://preview.bkper.com/docs/ai/bkper-ai-provider.md) for the client-agnostic inference interface and [Models and Usage](http://preview.bkper.com/docs/ai/models.md) for the current portfolio, model 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`.

## 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](http://preview.bkper.com/apps/bkper-cli.md).

[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

Bkper AI is already configured, so no separate model-provider setup is required. The CLI loads the current catalog and default from `GET /v1/models`; an explicitly saved model remains selected while it is available. See [Models and Usage](http://preview.bkper.com/docs/ai/models.md) for the current portfolio, capabilities, rates, and allowance rules.

To use an external subscription or API key instead, type `/connect` and choose a provider. External costs, limits, and privacy terms are governed by that provider.

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

## 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](http://preview.bkper.com/docs/ai/cli-agent-security.md).

## Reference

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