# Bkper Platform

> Build integrations, automate workflows, and extend Bkper with its APIs, tools, and managed app runtime.

Bkper is designed to be extended. Whether you're piping CLI commands in a shell script or building a full platform app with a UI, events, and managed hosting — the same APIs and tools power everything.

## The building spectrum

**Scripts & CLI** — Pipe data through the CLI, write Node.js scripts, or call the REST API directly. No infrastructure needed.

**Google Workspace** — Build automations with Apps Script, extend Google Sheets with custom functions and triggers.

**Platform Apps** — Full applications with managed hosting, authentication, event handling, and deployment on the [Bkper Platform](https://bkper.com/docs/platform/apps/overview.md).

**AI-assisted development** — Prefer CLI local tools when an agent can run terminal commands. Use MCP for conversational connector access. Keep deterministic financial outputs in scripts, tests, and audited artifacts.

- [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai.md): Add structured AI inference to a Bkper Platform app with managed authentication, live model discovery, and typed server-side validation.
- [App Listing](https://bkper.com/docs/platform/apps/app-listing.md): Apps are listed on the Bkper Automations Portal, populated from bkper.yaml fields. Sync metadata with bkper app sync, and by default limit installation to declared users until you publish more broadly.
- [App Architecture](https://bkper.com/docs/platform/apps/architecture.md): Bkper platform apps use one Worker with an npm workspace for the client UI, typed /api/* routes, and /events handlers.
- [App Configuration](https://bkper.com/docs/platform/apps/configuration.md): Reference for bkper.yaml — the single file that declares your app's identity, menu integration, event subscriptions, deployment targets, secrets, and KV storage. Sync metadata with bkper app sync, then deploy code with bkper app deploy.
- [Context Menu](https://bkper.com/docs/platform/apps/context-menu.md): Add a custom item to the Transactions page More menu that opens a URL pre-populated with the current book context — query, account, date range, and more.
- [Building & Deploying](https://bkper.com/docs/platform/apps/deploying.md): Build locally, sync app metadata and managed source, then explicitly deploy to the Bkper Platform. Covers previews, secrets, KV storage, and deployment status.
- [Development Experience](https://bkper.com/docs/platform/apps/development.md): Local development uses two composable processes: bkper app dev for the Worker runtime and vite dev for the client UI with HMR. The npm workspace runs both concurrently.
- [Bkper Webhooks and Event Handlers](https://bkper.com/docs/platform/apps/event-handlers.md): Write code that reacts to book events — checked transactions, new accounts, and files — to automate calculations, sync data between books, and call external services. Covers response format, loop prevention, and replay.
- [Your First App](https://bkper.com/docs/platform/apps/first-app.md): Scaffold, run, and deploy a Bkper platform app in minutes. This is a thin walkthrough — deep reference for each topic lives in the other App docs.
- [The Bkper Platform](https://bkper.com/docs/platform/apps/overview.md): The Bkper Platform provides managed app hosting, shared private source, authentication, previews, logs, secrets, storage, and local event delivery.
- [App Quality Guidelines](https://bkper.com/docs/platform/apps/quality.md): Shared expectations for reliable, secure, and maintainable Bkper apps.
- [App Security](https://bkper.com/docs/platform/apps/security.md): Understand platform and app security responsibilities, then authorize app operations by user domain, Book permission, and app installation.
- [Bkper Self-Hosted Webhooks](https://bkper.com/docs/platform/apps/self-hosted.md): Host Bkper event handlers outside the Bkper Platform — on Google Cloud Functions (with automatic authentication via service account) or any generic webhook infrastructure. Use when you have compliance constraints or an existing cloud setup.
- [Shared App Source](https://bkper.com/docs/platform/apps/shared-app-source.md): Host one private Bkper app codebase that authorized teammates and coding agents can clone, improve, and continue building together.
- [Examples & Patterns](https://bkper.com/docs/platform/examples.md): Open-source production apps demonstrating key integration patterns: property-driven tax bots, multi-book exchange rate sync, FIFO inventory and portfolio tracking, subledger hierarchies, and Google Sheets add-ons.
- [The Agent Model](https://bkper.com/docs/platform/getting-started/agent-model.md): Every program that acts on Bkper books — scripts, automations, platform apps, bank connections — is an agent acting on behalf of a user. Agents are identified by logo and name in the activity stream, and are bound by the same permissions as the user who authorized them.
- [Quick Wins](https://bkper.com/docs/platform/getting-started/quick-wins.md): Start building with Bkper in minutes using three approaches of increasing complexity: a one-line CLI pipe, a 20-line Node.js script, and a direct REST API call with curl.
- [Bkper Developer Setup](https://bkper.com/docs/platform/getting-started/setup.md): Install the Bkper CLI, authenticate via Google OAuth, and verify access to your books. This single setup step unlocks CLI commands, bkper-js scripting, and the full app development toolchain.
- [Apps Script Development](https://bkper.com/docs/platform/google-workspace/apps-script.md): Use the bkper-gs library to build Bkper automations that run inside Google's serverless Apps Script platform — scheduled jobs, spreadsheet triggers, custom add-ons, and workflows that combine Bkper with Sheets, Drive, and Gmail.
- [Building Sheets Integrations](https://bkper.com/docs/platform/google-workspace/google-sheets.md): Go beyond the standard add-on with custom Google Sheets integrations using bkper-gs — build team-specific menus, automated import/export pipelines, scheduled balance reports, and two-way sync between spreadsheets and Bkper books.
- [CLI Scripting & Piping](https://bkper.com/docs/platform/scripts/cli-pipelines.md): Use the Bkper CLI as a scripting tool — pipe JSON between commands for batch creates and updates, output CSV for data pipelines and AI agents, and chain operations to migrate, transform, or sync book data without writing code.
- [Node.js Scripts](https://bkper.com/docs/platform/scripts/node-scripts.md): Write standalone Node.js scripts with bkper-js for complex logic, bulk data operations, scheduled jobs, and integrations that go beyond what the CLI alone can do.
- [Bkper REST API Authentication and Direct Usage](https://bkper.com/docs/platform/scripts/rest-api.md): Call the Bkper REST API directly from any language using raw HTTP. Covers the endpoint, authentication, request examples in curl, fetch, and Python, the OpenAPI specification, and optional API keys for dedicated quota.
- [Bkper CLI](https://bkper.com/docs/platform/tools/cli.md): Use the Bkper CLI for data management and app development, including shared-source cloning, local development, builds, metadata sync, deployment, logs, and secrets.
- [Libraries & SDKs](https://bkper.com/docs/platform/tools/libraries.md): Choose the right library for your environment: bkper-js for Node.js and browsers, bkper-gs for Google Apps Script, @bkper/web-auth for OAuth on *.bkper.app subdomains, and @bkper/bkper-api-types for TypeScript definitions in any project.