GitHub - bkper/bkper-cli: Build and deploy Bkper apps, manage financial data -- books, accounts, transactions, and balances -- from the terminal.

A unified interface for Bkper. Use bkper in two complementary modes:

Interactive mode — run bkper with no arguments to open the agent TUI
Command mode — run bkper <command> for explicit CLI workflows, scripts, and automation

With one tool, you can build and deploy Bkper apps, and manage financial data -- books, accounts, transactions, and balances.

Quick Start

Prerequisites

Node.js >= 18

Install (choose one)

bun add -g bkper

npm i -g bkper

pnpm add -g bkper

yarn global add bkper

Authenticate

bkper auth login

Start using bkper

# Interactive mode (agent TUI)
bkper

# Command mode (explicit command)
bkper book list

Pick a book and create your first transaction:

bkper transaction create -b <bookId> --description "Office supplies 123.78"

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

To build and deploy Bkper Apps, see App Management.

Access Token

Use the access token for direct API calls from any tool:

# Print the current access token
TOKEN=$(bkper auth token)

# Use it with curl, httpie, or any HTTP client
curl -s -H "Authorization: Bearer $TOKEN" \
  https://api.bkper.app/v5/books | jq '.items[].name'

Interactive Mode (powered by Pi)

When you run bkper with no arguments in an interactive terminal, bkper starts the embedded agent TUI.

Bkper's agent mode is intentionally a thin wrapper around Pi:

Pi provides the core agent runtime and TUI
bkper adds Bkper-specific domain context and startup maintenance behavior

Startup maintenance (non-blocking)

On each agent startup, bkper performs a background CLI auto-update check (same behavior as command mode).

Pi passthrough

Use Pi CLI features directly through bkper:

bkper agent -- <pi-args>

Examples:

bkper agent -- -p "Summarize this repository"
bkper agent -- --model openai/gpt-4o -c
bkper agent -- install <pi-package-source>

bkper agent keeps Bkper defaults (including Bkper system prompt) unless you explicitly pass --system-prompt.

For all available passthrough flags and commands, see the Pi CLI reference: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#cli-reference

Pi-specific extensions are loaded from Pi extension folders (for example .pi/extensions and ~/.pi/agent/extensions).

Data Management

Interact with books, accounts, transactions, and balances.

All data commands that operate within a book use -b, --book <bookId> to specify the book context.

Books

Create and manage financial books with locale-specific settings.

# List all books
bkper book list

# Get book details
bkper book get abc123

# Create a book with Brazilian settings
bkper book create --name "My Company" --fraction-digits 2 \
  --date-pattern "dd/MM/yyyy" --decimal-separator COMMA \
  --time-zone "America/Sao_Paulo"

# Create a book with custom properties
bkper book create --name "Project X" -p "code=PX001" -p "department=Engineering"

# Update a book
bkper book update abc123 --lock-date 2024-12-31

Command reference

book list - List all books
- -q, --query <query> - Search query
book get <bookId> - Get a book's details
book create - Create a new book
- --name <name> - Book name (required)
- --fraction-digits <digits> - Number of decimal places (0-8)
- --date-pattern <pattern> - Date format pattern (dd/MM/yyyy, MM/dd/yyyy, or yyyy/MM/dd)
- --decimal-separator <separator> - Decimal separator (DOT or COMMA)
- --time-zone <timezone> - IANA time zone (e.g. America/New_York, UTC)
- --period <period> - Period (MONTH, QUARTER, or YEAR)
- -p, --property <key=value> - Set a property (repeatable)
book update <bookId> - Update a book
- --name <name> - Book name
- --fraction-digits <digits> - Number of decimal places (0-8)
- --date-pattern <pattern> - Date format pattern (dd/MM/yyyy, MM/dd/yyyy, or yyyy/MM/dd)
- --decimal-separator <separator> - Decimal separator (DOT or COMMA)
- --time-zone <timezone> - IANA time zone identifier (e.g. America/New_York, Europe/London, UTC)
- --lock-date <date> - Lock date in ISO format (yyyy-MM-dd, e.g. 2024-01-31)
- --closing-date <date> - Closing date in ISO format (yyyy-MM-dd)
- --period <period> - Period (MONTH, QUARTER, or YEAR)
- -p, --property <key=value> - Set a property (repeatable, e.g. -p code=1010 -p branch=NYC; empty value deletes the property)

