# Bkper CLI

The official Bkper CLI is published on npm as [`bkper`](https://www.npmjs.com/package/bkper). It is the command-line interface for everything you build on Bkper and serves two roles:

- **Data management** — Work with books, accounts, transactions, and balances from the terminal
- **App development** — Initialize, clone, develop, build, sync, and deploy Bkper apps

> **Tip: Want your assistant to handle setup?**
> Use [Bkper with your AI assistant](https://preview.bkper.com/docs/ai/assistants.md) for a copyable setup prompt and outcome-based examples. Continue here when you want the command reference or manual installation.
## Installation

```bash npm install -g bkper ```

Or run it without a global installation:

```bash
npx bkper
```

The package and executable are both named `bkper`.

## Authentication

```bash
bkper auth login   # authenticate via Google OAuth
bkper auth logout  # revoke the stored refresh token and clear local credentials
bkper auth token   # print the current access token (requires prior login)
```

`bkper auth login` authenticates via Google OAuth and stores credentials locally. Keep the command running while you complete browser authorization, and wait for it to finish successfully before running other Bkper commands. The same credentials are used by:

- All CLI commands
- The `getOAuthToken()` function in scripts
- The `bkper app dev` local development server

`bkper auth token` is useful for direct API calls — pipe the output into a variable:

```bash
TOKEN=$(bkper auth token)
```

### App lifecycle

```bash
# Create a new app from the template
bkper app init my-app
cd my-app

# Or clone an existing Bkper-managed app source repository
bkper app clone <appId>

# Start worker runtime (Miniflare + tunnel + file watching)
bkper app dev

# Build the server Worker bundle
bkper app build

# Sync app metadata and, for managed apps, committed source
bkper app sync

# Deploy to the Bkper Platform
bkper app deploy

# Remove app from the Bkper Platform
bkper app undeploy

# Check deployment status
bkper app status
```

> **Note:** The project template composes the full workflow via `npm run dev` (runs Vite + `bkper app dev` concurrently) and `npm run build` (runs `vite build` + `bkper app build`). Use the template scripts for the complete development experience.

`bkper app clone` is available to authorized developers of apps with Bkper-managed source. Clone external-source apps from their Git provider instead.

Source synchronization and deployment are separate. Neither `git push` nor `bkper app sync` deploys an app. `bkper app deploy` uploads an existing local build and does not run the build itself.

See [Shared App Source](/docs/platform/apps/shared-app-source) for the managed-source collaboration workflow and eligibility rules.

### Secrets management

```bash
# Set a secret for production
bkper app secrets put EXTERNAL_SERVICE_TOKEN

# Set a secret for preview environment
bkper app secrets put EXTERNAL_SERVICE_TOKEN --preview

# List secrets
bkper app secrets list

# Delete a secret
bkper app secrets delete EXTERNAL_SERVICE_TOKEN
```

### App installation

```bash
# Install app on a book
bkper app install <appId> -b <bookId>

# Uninstall app from a book
bkper app uninstall <appId> -b <bookId>
```

### Authenticating scripts and local development

For Node.js scripts, automations, and local app development, use the CLI's stored credentials via `getOAuthToken()`:

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

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

This is the canonical pattern. The CLI handles the OAuth flow, token storage, and refresh. Do not implement custom OAuth for scripts.

## Data management commands

The CLI provides full data management capabilities:

```bash
# Books
bkper book list
bkper book get <bookId>
bkper book create --name "My Company"

# Accounts
bkper account list -b <bookId>
bkper account create -b <bookId> --name "Sales" --type INCOMING

# Transactions
bkper transaction list -b <bookId> -q "account:Sales after:2025-01-01"
bkper transaction create -b <bookId> --description "Office supplies 123.78"

# Balances
bkper balance list -b <bookId> -q "on:2025-12-31"
```

All data commands use `-b, --book <bookId>` to specify the book context.

## Query semantics (transactions and balances)

Use the same query language across Bkper web app, CLI, and Google Sheets integrations.

- `on:` supports different granularities:
    - `on:2025` → full year
    - `on:2025-01` → full month
    - `on:2025-01-31` → specific day
- `after:` is **inclusive** and `before:` is **exclusive**.
    - Full year 2025: `after:2025-01-01 before:2026-01-01`
- For point-in-time statements (typically permanent accounts: `ASSET`, `LIABILITY`), prefer `on:` or `before:`.
- For activity statements over a period (typically non-permanent accounts: `INCOMING`, `OUTGOING`), prefer `after:` + `before:`.
- For statement-level analysis, prefer report root groups (for example `group:'Balance Sheet'` or `group:'Profit & Loss'`) over isolated child groups.

```bash
# Transactions in full year 2025
bkper transaction list -b <bookId> -q "on:2025"

# Transactions in January 2025
bkper transaction list -b <bookId> -q "on:2025-01"

# Balance Sheet snapshot (point-in-time)
bkper balance list -b <bookId> -q "group:'Balance Sheet' before:2026-01-01"

# P&L activity over 2025
bkper balance list -b <bookId> -q "group:'Profit & Loss' after:2025-01-01 before:2026-01-01"
```

## Output format

All data commands output JSON, ready for scripts and AI agents. Reshape it with [jq](https://jqlang.github.io/jq/) instead of output flags:

```bash
# Lists use an {"items":[...]} envelope
bkper book list | jq '.items[].name'

# Export transactions to CSV
bkper transaction list -b <bookId> -q "on:2025-01" | \
  jq -r '.items[] | [.date, .amount, .creditAccount.name, .debitAccount.name, .description] | @csv'
```

Table and CSV output formats were removed in CLI v5. `--json` and `--format json` are still accepted and have no effect.

See [CLI Scripting & Piping](/docs/platform/scripts/cli-pipelines) for output shapes and scripting patterns.

## Full reference

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

The complete CLI documentation, including all commands and options, is available on the [bkper-cli app page](/apps/bkper-cli).