Skip to content
Bkper
Sign In

CLI

Use the Bkper CLI for data management and app development, including shared-source cloning, local development, builds, metadata sync, deployment, logs, and secrets.

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, clone, develop, build, sync, and deploy Bkper apps

Installation

npm i -g bkper

Authentication

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. 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
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 for the managed-source collaboration workflow and eligibility rules.

Secrets management

# 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

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

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:

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