Accounts

Manage your chart of accounts within a book.

# List all accounts
bkper account list -b abc123

# Get an account by name
bkper account get "Bank Account" -b abc123

# Create an asset account
bkper account create -b abc123 --name "Bank Account" --type ASSET --groups "Current Assets"

# Update an account
bkper account update "Bank Account" -b abc123 --type LIABILITY

# Archive an account
bkper account update "Old Account" -b abc123 --archived true

# Delete an account
bkper account delete "Old Account" -b abc123

Command reference

account list -b <bookId> - List accounts in a book
account get <nameOrId> -b <bookId> - Get an account
account create -b <bookId> - Create a new account
- --name <name> - Account name (required)
- --type <type> - Account type (ASSET, LIABILITY, INCOMING, OUTGOING)
- --description <description> - Account description
- --groups <groups> - Comma-separated group names
- -p, --property <key=value> - Set a property (repeatable)
account update <nameOrId> -b <bookId> - Update an account
- --name <name> - Account name
- --type <type> - Account type (ASSET, LIABILITY, INCOMING, OUTGOING)
- --archived <true|false> - Archive status
- -p, --property <key=value> - Set a property (repeatable, merges with existing)
account delete <nameOrId> -b <bookId> - Delete an account

Groups

Organize accounts into hierarchical groups for structured reporting.

# List all groups (shows hierarchy)
bkper group list -b abc123

# Create a group
bkper group create -b abc123 --name "Current Assets"

# Create a child group
bkper group create -b abc123 --name "Cash" --parent "Current Assets"

# Update a group
bkper group update "Cash" -b abc123 --hidden true

# Delete a group
bkper group delete "Cash" -b abc123

Command reference

group list -b <bookId> - List groups in a book
group get <nameOrId> -b <bookId> - Get a group
group create -b <bookId> - Create a new group
- --name <name> - Group name (required)
- --parent <parent> - Parent group name or ID
- --hidden - Hide the group
- -p, --property <key=value> - Set a property (repeatable)
group update <nameOrId> -b <bookId> - Update a group
- --name <name> - Group name
- --hidden <true|false> - Hide status
- -p, --property <key=value> - Set a property (repeatable, merges with existing)
group delete <nameOrId> -b <bookId> - Delete a group

Transactions

Record, query, and manage financial transactions.

# Create a draft transaction
bkper transaction create -b abc123 --description "Office supplies"

# Create a complete transaction
bkper transaction create -b abc123 --date 2025-01-15 --amount 100.50 \
  --from "Bank Account" --to "Office Supplies" --description "Printer paper"

# List transactions for a full year (on:YYYY)
bkper transaction list -b abc123 -q "on:2025"

# List transactions for a month (on:YYYY-MM)
bkper transaction list -b abc123 -q "on:2025-01"

# List with custom properties included
bkper transaction list -b abc123 -q "account:Sales" -p

# Update a transaction
bkper transaction update tx_456 -b abc123 --amount 120.00 --description "Printer paper (corrected)"

# Post a draft transaction
bkper transaction post tx_456 -b abc123

# Check (reconcile) a transaction
bkper transaction check tx_456 -b abc123

# Trash a transaction
bkper transaction trash tx_456 -b abc123

# Merge two duplicate transactions
bkper transaction merge tx_123 tx_456 -b abc123

Command reference

