PlanBee CLI

Command-line client for PlanBee — agent coordination, Claude Code hooks and voice notifications.

This package is a client. It requires a PlanBee server (cloud or self-hosted) and is not usable without access to one. Get started at planbee.cloud.

Installation

npm install -g planbee
planbee --version

Node.js 18 or newer.

Updating

npm does not update global packages automatically. To upgrade to the latest release:

npm install -g planbee@latest

Login

planbee auth login --email [email protected]

In a terminal you are prompted for the password (input is hidden). For scripts and CI, pass it via stdin or the environment instead of the command line:

printf '%s' "$PW" | planbee auth login --email [email protected] --password-stdin
PLANBEE_PASSWORD=… planbee auth login --email [email protected]

Without a terminal and without one of these sources, the command fails with a clear error instead of waiting for input. --password <pass> still works but is deprecated: it exposes the password in the process list and the shell history, and prints a warning.

This creates a long-lived CLI token (PAT) and stores it in ~/.planbee/cli-auth.json with 0600 permissions. Alternatively, an existing token can be stored with planbee auth login --token-stdin (reads the token from stdin) or via PLANBEE_TOKEN=pbat_… planbee auth login. --token <token> is deprecated for the same reason as --password.

planbee auth logout always deletes the local file. It revokes the token on the server (best effort, with a hard timeout) only if planbee auth login --email … created it. A token you stored yourself (--token-stdin, PLANBEE_TOKEN, --token) may also be in use on other machines or in CI, so it is only removed locally; add --revoke to revoke it on the server as well (planbee auth logout --revoke). Auth files written by older versions carry no such marker and are treated the same way, with a note on stderr. If the server cannot be reached, a warning is printed; revoke the token in the PlanBee app in that case.

Against your own server:

planbee --local <command>            # http://localhost:3456
PLANBEE_API_URL=https://… planbee …  # any endpoint

What is sent to the server

The client is not a read-only viewer. So you know what happens:

• Session and task data: topic, task list, progress, status and the state objects you set yourself (planbee progress).
• Claude Code transcripts: once the hooks are installed, the client reads the conversation files under ~/.claude/projects/<project>/<session>.jsonl incrementally and uploads the new lines to the server so the conversation is visible in the dashboard. This includes the complete history, including your prompts and the model responses.
• Machine name: when a CLI token is created, the hostname is sent as the token label (cli-<hostname>) so you can tell tokens apart.
• Messages between agents and the text of voice notifications (planbee speak).

Without installed hooks, no transcripts are transferred. Hooks are only set up by planbee hooks install; the command writes to the .claude/settings.json of the given project.

If you run your own server (--local / PLANBEE_API_URL), this data goes there exclusively.

Hooks

planbee hooks install --project /path/to/project
planbee hooks status

Running planbee hooks install again on an already set-up project refreshes the generated planbee-register / planbee-remote command and skill files and removes the outdated planb-register skill (only if it is a PlanBee register skill and its folder contains nothing but SKILL.md).

Generated files carry a # planbee-generated … comment line. Files with that line, and unchanged files from earlier PlanBee versions, are replaced. A file you changed by hand (without that line) is left alone with a warning on stderr; delete the marker line to keep your own version, or run planbee hooks install --force to replace it.

Local session diagnostics

planbee peers [--json] [--verbose]

Lists the local Claude Code sessions (~/.claude/sessions/*.json) and whether PlanBee's cross-session wake-up can reach each one, with a concrete reason when it cannot. Purely local and read-only: nothing is sent to the server.

Author and support

planbee.cloud — infin8 world llc, www.infin8.world

License

Proprietary, see LICENSE: use as a client is permitted, resale and reuse of the source code are not.

The license texts of the bundled open-source packages are included in full in THIRD-PARTY-NOTICES.txt (44 packages, MIT/ISC) and in bin/planbee.js.LEGAL.txt; for those components they take precedence.