CLI

The Bkper CLI is the command-line interface for everything you build on Bkper. It serves two roles:

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

Installation

npm

npm i -g bkper

bun

bun add -g bkper

pnpm

pnpm add -g bkper

yarn

yarn global add bkper

Authentication

bkper auth login   # authenticate via Google OAuth
bkper auth logout  # revoke stored credentials
bkper auth token   # print the current access token

bkper auth login authenticates via Google OAuth and stores credentials locally. 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:

TOKEN=$(bkper auth token)

Developer workflows

App lifecycle

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

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

# Build worker bundles
bkper app build

# Sync app metadata to Bkper
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.

Secrets management

# Set a secret for production
bkper app secrets put BKPER_API_KEY

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

# List secrets
bkper app secrets list

# Delete a secret
bkper app secrets delete BKPER_API_KEY

App installation

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

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

Auth provider for scripts

The CLI package exports getOAuthToken() for use in Node.js scripts:

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

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

Data management commands

The CLI provides full data management capabilities:

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

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

The CLI supports multiple output formats for scripting and piping:

# Table (default, human-readable)
bkper book list

# JSON (for programmatic use)
bkper book list --format json

# CSV (for spreadsheets and data tools)
bkper transaction list -b <bookId> --format csv

See CLI Scripting & Piping for 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.