transaction list -b <bookId> -q <query> - List transactions matching a query (auto-paginates through all results)
- -p, --properties - Include custom properties in the output
transaction create -b <bookId> - Create a transaction
- --date <date> - Transaction date
- --amount <amount> - Transaction amount
- --description <description> - Transaction description
- --from <from> - Credit account (source)
- --to <to> - Debit account (destination)
- --url <url> - URL (repeatable)
- --remote-id <remoteId> - Remote ID (repeatable)
- -p, --property <key=value> - Set a property (repeatable, empty value deletes)
transaction update [transactionId] -b <bookId> - Update a transaction (or batch update via stdin)
- --date <date> - Transaction date
- --amount <amount> - Transaction amount
- --description <description> - Transaction description
- --from <from> - Credit account (source)
- --to <to> - Debit account (destination)
- --url <url> - URL (repeatable, replaces all)
- --update-checked - Also update checked transactions
- -p, --property <key=value> - Set a property (repeatable, empty value deletes)
transaction post <id> -b <bookId> - Post a draft transaction
transaction check <id> -b <bookId> - Check a transaction
transaction trash <id> -b <bookId> - Trash a transaction
transaction merge <id1> <id2> -b <bookId> - Merge two transactions

Balances

Query account balances and group totals.

# List balances for a specific date (point-in-time)
bkper balance list -b abc123 -q "on:2025-12-31"

# Monthly balance evolution of one account during 2025
bkper balance list -b abc123 -q "account:'<accountName>' after:2025-01-01 before:2026-01-01 by:m" --expanded 2

Command reference

balance list -b <bookId> -q <query> - List balances
- --expanded <level> - Expand groups to specified depth (0+)

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 filtering by the report root group. Root names vary by book.

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

# P&L activity over 2025
bkper balance list -b abc123 -q "group:'<profitAndLossRootGroup>' after:2025-01-01 before:2026-01-01"

Collections

Organize books into collections.

# Create a collection
bkper collection create --name "My Collection"

# Add books to a collection
bkper collection add-book col_789 -b abc123 -b def456

# List all collections
bkper collection list

# Remove a book from a collection
bkper collection remove-book col_789 -b abc123

# Delete a collection
bkper collection delete col_789

Command reference

collection list - List all collections
collection get <collectionId> - Get a collection
collection create - Create a new collection
- --name <name> - Collection name (required)
collection update <collectionId> - Update a collection
- --name <name> - Collection name
collection delete <collectionId> - Delete a collection
collection add-book <collectionId> - Add books to a collection
- -b, --book <bookId> - Book ID (repeatable)
collection remove-book <collectionId> - Remove books from a collection
- -b, --book <bookId> - Book ID (repeatable)

Output Format

All commands support three output formats via the --format global flag:

Format	Flag	Best for
Table	`--format table` (default)	Human reading in the terminal
JSON	`--format json`	Programmatic access, single-item detail
CSV	`--format csv`	LLM consumption, spreadsheets, list reports

# Table output (default)
bkper account list -b abc123

# JSON output
bkper account list -b abc123 --format json

# CSV output -- raw data, no truncation, RFC 4180
bkper account list -b abc123 --format csv

CSV output details:

RFC 4180 compliant -- proper quoting, CRLF line endings, no truncation
All metadata included -- IDs, properties, hidden properties, URLs, and timestamps are enabled
Raw values -- dates stay in ISO format, numbers are unformatted (no locale formatting)
Single-item commands (e.g. account get, transaction create) fall back to JSON since CSV adds no value for non-tabular data

LLM-first output guidance (important):

When command output will be loaded into an LLM context (chat, prompt, memory, or agent reasoning), prefer:

--format csv for list commands (balance list, transaction list, account list, etc.).
--format json for single-item commands (get, create, update) and CLI-to-CLI pipelines.

CSV is significantly more token-efficient than JSON for tabular data, and for wide balance outputs it can reduce token usage by up to 95%.

Quick rule:

LLM consumption of lists/reports → CSV
Programmatic processing / pipelines → JSON
Human terminal reading → Table

