CLI Reference
The Scribe CLI lets you manage projects, generate invoices with beautiful PDF templates, track work evidence, and sync between devices — all from the command line.
Installation
Install the Scribe CLI globally with Bun:
bun add -g @scribe.cool/cli
Then run any command with:
scribe --help scribe project list scribe invoice list
Prerequisites
Projects
Projects group related filesystem roots (git repos, code directories) and can be linked to clients for invoicing.
| Command | Description |
|---|---|
| scribe project list [--with-stats] | List all projects. --with-stats shows event counts and date ranges. |
| scribe project show <name> | Show project details, linked client, assigned roots. |
| scribe project create --name "..." [--color --icon] | Create a new project group. |
| scribe project rename <name> --name "New Name" | Rename a project. |
| scribe project delete <name> | Delete a project. Roots become unassigned (not deleted). |
| scribe project discover | Scan filesystem for new git repos and add them as project roots. |
| scribe project unassigned | List roots not assigned to any project. |
| scribe project assign <project> <root-path> | Assign a root to a project. |
| scribe project unassign <root-path> | Remove a root from its project. |
| scribe project link-client <project> <client> | Link a project to a client for billing. Optional --rate flag. |
| scribe project unlink-client <project> | Remove client link from a project. |
Clients
Clients are billing entities. Projects can be linked to clients, and invoices are generated per client.
| Command | Description |
|---|---|
| scribe client list | List all clients with rates. |
| scribe client create --name "..." --email "..." --rate 17500 | Create a client. Rate is in cents per hour ($175/hr = 17500). |
| scribe client show <name> | Show client details. |
| scribe client update <name> --email "new@co.com" | Update a client field. |
| scribe client delete <name> | Delete a client. |
Invoicing
Generate professional invoices with work breakdown from your Scribe timeline. Two built-in PDF templates: mandala (watercolor teal/gold) and minimal (clean white).
| Command | Description |
|---|---|
| scribe invoice list [--status draft|sent|paid] | List invoices with optional status filter. |
| scribe invoice create --client "..." --description "..." --rate 1000000 --quantity 1 | Create an invoice. Amounts in cents ($10,000 = 1000000). |
| scribe invoice show <number> | Show invoice details and line items. |
| scribe invoice pdf <number> [--template mandala] | Generate PDF. Saves to ~/Documents/Scribe/invoices/. |
| scribe invoice send <number> [--to email] | Send invoice via email. Requires RESEND_API_KEY. |
| scribe invoice update <number> --status paid | Update invoice status or notes. |
| scribe invoice delete <number> | Delete a draft invoice. |
Work breakdown
When an invoice has a date range (--since / --until), the generated PDF automatically includes a work breakdown showing each project with git commits during that period — pulled directly from your Scribe timeline data.
Amounts
All monetary values are in cents:
| Amount | Cents | Flag |
|---|---|---|
| $175/hr | 17500 | --rate 17500 --quantity 100 |
| $10,000 flat | 1000000 | --rate 1000000 --quantity 1 |
| $17,500/mo | 1750000 | --rate 1750000 --quantity 1 |
Timeline Summary
Summarize work activity for any date range. Shows event counts, active projects, and per-source breakdown — useful for building invoices.
| Command | Description |
|---|---|
| scribe summary --since 2026-01-01 --until 2026-01-31 | Summary for a specific date range. |
| scribe summary --last-month | Summary for the previous calendar month. |
Ingestion
Scan local AI coding tool sessions and upload to the Scribe hub. Supports Claude, Cursor, Gemini, Codex, OpenCode, Cline, Amp, and Copilot.
| Command | Description |
|---|---|
| scribe scan chat [--provider claude] | Scan local chat sessions. Providers: claude, cursor, gemini, codex, opencode, cline, amp, copilot. |
| scribe ingest chat --host https://scribe.cool --api-key "..." | Upload scanned chat data to the hosted hub. |
Multi-Device Sync
Diagnose sync between local devices and the hosted hub.
| Command | Description |
|---|---|
| scribe hub teams --host ... --auth-token ... | List teams on the hub. |
| scribe hub diagnose --host ... --auth-token ... | Diagnose sync issues between devices. |
| scribe login [--host https://scribe.cool] | Authenticate with the hub. |
| scribe logout | Clear local auth. |
Business Info
Configure your company details and payment methods for invoices. Stored in ~/.scribe/config.json.
| Command | Description |
|---|---|
| scribe org info | Show business info, payment methods, and invoice defaults. |
| scribe org set --company "..." --email "..." --address "..." | Set business info (appears on invoice 'from' section). |
| scribe org payment add --type wire --label "Wire Transfer" --detail "bank=..." | Add a payment method (appears on invoice PDFs). |
| scribe org payment list | List configured payment methods. |
| scribe org defaults --template mandala | Set default invoice template and currency. |
Search
Full-text search across timeline events.
| Command | Description |
|---|---|
| scribe search "query" [--source git] [--limit 20] | Search events. Filter by source and project. |
Other Commands
| Command | Description |
|---|---|
| scribe monitor | Real-time TUI dashboard of ingestion activity. |
| scribe env ls | List environment variables. |
| scribe env create <name> [--sync] | Create a new environment. |
| scribe env add <key> [--secret] | Add an environment variable. |
Claude Code Plugin
Scribe ships as a Claude Code plugin with skills and session hooks that make AI agents aware of your projects and invoicing workflow.
Install the plugin
claude plugin install scribe@b-open-io
What you get
| Component | Type | Description |
|---|---|---|
| Session Hook | Hook | Auto-detects which Scribe project you're in from your working directory. Injects project name, linked client, billing rate, and recent activity into every session. |
| Invoice Skill | Skill | Guides agents through the full invoice workflow — client setup, work summary, project selection, PDF generation with mandala or minimal templates, and email delivery. |
| Project Skill | Skill | Project management — create, rename, discover, assign roots, link to clients. Agents use the CLI commands on your behalf. |
| Release Skill | Skill | Desktop app release workflow — version bump, changelog, build, publish. |
How it works
When you start a Claude Code session in a directory that Scribe tracks, the session hook automatically injects context:
[Scribe] Project: flow | Client: Open Protocol Labs | 234 events (7d) | Rate: $175/hr | Billable: yes
This means you can say things like "generate me an invoice for last month" or "what projects did I work on in January?" and the agent already knows your project context, clients, and billing setup.
Skills are cross-platform
Scribe skills use the open SKILL.md format from agentskills.io. The same skills work in Claude Code, OpenCode, Gemini CLI, Cursor, and 20+ other AI coding tools.