{
  "markdown": "# Bookipi CLI\n\n[![release](https://img.shields.io/github/v/release/Bookipi-Group/bookipi-cli?label=release)](https://github.com/Bookipi-Group/bookipi-cli/releases/latest)\n[![release status](https://github.com/Bookipi-Group/bookipi-cli/actions/workflows/release.yml/badge.svg?event=release)](https://github.com/Bookipi-Group/bookipi-cli/actions/workflows/release.yml)\n\n**Bookipi CLI** turns your back office — invoices, payments, customers,\nexpenses, proposals, contracts, and reports — into clean `--json` commands you\ncan run directly or drive through Claude in plain English.\n\nFull overview and docs: [Bookipi CLI](https://bookipi.com/cli/)\n\nPrefer zero setup? The **[Bookipi connector](docs/connector.md)** adds Bookipi\nto claude.ai, Claude Desktop, or any MCP client — nothing to install.\n\n## Two ways to use it\n\n- **Talk to Claude** — install the skill and ask in plain English inside\n  Cowork, Claude Desktop, or Claude Code. Claude runs Bookipi CLI for you; no\n  commands to memorize. Setup is below.\n- **Build on the CLI** — clone it, run `bookipi init`, and pipe `--json`\n  output into your own agents, automations, and products. See\n  [Building on the CLI](#building-on-the-cli).\n\nEither way it's the same tool underneath. Everything that sends, charges, or\nrecords stops for your confirmation first.\n\n## Talk to Claude\n\nThe skill bundle is self-contained (it includes the Bookipi CLI), so no\nseparate installation is required. You don't run commands — you talk to Claude\nand Claude does the work. This guide shows you how to set that up.\n\n### 1. Install the skill\n\n1. Download the latest `bookipi-cli.skill` from\n   [Releases](https://github.com/Bookipi-Group/bookipi-cli/releases).\n2. Double-click it. Cowork or Claude Desktop will prompt to install.\n3. Confirm. It now appears in your Skills list as `bookipi-cli`.\n\nIf double-click does nothing, drag the file into the Cowork window. If your\nbrowser stripped the `.skill` extension on download, rename it back.\n\n**Claude Code:** install it as a plugin instead — no download, and upgrading\nlater is two commands rather than a re-download:\n\n```\n/plugin marketplace add Bookipi-Group/bookipi-cli\n/plugin install bookipi@bookipi-cli\n```\n\nClaude fetches the CLI on first use, so there's nothing else to install. You\nneed Node 22.12 or newer on your machine.\n\nTo upgrade later, refresh the marketplace **first** — `install` and `update`\nboth read a local copy of this repo, so without the refresh they will happily\nkeep serving the version you originally cloned:\n\n```\n/plugin marketplace update bookipi-cli\n/plugin update bookipi@bookipi-cli\n```\n\nInclude the `@bookipi-cli` part — `update bookipi` on its own reports\n\"Plugin not found\".\n\nA skill installed via Claude Desktop is also available in Claude Code sessions\nstarted from the desktop app, so you may already have it. To install by hand\ninstead, unzip the `.skill` file into `~/.claude/skills/` (it's a zip — you'll\nend up with `~/.claude/skills/bookipi-cli/`).\n\n**Codex:** add this repo as a marketplace and install from it — the plugin\ncarries its own Codex manifest, so you get the Bookipi icon and starter prompts\nrather than a bare listing:\n\n```\n/plugin marketplace add Bookipi-Group/bookipi-cli\n/plugin install bookipi\n```\n\n**Gemini CLI:** install it as an extension:\n\n```\ngemini extensions install https://github.com/Bookipi-Group/bookipi-cli\n```\n\nUpgrade later with `gemini extensions update bookipi`.\n\n**Other agents** — Cursor, GitHub Copilot, Antigravity, Windsurf — read\nskills from `.agents/skills/`, which this repo publishes alongside the Claude\npath. Copy `.agents/skills/bookipi-cli/` into your project or agent skills\ndirectory.\n\n### 2. Allow network access (only on your own Claude subscription, one-time)\n\nYou can skip this entirely if:\n\n- You're on Claude Code — it runs on your own machine with your normal network,\n  so an org allowlist doesn't apply.\n- Your workspace admin has already allowlisted the domains below.\n\nYou only need this if you're using Cowork / Claude Desktop on your own\nworkspace/org. Cowork runs Claude in an Anthropic-hosted sandbox that blocks\nunknown websites, so Bookipi's servers must be on your org's allowlist —\notherwise login will fail on the first try. (Tip: if you hit network trouble in\nCowork, switching to Claude Code is a quick workaround.)\n\nAsk your workspace admin (or do it yourself if you're an admin):\n**Organization Settings → Capabilities → Code execution → Additional allowed\ndomains**, and add:\n\n```\n*.bkpi.co\n*.bookipi.com\n*.bookipay.com\n*.s3.amazonaws.com\n*.amplitude.com\n```\n\nThe first three are Bookipi servers (invoices, login, meetings, contracts, PDF\nrendering). The S3 one is only needed for uploading receipt photos and showing\nlogos/QR codes in invoice previews.\n\n**How you'll know it's missing:** Claude will tell you directly — something like\n\"this environment is blocking network access to Bookipi's servers\", usually on\nthe very first request. That message includes the same list above; forward it to\nyour admin.\n\n### 3. Set up your project folder\n\nEvery Bookipi workspace lives in its own **local folder**. This keeps your\ncredentials and account-specific data scoped — no env-var juggling, no\nshared global state.\n\n> ⚠️ **Cowork changed how projects are stored.** New projects are now\n> **cloud-based by default** — they do _not_ create a local folder unless you\n> ask for one. A cloud-only project runs in a temporary space that's wiped\n> between chats, so your Bookipi login **won't survive** to the next session.\n> To stay logged in, you **must** attach a local folder when you create the\n> project (below).\n\n1. In Cowork, click **New Project**, give it a name like `bookipi-testing`,\n   then click **Use a folder** and pick (or create) a folder on your computer.\n   This is the important step — without it, the project is cloud-only and your\n   login won't persist.\n   **In Claude Code** there's no button — just start `claude` inside any\n   folder you want to use as the workspace.\n2. In the chat, say:\n\n   > _Set up Bookipi in this folder._\n\nClaude opens a browser to sign you in to Bookipi, then saves your credentials\ninside the folder (under `.bookipi/`, auto-gitignored). Confirm with:\n\n> _Who am I logged in as?_\n\nEvery session you open in that project is auto-logged-in. To work with a\ndifferent Bookipi account, create a different folder and repeat — each\nfolder is its own workspace.\n\n**If you skip the folder in Cowork** (a cloud-only project), you'll be asked to\nlog in again every new chat — there's nowhere persistent to keep the\ncredentials. Attaching a folder is the only way to stay logged in between\nsessions. _(A no-folder, zero-setup alternative: the\n**[Bookipi connector](docs/connector.md)** stores the login on your Claude\naccount instead.)_\n\n**Claude Code only:** the folder is recommended, not required. If you skip\nit and just say _\"log me in to Bookipi\"_, credentials are saved globally\n(`~/.bookipi/`) and work from any directory on your machine — fine for a\nsingle account. Use per-folder workspaces when you want to test multiple\naccounts side by side.\n\n### 4. Try things\n\n#### Reading\n\n- \"Who owes me money?\"\n- \"Pull up Wayne Construction.\"\n- \"Show my overdue invoices.\"\n- \"Show me what INV-650 looks like.\" (you get a print-ready PDF)\n- \"List my open proposals.\"\n- \"Show my pending contracts.\"\n- \"What deals are in proposal stage?\"\n- \"Show me my items / products.\"\n- \"What's on my calendar today?\"\n- \"Find my meetings with Maria this week.\"\n- \"Is my Google Calendar connected?\"\n- \"Give me the morning brief.\"\n- \"How much did I invoice last month?\"\n- \"Who's my biggest customer this quarter?\"\n- \"What products are selling well?\"\n\n#### Creating\n\n- \"Add a new customer: Acme Corp, billing@acme.com.\"\n- \"Add 'logo design' to my items list at $200.\"\n- \"Add a new deal — Stark kitchen renovation, $40,000.\"\n- \"Create an invoice for Acme — $5,000 for consulting.\"\n- \"Draft a proposal for the Stark deal — kitchen renovation, $40,000.\"\n- \"Turn that accepted proposal into a contract.\"\n\n#### Sending\n\n- \"Send invoice INV-650 to alice@acme.com.\"\n- \"Send the proposal to John.\"\n- \"Send the MSA contract to Bruce.\"\n- \"Email Maria — tell her I'll be late to the call.\"\n- \"Send reminders to all my overdue invoices.\"\n\n#### Receipts & expenses (drag an image/PDF into chat)\n\n- (drop in a receipt photo) \"Log this as an expense.\"\n- \"What expense categories do I have?\"\n- \"Show my expenses this month.\"\n\n#### Reports & insights\n\n- \"Build me a dashboard for last quarter.\" (opens an HTML report)\n- \"Give me insights on my business this month.\"\n- \"What should I focus on this week?\"\n\n#### Acting / changing things\n\n- \"Mark the Stark deal as won.\"\n- \"Mark INV-650 as paid.\"\n- \"Update Wayne's email to wayne@new-domain.com.\"\n- \"Has Bruce signed the MSA yet?\"\n- \"Switch to my other Bookipi account.\"\n- \"What companies do I have?\"\n- \"Log me out.\"\n\nEverything that sends, charges, or records stops for your confirmation first.\n\n## Building on the CLI\n\nBookipi CLI is also a standalone, JSON-first command-line tool you can build on\ndirectly — for AI agents, automations, integrations, and your own products. The\nbundled CLI runs on Node 22+ with no build step.\n\nGrab the bundled CLI from the latest release — this repo holds the skill and\ndocs, not the CLI source, so cloning it won't give you a binary:\n\n```\ncurl -fsSL -o bookipi-cli.skill \\\n  https://github.com/Bookipi-Group/bookipi-cli/releases/latest/download/bookipi-cli.skill\nunzip -q bookipi-cli.skill 'bookipi-cli/bin/*'\nalias bookipi='node \"$PWD/bookipi-cli/bin/bookipi.js\"'\n\nbookipi init                                   # creates a workspace + browser OAuth sign-in (~5s)\nbookipi invoice list --status overdue --json   # structured output your code can act on\n```\n\nFor headless or CI use, skip the browser sign-in and set a token instead:\n\n```\nexport BOOKIPI_TOKEN=...\n```\n\nAdd `--json` to any command for machine-readable output. A typical example:\n\n```\n$ bookipi invoice list --status overdue --json\n[\n  { \"number\": \"INV-650\", \"customer\": \"Acme Corp\", \"amount\": 5000, \"currency\": \"USD\", \"status\": \"overdue\", \"days_late\": 12 },\n  { \"number\": \"INV-661\", \"customer\": \"Stark Ind.\", \"amount\": 12000, \"status\": \"overdue\", \"days_late\": 4 }\n]\n```\n\n### Commands\n\nA small, predictable, `--json`-first surface your code can call reliably. Every\ncommand accepts `--json`; run `bookipi <group> --help` for the flags on any one\nof them.\n\n| Group | What it covers | Subcommands |\n| --- | --- | --- |\n| `invoice` | Invoices and the wider document family | `list` `get` `preview` `create` `create-from-proposal` `duplicate` `update` `delete` `send` `send-receipt` `mark-paid` `void` `remind` `collections` `attach-photo` |\n| `customer` | Customers, their payment history and email | `list` `get` `payments` `create` `update` `delete` `send-email` `emails` |\n| `item` | Products and services you bill for | `list` `create` `set-photo` |\n| `expense` | Expenses and receipt scanning (OCR) | `categories` `list` `upload` `scan` `create` `delete` |\n| `paylink` | BPay payment links | `create` `list` `get` `status` `send` |\n| `deal` | Pipeline deals | `list` `create` `update` |\n| `proposal` | AI-written proposals | `list` `generate` `update` `duplicate` `send` `delete` |\n| `contract` | eSign contracts | `list` `draft` `upload` `create-from-proposal` `finalize` `send` |\n| `report` | Reports, dashboards and insights | `summary` `customers` `items` `dashboard` `insights` `digest` `suggest` `open` |\n| `meeting` | Recorded meetings and bookings | `list` |\n| `calendar` | Calendar connection state | `status` |\n| `company` | The active company | `list` `set` |\n| `website` | The AI-built company website | `status` `content` `pages` `page` `create` `generate` `add-page` `update` `ask` `preview` `publish` `analytics` `open` |\n| — | Session and workspace | `login` `logout` `whoami` `init` `mcp` |\n\nNote the difference between the two paths: in chat, the skill stops and asks\nbefore anything sends, charges, or records. The CLI has no such prompt — a\nwrite subcommand executes as soon as you run it, which is what you want in a\nscript and worth knowing before you wire one up.\n\n## Found a bug? Stuck?\n\nOpen an issue on\n[GitHub](https://github.com/Bookipi-Group/bookipi-cli/issues) with:\n\n- What you typed\n- What Claude did\n- What you expected\n\nThe more detail, the faster we can help.\n\n**Security issues:** please don't open a public issue — see\n[SECURITY.md](SECURITY.md) for how to report privately.\n\n## Privacy\n\nBookipi CLI talks only to Bookipi's own services, on your behalf, using your own\nBookipi account. Full policy: **[bookipi.com/privacy-policy](https://bookipi.com/privacy-policy/)**.\n\n**What it collects and where it goes**\n\n- **Your Bookipi business data** — invoices, customers, items, expenses, deals,\n  proposals, contracts, meetings, website content. Read from and written to\n  your Bookipi account over HTTPS. Nothing is stored anywhere else.\n- **Credentials** — an OAuth access token and refresh token, obtained by\n  browser sign-in. Stored **locally on your machine** in the workspace folder\n  (`.bookipi/`, auto-gitignored) or in `~/.bookipi/`. They are never sent\n  anywhere but Bookipi's auth service, and `bookipi logout` deletes them.\n- **Receipt and logo images** — uploaded to Bookipi's S3 storage so scanning and\n  invoice previews work.\n- **Usage analytics** — which command or tool ran, how long it took, whether it\n  failed, plus CLI version, OS and client platform, sent to Amplitude so we can\n  find broken flows. Identified by a one-way hash of your email and a hash of\n  the machine, never by either value itself. Command arguments, invoice\n  contents, customer records and credentials are not included. Turn it off with\n  `BOOKIPI_NO_ANALYTICS=1` or the cross-tool `DO_NOT_TRACK=1`.\n\n**What it does not do**\n\nIt does not scan your filesystem — it reads the workspace folder and whatever\nfile you point it at, such as a receipt image. It does not collect your\nconversations with Claude, and it does not share your data with third parties\nfor advertising or model training.\n\n**Retention** — business data lives in your Bookipi account and follows\nBookipi's retention policy; delete it there or ask support to delete the\naccount. Local credentials live only on your machine until you log out.\n\n**Questions or a deletion request:** [support@bookipi.com](mailto:support@bookipi.com).\n\n## License\n\nCopyright © Bookipi. All rights reserved — see [LICENSE](LICENSE). Use of\nBookipi CLI is subject to Bookipi's\n[Terms of Service](https://bookipi.com/terms-of-service/).\n",
  "bytes": 14553,
  "sha": "372e566e06300df8a7b5eba6f648e2e1dd0c7ce20be5075589907b47151241bf",
  "repo_slug": "bookipi-group/bookipi-cli",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_bookipi_group_bookipi_cli_7f91739a/readme"
}