Batch Operations & Piping

Write commands (account create, group create, transaction create) accept JSON data piped via stdin for batch operations. The transaction update command also accepts stdin for batch updates. The input format follows the Bkper API Types exactly -- a single JSON object or an array of objects.

# Create transactions
echo '[{
  "date": "2025-01-15",
  "amount": "100.50",
  "creditAccount": {"name": "Bank Account"},
  "debitAccount": {"name": "Office Supplies"},
  "description": "Printer paper",
  "properties": {"invoice": "INV-001"}
}]' | bkper transaction create -b abc123

# Create accounts
echo '[{"name":"Cash","type":"ASSET"},{"name":"Revenue","type":"INCOMING"}]' | \
  bkper account create -b abc123

# Create groups
echo '[{"name":"Fixed Costs","hidden":true}]' | \
  bkper group create -b abc123

# Pipe from a script
python export_bank.py | bkper transaction create -b abc123

The input follows the exact bkper.Transaction, bkper.Account, or bkper.Group type from the Bkper API Types. Custom properties go inside the properties object.

The --property CLI flag can override or delete properties from the stdin payload:

echo '[{"name":"Cash","type":"ASSET"}]' | \
  bkper account create -b abc123 -p "region=LATAM"

Batch output: results are output as a flat JSON array, matching the same format as list commands:

bkper account create -b abc123 < accounts.json
# Output: [{"id":"acc-abc","name":"Cash",...}, {"id":"acc-def","name":"Revenue",...}]

Piping between commands:

All JSON output is designed to be piped directly as stdin to other commands. The output of any list or batch create command can feed directly into a create or update command:

# Copy all accounts from one book to another
bkper account list -b $BOOK_A --format json | bkper account create -b $BOOK_B

# Copy all groups from one book to another
bkper group list -b $BOOK_A --format json | bkper group create -b $BOOK_B

# Copy transactions matching a query
bkper transaction list -b $BOOK_A -q "after:2025-01-01" --format json | \
  bkper transaction create -b $BOOK_B

# Clone a full chart of accounts: groups, then accounts, then transactions
bkper group list -b $SOURCE --format json | bkper group create -b $DEST
bkper account list -b $SOURCE --format json | bkper account create -b $DEST
bkper transaction list -b $SOURCE -q "after:2025-01-01" --format json | \
  bkper transaction create -b $DEST

# Batch update: list transactions, modify, and pipe back to update
bkper transaction list -b $BOOK -q "after:2025-01-01" --format json | \
  jq '[.[] | .description = "Updated: " + .description]' | \
  bkper transaction update -b $BOOK

# Batch update: add a property to all matching transactions
bkper transaction list -b $BOOK -q "account:Expenses" --format json | \
  bkper transaction update -b $BOOK -p "reviewed=true"

# Batch update checked transactions
bkper transaction list -b $BOOK -q "is:checked after:2025-01-01" --format json | \
  bkper transaction update -b $BOOK --update-checked -p "migrated=true"

Writable fields reference

Only the fields below are meaningful when creating or updating resources via stdin. For batch updates, items must include an id field. Other read-only fields (createdAt, updatedAt, etc.) are ignored.

Transaction (bkper.Transaction)

Field	Type	Notes
`id`	`string`	Required for batch updates, ignored on create
`date`	`string`	ISO format `yyyy-MM-dd`
`amount`	`string`	Decimal format `####.##` (string, not number)
`creditAccount`	`{"name":"..."}` or `{"id":"..."}`	Reference to an existing account
`debitAccount`	`{"name":"..."}` or `{"id":"..."}`	Reference to an existing account
`description`	`string`	Free-text description
`urls`	`string[]`	Attached URLs (e.g. receipts)
`remoteIds`	`string[]`	External IDs to prevent duplicates
`properties`	`{"key": "value", ...}`	Custom key/value properties

Account (bkper.Account)

Field	Type	Notes
`name`	`string`	Account name (required)
`type`	`string`	`ASSET`, `LIABILITY`, `INCOMING`, or `OUTGOING`
`credit`	`boolean`	Credit nature (`true`) or debit (`false`)
`archived`	`boolean`	Archive the account on creation
`permanent`	`boolean`	Permanent accounts (e.g. bank accounts, customers)
`groups`	`[{"name":"..."}, ...]`	Groups to assign by name or id
`properties`	`{"key": "value", ...}`	Custom key/value properties

Group (bkper.Group)

Field	Type	Notes
`name`	`string`	Group name (required)
`hidden`	`boolean`	Hide from transactions main menu
`parent`	`{"name":"..."}` or `{"id":"..."}`	Parent group for nesting
`properties`	`{"key": "value", ...}`	Custom key/value properties

App Management

Build, deploy, and manage Bkper apps.

Development Workflow

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

# Start the worker runtime (Miniflare + tunnel + file watching)
# In your project, use "npm run dev" to run both Vite and workers concurrently
bkper app dev

# Build worker bundles (web server + events handler)
# In your project, use "npm run build" to build both client (Vite) and workers
bkper app build

# Sync configuration and deploy to production
bkper app sync && bkper app deploy

# Deploy to development environment
bkper app deploy --preview

# Deploy only the events handler
bkper app deploy --events

# Check deployment status
bkper app status

Note: bkper app dev runs the worker runtime only — Miniflare, file watching, and the Cloudflare tunnel. The Vite client dev server is configured in the project's vite.config.ts and run separately. The project template composes both via npm run dev using concurrently.

Install Apps on Books

# Install an app on a book
bkper app install my-app -b abc123

# Uninstall an app from a book
bkper app uninstall my-app -b abc123

Secrets

# Store a secret (prompts for value)
bkper app secrets put API_KEY

# List all secrets
bkper app secrets list

# Delete a secret
bkper app secrets delete API_KEY

Configuration

Apps are configured via a bkper.yaml file in the project root. See the complete bkper.yaml reference below.

bkper.yaml reference

# =============================================================================
# bkper.yaml Reference
# =============================================================================
# This file documents all available configuration options for Bkper Apps.
# Copy the fields you need to your app's bkper.yaml file.
#
# For a minimal working template, see:
# https://github.com/bkper/bkper-app-template
# =============================================================================

# -----------------------------------------------------------------------------
# APP IDENTITY
# -----------------------------------------------------------------------------
# The app id is permanent and cannot be changed after creation.
# Use lowercase letters, numbers, and hyphens only.
id: my-app

# Display name shown in the Bkper UI
name: My App

# Brief description of what the app does
description: A Bkper app that does something useful

# -----------------------------------------------------------------------------
# BRANDING
# -----------------------------------------------------------------------------
# App logo for light mode (SVG recommended, PNG/JPG supported)
logoUrl: https://example.com/logo.svg

# App logo for dark mode (required for proper theming)
logoUrlDark: https://example.com/logo-dark.svg

# App website or documentation URL
website: https://example.com

# -----------------------------------------------------------------------------
# OWNERSHIP
# -----------------------------------------------------------------------------
# Developer/company name
ownerName: Your Name

# Owner's logo/avatar URL
ownerLogoUrl: https://example.com/owner-logo.png

# Owner's website
ownerWebsite: https://yoursite.com

# Source code repository URL
repoUrl: https://github.com/you/my-app

# Whether the repository is private
repoPrivate: true

# Mark as deprecated (hides from app listings, existing installs continue working)
deprecated: false

# -----------------------------------------------------------------------------
# ACCESS CONTROL
# -----------------------------------------------------------------------------
# Who can update the app configuration and deploy new versions.
# Comma-separated list of Bkper usernames (not emails).
# Supports domain wildcards for registered custom domains: *@yourdomain.com
developers: victor, aldo, *@bkper.com

# Who can install and use the app.
# Same format as developers. Leave empty for public apps.
users: maria, *@acme.com

# -----------------------------------------------------------------------------
# MENU INTEGRATION (optional)
# -----------------------------------------------------------------------------
# When configured, adds a menu item to Bkper's "More" menu.
# Clicking opens a popup with the specified URL.

# Production menu URL (supports variable substitution)
menuUrl: https://${id}.bkper.app?bookId=${book.id}

# Development menu URL (used when developer runs the app)
menuUrlDev: http://localhost:8787?bookId=${book.id}

# Custom menu text (defaults to app name if not specified)
menuText: Open My App

# Popup dimensions in pixels
menuPopupWidth: 500
menuPopupHeight: 300

# -----------------------------------------------------------------------------
# Menu URL Variables
# -----------------------------------------------------------------------------
# The following variables can be used in menuUrl and menuUrlDev:
#
# ${book.id}                - Current book ID
# ${book.properties.xxx}    - Book property value (replace xxx with property key)
# ${account.id}             - Selected account ID (in account context)
# ${account.properties.xxx} - Account property value
# ${group.id}               - Selected group ID (in group context)
# ${group.properties.xxx}   - Group property value
# ${transactions.ids}       - Comma-separated selected transaction IDs
# ${transactions.query}     - Current search query
# -----------------------------------------------------------------------------

# -----------------------------------------------------------------------------
# EVENT HANDLING (optional)
# -----------------------------------------------------------------------------
# When configured, Bkper calls your webhook URL when subscribed events occur.

# Production webhook URL
webhookUrl: https://${id}.bkper.app/events

# Development webhook URL (auto-updated by bkper app dev)
webhookUrlDev: https://<random>.trycloudflare.com/events

# API version for event payloads
apiVersion: v5

# Events to subscribe to (remove events you don't need)
events:
    # Transaction
    - TRANSACTION_CREATED
    - TRANSACTION_POSTED
    - TRANSACTION_CHECKED
    - TRANSACTION_UNCHECKED
    - TRANSACTION_UPDATED
    - TRANSACTION_DELETED
    - TRANSACTION_RESTORED
    # Account
    - ACCOUNT_CREATED
    - ACCOUNT_UPDATED
    - ACCOUNT_DELETED
    # Group
    - GROUP_CREATED
    - GROUP_UPDATED
    - GROUP_DELETED
    # File
    - FILE_CREATED
    - FILE_UPDATED
    # Query
    - QUERY_CREATED
    - QUERY_UPDATED
    - QUERY_DELETED
    # Comment
    - COMMENT_CREATED
    - COMMENT_DELETED
    # Collaborator
    - COLLABORATOR_ADDED
    - COLLABORATOR_UPDATED
    - COLLABORATOR_REMOVED
    # Integration
    - INTEGRATION_CREATED
    - INTEGRATION_UPDATED
    - INTEGRATION_DELETED
    # Book
    - BOOK_CREATED
    - BOOK_UPDATED
    - BOOK_DELETED
    - BOOK_AUDITED

# -----------------------------------------------------------------------------
# FILE PATTERNS (optional)
# -----------------------------------------------------------------------------
# For file processing apps. When a file matching these patterns is uploaded,
# a FILE_CREATED event is triggered with the file content.
filePatterns:
    - '*.ofx'
    - '*.csv'

# -----------------------------------------------------------------------------
# PROPERTIES SCHEMA (optional)
# -----------------------------------------------------------------------------
# Defines autocomplete suggestions for custom properties in the Bkper UI.
# Helps users discover and use the correct property keys/values for your app.
propertiesSchema:
    book:
        keys:
            - my_app_enabled
            - my_app_config
        values:
            - 'true'
            - 'false'
    group:
        keys:
            - my_app_category
        values:
            - category_a
            - category_b
    account:
        keys:
            - my_app_sync_id
    transaction:
        keys:
            - my_app_reference

# -----------------------------------------------------------------------------
# DEPLOYMENT CONFIGURATION (optional)
# -----------------------------------------------------------------------------
# For apps deployed to Bkper's Workers for Platforms infrastructure.
deployment:
    # Web handler (serves UI and API)
    web:
        bundle: packages/web/server/dist
        # assets: packages/web/client/dist  # Static assets (when supported)

    # Events handler (processes webhooks)
    events:
        bundle: packages/events/dist

    # Platform services available to your app (one per type, auto-provisioned)
    # See: https://developers.cloudflare.com/kv/
    services:
        - KV # Key-value storage

Environment variables:

BKPER_API_KEY -- Optional. If not set, uses the Bkper API proxy with a managed API key. Set it for direct API access with your own quotas. Follow these steps to enable.

Command reference

Authentication

auth login - Authenticate with Bkper, storing credentials locally
auth logout - Remove stored credentials
auth token - Print the current OAuth access token to stdout

Agent Bridge (Pi passthrough)

agent -- <pi-args...> - Run Pi CLI with Bkper defaults (system prompt/resources)

App Lifecycle

app init <name> - Scaffold a new app from the template
app list - List all apps you have access to
app sync - Sync bkper.yaml configuration (URLs, description) to Bkper API
app build - Build worker bundles for deployment
app deploy - Deploy built artifacts to Cloudflare Workers for Platforms
- -p, --preview - Deploy to preview environment
- --events - Deploy events handler instead of web handler
app status - Show deployment status
app undeploy - Remove app from platform
- -p, --preview - Remove from preview environment
- --events - Remove events handler instead of web handler
- --delete-data - Permanently delete all associated data (requires confirmation)
- --force - Skip confirmation prompts (use with --delete-data for automation)
app dev - Start the worker runtime for local development
- --sp, --server-port <port> - Server simulation port (default: 8787)
- --ep, --events-port <port> - Events handler port (default: 8791)
- -w, --web - Run only the web handler
- -e, --events - Run only the events handler

Note: sync and deploy are independent operations. Use sync to update your app's URLs in Bkper (required for webhooks and menu integration). Use deploy to push code to Cloudflare. For a typical deployment workflow, run both: bkper app sync && bkper app deploy

App Installation

app install <appId> -b <bookId> - Install an app on a book
app uninstall <appId> -b <bookId> - Uninstall an app from a book

Secrets Management

app secrets put <name> - Store a secret
- -p, --preview - Set in preview environment
app secrets list - List all secrets
- -p, --preview - List from preview environment
app secrets delete <name> - Delete a secret
- -p, --preview - Delete from preview environment

Library

The getOAuthToken function returns a Promise that resolves to a valid OAuth token, for use with the bkper-js library:

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 512 Commits
.claude/commands		.claude/commands
.docs/plans		.docs/plans
.github		.github
assets		assets
src		src
test		test
tools/docs-compliance		tools/docs-compliance
.gitignore		.gitignore
.mocharc.deploy.json		.mocharc.deploy.json
.mocharc.integration.json		.mocharc.integration.json
.mocharc.json		.mocharc.json
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
bkper.yaml		bkper.yaml
bun.lock		bun.lock
package.json		package.json
test-mcp.js		test-mcp.js
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json

Folders and files

Latest commit

History

Repository files navigation

Quick Start

Prerequisites

Install (choose one)

Authenticate

Start using bkper

Access Token

Interactive Mode (powered by Pi)

Startup maintenance (non-blocking)

Pi passthrough

Data Management

Books

Accounts

Groups

Transactions

Balances

Query semantics (transactions and balances)

Collections

Output Format

Batch Operations & Piping

App Management

Development Workflow

Install Apps on Books

Secrets

Configuration

Authentication

Agent Bridge (Pi passthrough)

App Lifecycle

App Installation

Secrets Management

Library

Documentation

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages