@tabbio-technologies/cli 1.2.8

package/README.md

@@ -0,0 +1,763 @@
+# Tabbio CLI
+
+`tabbio` puts your whole Tabbio account in the terminal: every tool the Tabbio
+MCP server exposes (CVs, profile, jobs, applications, messages, skills,
+automations, memory and more), streaming chat with the Tabbio agent, approvals
+for sensitive actions, machine-readable output for scripts, and a stdio bridge
+for MCP clients that cannot speak HTTP.
+
+It is a thin client. Every capability comes from the same API the Tabbio apps
+use, over the same authentication, so the CLI can never do more than you can do
+in the app.
+
+Version 1.2.8. Where this guide and the code disagree, the code is right.
+
+- [Install](#install)
+- [First run](#first-run)
+- [Signing in](#signing-in)
+- [Commands](#commands)
+- [Output and exit codes](#output-and-exit-codes)
+- [Profiles and files](#profiles-and-files)
+- [Approvals](#approvals)
+- [Limits](#limits)
+- [Research, documents, pages and images](#research-documents-pages-and-images)
+- [Using Tabbio from MCP clients](#using-tabbio-from-mcp-clients)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Screenshots](#screenshots)
+- [Contributing](#contributing)
+
+## Install
+
+Requires Node.js 20 or newer.
+
+```sh
+# Run once without installing
+npx @tabbio-technologies/cli
+
+# Install the `tabbio` command globally
+npm i -g @tabbio-technologies/cli
+tabbio --version
+```
+
+From source, inside the Tabbio monorepo:
+
+```sh
+pnpm install
+pnpm --filter @tabbio-technologies/cli build
+node apps/cli/dist/cli.js --help
+
+# or run the TypeScript sources directly
+pnpm dev:cli -- --help
+```
+
+## First run
+
+```sh
+tabbio login      # opens your browser to approve this computer
+tabbio status     # who you are, which server, how you are signed in
+tabbio            # interactive home screen (in a terminal)
+```
+
+In an interactive terminal, `tabbio` with no arguments opens the home screen.
+It is built around the chat composer: type a message to start a chat, or `/`
+for the command palette (browse tools, approvals, status). Recent tool runs and
+key hints sit beside it on wide terminals and below it on narrow ones. When
+stdout is not a terminal (a pipe, a script, CI) it prints help instead and
+never draws the interactive UI.
+
+## Signing in
+
+`tabbio login` picks a method in this order: an explicit flag, then the browser
+hand-off when there is a terminal and a display, then email.
+
+The browser hand-off and email both give the CLI an **app session**, the same
+kind of session the Tabbio app itself uses. That one session is used for
+everything: the tool catalog over MCP, chat, and approving actions from the
+terminal. The CLI does not create or need a personal MCP token.
+
+A personal MCP token (method 3) is the alternative for scripts and CI. It
+reaches the tools only.
+
+### 1. Browser hand-off (default on a desktop)
+
+```sh
+tabbio login
+tabbio login --browser
+```
+
+1. The CLI starts a one-shot listener on `127.0.0.1` on a random port and opens
+   `https://app.tabbio.com/cli/connect?port=<port>&state=<nonce>&device=<hostname>`.
+2. Sign in to Tabbio in the browser if you are not already. The page shows the
+   account, the computer name, what you are granting, and the exact address
+   the one-time code will be sent to (`http://127.0.0.1:<port>/callback`).
+3. Choose **Approve and connect**. The browser hands a 60-second, single-use
+   code to the listener, and the CLI swaps it for its own session.
+   **Cancel** tells the listener you declined and the command exits.
+
+The listener gives up after 5 minutes. Ctrl+C cancels at any time.
+
+For editors and wrappers that want to open the page themselves:
+
+```sh
+tabbio login --non-interactive
+# {"url":"https://app.tabbio.com/cli/connect?port=…&state=…&device=…","state":"…","expiresAt":"…"}
+```
+
+It prints that JSON on stdout, opens no browser, and waits for the same
+loopback callback.
+
+The browser has to run on the same computer as the CLI, because `127.0.0.1`
+means "this machine". Over SSH, or on a machine without a browser, use email.
+
+### 2. Email code (headless, SSH, containers)
+
+```sh
+tabbio login --email you@example.com
+```
+
+Tabbio emails a 6-digit code. Type it at the prompt (3 attempts; the code is
+valid for 10 minutes).
+
+### 3. Personal MCP token (tools only)
+
+```sh
+# from stdin, which keeps the token out of your shell history and the process list
+pbpaste | tabbio login --with-token
+tabbio login --with-token < token.txt
+
+# as an argument (visible in shell history and `ps` while it runs)
+tabbio login --token tabbio_mcp_...
+
+# or, without storing anything
+export TABBIO_TOKEN=tabbio_mcp_...
+```
+
+This uses a token you already have: create or copy it in the app under
+**Settings › MCP Access**. It gives the CLI the tool catalog (`tools`, `run`,
+`<group> <action>`, `mcp serve`) within the token's scope (personal, company or
+both; read, or read and write). It is not an app session, so `chat`, `ask`,
+`artifacts`, `approvals approve` and `approvals reject` need a full sign-in
+(see [`ask`](#ask) for the one exception and why it does not work today).
+
+Tabbio keeps **one active personal MCP token per account**: creating a new one
+in Settings › MCP Access replaces the previous one. If you use the same token
+in another MCP client (Claude Desktop, Cursor…), making a new token for either
+one cuts the other off; run `tabbio login --with-token` again with the new
+token. Browser and email sign-ins are not affected by this.
+
+### 4. CI and automation
+
+Environment variables override the stored credentials and are never written to
+disk:
+
+| Variable | Meaning |
+|---|---|
+| `TABBIO_TOKEN` | Personal MCP token (`tabbio_mcp_…`). Enough for the tools and `mcp serve`. |
+| `TABBIO_ACCESS_TOKEN` | App access token (JWT). Works for everything, including tools, chat and approvals. Expires after 24 hours and is not refreshed, so it suits short jobs only. |
+| `TABBIO_PROFILE` | Profile to use when `--profile` is not given. |
+| `TABBIO_API_URL`, `TABBIO_APP_URL`, `TABBIO_MCP_URL` | Point at another environment. |
+| `CI` | Any value: never draw interactive UI, never prompt. |
+
+```sh
+# GitHub Actions example
+- run: npx -y @tabbio-technologies/cli run cv.list --json > cvs.json
+  env:
+    TABBIO_TOKEN: ${{ secrets.TABBIO_TOKEN }}
+```
+
+### What sign-in stores
+
+After a browser or email sign-in the CLI keeps an app session: a 24-hour
+access token, a refresh token that renews it, and your user id and email. The
+session appears on the server under this computer's name (the hostname, or
+`TABBIO_DEVICE_LABEL`). With `--token` / `--with-token` it stores the personal
+token instead.
+
+`tabbio status` says which one a profile uses, without showing secrets:
+`app session` for a browser or email sign-in, or `personal token …a1b2` (the
+last four characters) for a token.
+
+### Signing out
+
+```sh
+tabbio logout          # this profile: ends the app session and deletes the stored credentials
+tabbio logout --all    # every profile
+```
+
+For a browser or email sign-in, `logout` ends the app session on the server
+(the refresh token is revoked) and deletes the local credentials. For a
+personal token, it only deletes the local copy: the token itself stays valid,
+because other clients may use it. Revoke it in Settings › MCP Access if you
+want it gone.
+
+## Commands
+
+```
+tabbio                                   TTY: interactive home. Non-TTY: help.
+tabbio login [--browser | --email <addr> | --token <tabbio_mcp_…> | --with-token] [--non-interactive] [--profile p] [--api-url u] [--app-url u]
+tabbio logout [--all]
+tabbio status                            profile, API/MCP urls, user, plan, sign-in kind (app session | personal token …xxxx), pending approvals, catalog age
+tabbio whoami [--json]
+tabbio doctor                            node version, config perms, /api/health, MCP tools/list, JWT validity, clock skew
+tabbio config list|get <k>|set <k> <v>|path ; tabbio config profile list|use <name>|add <name> --api-url … --app-url …
+tabbio tools [query] [--group g] [--writes|--reads] [--json] [--refresh]     TTY: browser; else list
+tabbio tools describe <tool.id> [--json]                                    schema as flags + example
+tabbio run <tool.id> [--<flag> …] [--input '<json>' | --input-file f | -] [--wait] [--yes] [--json|--table|--plain] [--fields a,b]
+tabbio <group> <action> [flags]          generated for every catalog tool (same options as run)
+tabbio workflows                         says that workflows are not exposed over MCP (they run inside chat)
+tabbio approvals [list] [--json] ; approvals show <id> ; approvals approve <id> [--reason r] [--wait] ; approvals reject <id> [--reason r] ; approvals wait <id> [--timeout 10m]
+tabbio artifacts [list] [--kind k] [--status s] ; artifacts get|open|versions|delete|wait <id> ; artifacts download <id> [--format f] [--out p] [--force] [--wait] ; artifacts restore <id> <versionId>
+tabbio ask "<question>" [--mode m] [--via-mcp] [--json]   one question through the chat stream (app session)
+tabbio chat [message] [--mode seeker|employer] [--company <id>] [--thread <id>] [--model <id>] [--research auto|on|off] [--image auto|on|off] [--result auto|summary|document|slides|page|image] [--save] [--json]
+tabbio mcp serve [--profile p]          stdio ↔ remote MCP bridge for stdio-only clients
+tabbio mcp url                          prints the MCP URL for `claude mcp add`
+tabbio completion bash|zsh|fish
+tabbio help exit-codes
+tabbio --version | --help | --debug | --color | --no-color | --json
+```
+
+Global flags work on every command:
+
+| Flag | Effect |
+|---|---|
+| `--profile <name>` | Use a named profile (see [Profiles](#profiles-and-files)). |
+| `--api-url <url>` | Override the API origin for this run. |
+| `--json` | Machine-readable output (see [Output](#output-and-exit-codes)). |
+| `--color`, `--no-color` | Force colour on or off. |
+| `--debug` | Print method, URL, status, request id and timing for every request to stderr. Never prints bodies or secrets. |
+| `--yes` | Approve your own approval-gated calls for this one invocation, when a full sign-in is present; otherwise exit 6. |
+| `--quiet` | Only the result, no progress or hints. |
+
+### `login`, `logout`, `status`, `whoami`, `doctor`
+
+```sh
+tabbio login --email you@example.com --profile staging --api-url https://staging-api.example.com --app-url https://staging-app.example.com
+tabbio whoami --json | jq -r .email
+tabbio doctor          # run this first when something is off
+```
+
+`doctor` checks the Node version, the permissions on the config directory and
+credentials file, `/api/health`, an MCP `tools/list`, whether the access token
+is still valid, and the clock skew between your machine and the server.
+
+### `config` and `config profile`
+
+```sh
+tabbio config path                       # where config.json lives
+tabbio config set updateCheck false      # no daily npm version check
+tabbio config profile list
+tabbio config profile add staging --api-url https://staging-api.example.com --app-url https://staging-app.example.com
+tabbio config profile use staging
+```
+
+CLI profiles (environments and their credentials) live under `tabbio config
+profile`. `tabbio profile …` is a different thing: it is generated from the
+product's `profile.*` tools and edits your Tabbio profile, for example
+`tabbio profile get` or `tabbio profile update --title "Product manager"`.
+
+### `tools`
+
+```sh
+tabbio tools                     # interactive browser in a terminal, a list otherwise
+tabbio tools cv --reads          # read-only CV tools
+tabbio tools --group job --json  # machine-readable catalog slice
+tabbio tools describe catalog.jobSearch
+```
+
+The catalog comes from the MCP server's `tools/list` and is cached locally;
+`--refresh` refetches it. Each tool has a canonical id (`cv.list`,
+`catalog.jobSearch`, `careerHighlight.upsert`) and a read or write badge.
+`describe` prints the input schema as command-line flags plus an example.
+
+### `run` and generated commands
+
+Every tool id is also a command: the id is split on the dot and camelCase
+becomes kebab-case.
+
+| Tool id | Command |
+|---|---|
+| `cv.list` | `tabbio cv list` |
+| `catalog.jobSearch` | `tabbio catalog job-search` |
+| `careerHighlight.upsert` | `tabbio career-highlight upsert` |
+| `publicProfile.builderGet` | `tabbio public-profile builder-get` |
+
+```sh
+tabbio cv list
+tabbio run cv.get --cv-id cv_123 --fields id,title,updatedAt
+tabbio catalog job-search --query "product manager" --locations Dubai --work-modes hybrid --limit 10
+tabbio run catalog.jobSearch --input '{"query":"data analyst","datePosted":"thisWeek"}' --json
+echo '{"cvId":"cv_123"}' | tabbio run cv.get -
+tabbio run cv.delete --cv-id cv_old            # approval-gated, see Approvals
+tabbio research web-search --query "UAE labour law changes 2026" --max-sources 3
+tabbio artifact generate-image --prompt "Dubai skyline at dawn, flat illustration" --title "Skyline" --yes --wait
+tabbio artifact create-page --input-file page.json --yes --wait   # title, designPlan, html
+tabbio site publish --artifact-id art_123 --name my-portfolio --yes
+```
+
+`--wait` does two things: it waits for an approval instead of exiting 6, and
+for the file tools (`artifact create-document`, `create-page`,
+`generate-image`, `edit-image`, `update-document`, `update-page`) it waits
+until the file has rendered (usually a few seconds; PDFs and images finish
+after the tool returns) and prints it with its final status, followed by
+`tabbio artifacts open <id>` / `download <id>` hints. With a personal token it
+polls the `artifact.get` tool; with a full sign-in, `GET /api/artifacts/:id`.
+The publishing tools, whose ids have no group (`publishArtifact`), are
+`tabbio site publish` and `tabbio site unpublish`.
+
+Input comes from flags, `--input '<json>'`, `--input-file path.json`, or `-`
+(stdin). Flags are generated from the tool's JSON Schema: strings and numbers
+take a value, booleans are switches, arrays repeat or take a comma list, and
+nested objects go through `--input`. In a terminal, missing required fields
+open a short form; without a terminal the command exits 2 and names them.
+
+### `workflows`
+
+```sh
+tabbio workflows
+# No workflows are exposed over MCP; multi-step flows run through tabbio chat
+```
+
+The Tabbio MCP server exposes the audited tools only. Server workflows (tailor
+a CV to a job, apply, outreach) are not published over MCP, because the
+workflow engine takes the user id from its input rather than from the signed-in
+caller. Ask for those flows in `tabbio chat`, where the server knows who you
+are, or call the individual tools (`tabbio cv tailor`, `tabbio catalog
+apply-prepare`, …).
+
+### `approvals`
+
+```sh
+tabbio approvals                         # pending approvals
+tabbio approvals show apr_123
+tabbio approvals approve apr_123 --reason "cleaning up old drafts"
+tabbio approvals approve apr_456 --wait   # a file tool: waits for the render and prints the file
+tabbio approvals reject apr_123
+tabbio approvals wait apr_123 --timeout 10m
+```
+
+See [Approvals](#approvals).
+
+### `ask`
+
+```sh
+tabbio ask "Which of my saved jobs fit my main CV best?"
+tabbio ask "Summarise my application pipeline" --json
+```
+
+One question, one answer. With an app session (browser or email sign-in) the
+question goes through the chat stream (`POST /api/agent/chat`), exactly like a
+one-message `tabbio chat`: the answer streams, sources and files are listed,
+and it is metered like any chat reply. It sends the profile's saved research,
+image and result choice.
+
+With a personal token, or with `--via-mcp`, it looks for the MCP ask tool
+(`ask_tabbio`) instead. Today's server does not offer that tool (the MCP
+endpoint exposes tools only), so that path exits 5 with "This Tabbio server
+does not offer the ask_tabbio tool". Use a full sign-in for `ask`.
+
+### `chat`
+
+```sh
+tabbio chat
+tabbio chat "Tailor my CV for the Careem PM role" --thread thr_123
+tabbio chat --mode employer --company cmp_456
+```
+
+Streaming chat with the Tabbio agent, rendered as Markdown, with one-line
+tool-call rows (`ctrl+o` expands them) and inline approval prompts. Inside
+chat, `/new`, `/threads`, `/mode`, `/model`, `/research`, `/image`,
+`/result`, `/help` and `/exit` are available. With `--json`, chat prints the
+stream as NDJSON: one JSON event per line, exactly as the server sent it
+(including event types this version does not know). Needs a full sign-in.
+
+```sh
+tabbio chat --research on "What changed in UAE labour law this year? Two sources."
+tabbio chat --result document "A one-page brief on my job search"
+tabbio chat --result page --save          # every chat on this profile asks for pages until changed
+```
+
+See [Research, documents, pages and images](#research-documents-pages-and-images).
+
+### `artifacts`
+
+```sh
+tabbio artifacts                                   # your files, newest first
+tabbio artifacts list --kind document --json
+tabbio artifacts get art_123
+tabbio artifacts open art_123                      # prints a 15-minute link and opens it (on a terminal)
+tabbio artifacts open art_123 --variant pdf --print
+tabbio artifacts download art_123                  # ./<title>.pdf (documents), .pptx (slides), .html (pages), the image
+tabbio artifacts download art_123 --format html --out ~/Downloads --force
+tabbio artifacts wait art_123 --timeout 2m         # exit 0 ready, 1 failed, 7 still rendering
+tabbio artifacts versions art_123
+tabbio artifacts restore art_123 ver_456           # a copy of that version becomes the newest
+tabbio artifacts delete art_123 --yes
+```
+
+The documents, slide decks, pages and images Tabbio made for you. `download`
+never overwrites a file unless you pass `--force`, writes through a temporary
+file, and names the file after the title. It fetches a signed link (15
+minutes) without sending your session to the storage host. `delete` asks
+first unless `--yes` (and a published site of that file goes offline). Needs a
+full sign-in; with a personal token, `tabbio artifact list|get|read` reach the
+same files through the tools.
+
+### `mcp serve` and `mcp url`
+
+```sh
+tabbio mcp url      # https://server.tabbio.com/api/mcp
+tabbio mcp serve    # stdio MCP server that forwards to the remote one
+```
+
+See [Using Tabbio from MCP clients](#using-tabbio-from-mcp-clients).
+
+### `completion`
+
+```sh
+tabbio completion zsh > "${fpath[1]}/_tabbio"
+tabbio completion bash > ~/.local/share/bash-completion/completions/tabbio
+tabbio completion fish > ~/.config/fish/completions/tabbio.fish
+```
+
+## Output and exit codes
+
+The output format is chosen in this order:
+
+1. a flag: `--json`, `--table` or `--plain`;
+2. the `TABBIO_OUTPUT` environment variable (`json`, `table` or `plain`);
+3. a terminal on stdout: human output (arrays of objects as tables, objects
+   as key/value panels, scalars as plain text);
+4. otherwise (piped or redirected): plain, tab-separated values, one record
+   per line, ready for `cut`, `awk` and `sort`.
+
+| Flag | Output |
+|---|---|
+| `--json` | JSON. Pretty in a terminal, compact when piped. Carries `meta.schemaVersion` (currently `1`); within a schema version fields are only ever added, never renamed or removed. |
+| `--table` | Force a table. |
+| `--plain` | Tab-separated values, no colour. |
+| `--fields a,b` | Only these fields (tables, plain and JSON). |
+
+`tabbio chat --json` is the exception: it writes NDJSON, one stream event per
+line.
+
+Colour is decided in this order: `--color` / `--no-color`, then `FORCE_COLOR`,
+then `NO_COLOR`, then `CLICOLOR_FORCE` / `CLICOLOR`, then `TERM=dumb` (no
+colour), then whether stdout is a terminal. The accent colour adapts to light
+and dark terminals; if it guesses wrong, set `TABBIO_THEME=light` or
+`TABBIO_THEME=dark`. The CLI never paints background colours.
+
+Errors print three parts: `✗ <title>`, a hint when there is one, and the
+request id when the server returned one. Quote the request id when you report
+a problem. Under `--json`, errors are JSON too, with `code`, `message`, `hint`,
+`retry` and `requestId`.
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Unexpected error |
+| 2 | Usage error (unknown flag, missing required input, no terminal for an interactive command) |
+| 3 | Not signed in, or the session could not be refreshed. Run `tabbio login`. |
+| 4 | Forbidden (token scope, plan, out of credits, or a support session) |
+| 5 | Not found |
+| 6 | Approval pending (the action is waiting for a person) |
+| 7 | Network error |
+| 8 | Server error |
+| 130 | Interrupted (Ctrl+C) |
+
+`tabbio help exit-codes` prints this table.
+
+## Profiles and files
+
+A profile is a named environment (API, app and MCP URLs) with its own
+credentials. `default` points at production, and a built-in `local` profile
+points at a development stack (`http://localhost:3001` for the API,
+`http://localhost:8081` for the app):
+
+| Setting | Production value |
+|---|---|
+| API | `https://server.tabbio.com` |
+| App (sign-in page) | `https://app.tabbio.com` |
+| MCP | `https://server.tabbio.com/api/mcp` |
+
+Files live in `$TABBIO_CONFIG_DIR`, else `$XDG_CONFIG_HOME/tabbio`, else
+`~/.config/tabbio`:
+
+| File | Contents | Mode |
+|---|---|---|
+| `config.json` | Profiles, the active profile, preferences, each profile's saved research / image / result choice | 0600 |
+| `credentials.json` | One entry per profile: the app session (access token and expiry, refresh token) or a personal MCP token, plus user id and email | 0600 (directory 0700) |
+
+The tool catalog cache, update-check stamp and recent-runs history live in
+`$TABBIO_CACHE_DIR`, else `$XDG_CACHE_HOME/tabbio`, else `~/.cache/tabbio`.
+
+Other environment variables:
+
+| Variable | Effect |
+|---|---|
+| `TABBIO_OUTPUT` | Default output format: `json`, `table` or `plain`. |
+| `TABBIO_THEME` | `light` or `dark`, when the accent colour guesses the terminal background wrong. |
+| `TABBIO_DEBUG=1` | Same as `--debug`. |
+| `TABBIO_DEVICE_LABEL` | The name this computer shows on the sign-in page and in your sessions. Defaults to the hostname. |
+| `TABBIO_NO_UPDATE_CHECK=1` | Skip the once-a-day check for a newer version on npm (printed on stderr). Also skipped under `CI`. |
+| `TABBIO_ALLOW_INSECURE_HTTP=1` | Allow plain `http://` API URLs other than localhost. Development only. |
+| `FORCE_HYPERLINK` | `1` to always print OSC 8 links (file previews, sources), `0` never. Default: detected from the terminal. |
+| `NO_COLOR`, `FORCE_COLOR`, `CLICOLOR`, `CLICOLOR_FORCE`, `TERM` | Colour, see [Output](#output-and-exit-codes). |
+| `DO_NOT_TRACK` | Honoured. The CLI sends no telemetry in any case; the only request that does not go to Tabbio is the update check, which `TABBIO_NO_UPDATE_CHECK` turns off. |
+
+## Approvals
+
+Some tools change things that are hard to undo or that reach other people.
+They never run straight from a tool call; they create an approval and wait for a
+person. On a server without PR #512, 57 of the 162 tools work this way,
+including:
+
+- deleting anything (`cv.delete`, `experience.delete`, `memory.forget`, `conversation.delete`…)
+- submitting or withdrawing applications (`catalog.applySubmit`, `application.submit`, `application.withdraw`)
+- sending messages, email or Slack posts (`message.send`, `conversation.send`, `connector.sendEmail`, `connector.postSlackMessage`)
+- sharing a CV or changing who can see it (`cv.shareLinkCreate`, `cv.accessGrantCreate`, `publicProfile.settingsUpdate`)
+- publishing (`job.publish`, `skills.publish`) and starting automations (`nova.activate`, `nova.runNow`)
+
+`tabbio tools --writes` lists write tools; `tabbio tools describe <id>` says
+whether a tool needs approval.
+
+**With a full sign-in, in a terminal**, the CLI shows the tool and its
+arguments beside a yellow `◆` rail and offers three numbered choices:
+**1 Approve** (`y`), **2 Reject** (`n`) and **3 Leave pending** (`l`, or
+Esc). Approve confirms the action with your own session (the same thing the
+Approve button in the app does) and prints the result. Reject cancels it.
+Leave pending exits with code 6 and the approval id.
+
+**Without a terminal**, or **with a personal token**, the CLI prints the
+approval id with a hint to approve it in the app, or with `tabbio approvals
+approve <id>` from a profile signed in with an app session (or to wait with
+`tabbio approvals wait <id>`), and exits with code 6.
+
+- `--wait` keeps the command alive until someone decides (polling every 3 s,
+  backing off to 10 s, up to `--timeout`), then prints the result.
+- `--yes` approves the approvals created by that one command without asking,
+  and only when a full sign-in is present. It applies to a single invocation;
+  there is no setting that auto-approves for a whole session. Use it in scripts
+  you trust; it is the terminal equivalent of pressing Approve.
+- Approvals created by any client (the CLI, Claude, Cursor…) also appear in the
+  app under Settings › MCP Access, where you can approve or reject them.
+
+## Limits
+
+The CLI spends the same credits as the app, from the same daily pool. On the
+Free plan that is **40 credits a day** (UTC day, refilled at 00:00 UTC), which
+comes to roughly:
+
+- **8 to 14 chat replies** (`tabbio chat`, `tabbio ask`; 4 if every reply is
+  tool-heavy): each reply costs 1 to 10 credits by its token use;
+- **1 skill run** (40 credits, only as the first spend of the day);
+- **1 CV tailoring from the CLI** (`tabbio cv tailor`, 30 credits).
+
+Tool calls (`tabbio <group> <action>`, `tabbio run`) are direct MCP calls.
+Most tools make no model call and cost nothing. The ones that do are metered
+on the server:
+
+| Tool | Cost | Plans |
+|---|---|---|
+| `cv.tailor` | 30 credits (priced like the browser extension's tailoring) | every plan |
+| `cv.sectionPreview`, and `cv.updateSummary` without `--summary` | 12 credits | every plan |
+| `message.draft` (employer) | 1 workspace AI action | every plan |
+| Skills, Application Studio, automations, and #512 research, images and files | what the app charges; those services meter themselves | as in the app |
+
+An approval-gated tool is charged when it is approved and runs, against the
+balance at that moment. When a call does not fit, the server refuses it before
+any model call with `SUBSCRIPTION_ENTITLEMENT_DENIED` and the time the pool
+refills, and the CLI exits 4:
+
+```
+✗ Out of credits. Tailor CV to a job page needs 30 credits; you have 10 left. Your daily pool refills at 2026-09-26 00:00 UTC.
+```
+
+Plus and Pro have larger pools (300 and 3,000 credits a day). The full table,
+per surface and per plan, is in `docs/cli/limits-audit.md`. On a local
+development API `TABBIO_DEV_BYPASS_PAYWALL=true` (the default in the
+development `.env`) switches all of this off; deployed servers ignore it.
+
+## Research, documents, pages and images
+
+When the server has them switched on (see `docs/cli/deployment-notes.md` §7),
+the Tabbio agent can search the web, read pages, PDFs and repositories, and
+make documents (HTML and PDF), slide decks (PPTX), web pages (HTML) and
+images. Three controls decide what each chat message may do, like the
+controls under the app's message box:
+
+| Control | Values | Meaning |
+|---|---|---|
+| Research (`--research`, `/research`) | `auto` · `on` · `off` | Search the web when it helps, always first, or never. |
+| Image (`--image`, `/image`) | `auto` · `on` · `off` | Images only when asked, on this message, or never. Uses image credits. |
+| Result (`--result`, `/result`) | `auto` · `summary` · `document` · `slides` · `page` · `image` | What to make: let the message decide, an answer in the chat, or that file. |
+
+They are sent with every message in seeker chats, together with your
+timezone (`Intl` timezone, so "today" and the daily limits follow your day).
+Employer chats do not send them; the server ignores them there. Flags apply to
+one run; `/research on` in the chat and `tabbio chat … --save` remember the
+choice for the profile (`profiles.<name>.capabilities` in `config.json`). The
+status bar shows every control you changed from `auto`. If your account
+cannot use a control you switched on (the server has it off, you are outside
+the canary, or it needs a paid plan), the chat says why and Tabbio answers
+without it.
+
+What you see in the chat:
+
+- **Research** as one activity row per call, e.g. `✓ Searched the web ·
+  "uae labour law" · 4 sources · 3.2s` (`ctrl+o` lists the queries and
+  sources), and a numbered **Sources** list after the answer. Where the
+  terminal supports OSC 8 links (iTerm2, WezTerm, kitty, Ghostty, VS Code,
+  Windows Terminal, recent GNOME Terminal; `FORCE_HYPERLINK=1` to force) the
+  titles are links; elsewhere the URL follows the title.
+- **Files** as a card row: `▤ Q3 brief · document · ready · art_12…9xyz
+  tabbio artifacts open art_…` (`▦` slides, `◫` page, `▣` image). A file that
+  is still rendering shows a spinner and the writer's progress (`writing ·
+  120 lines`) and turns ready by itself; its title then links to a preview.
+- **Limits** (daily quota, plan tier, a switched-off feature) as a dim line
+  under the tool row with the reason.
+
+`tabbio chat --json` passes every event through, including `artifact-draft`
+(the streaming writer's progress). Research sources are in the
+`tool-result` payloads of `webSearch`, `readUrl`, `readPdf`,
+`readGithubRepo` and `readSkill` (`result.sources`); files are in the
+`tool-result` payloads of `createDocument`, `createPage`, `generateImage`,
+`updatePage`, `updateDocument` and `editImage` (`result.artifactId`,
+`result.status`: `pending`, `ready` or `failed`).
+
+Over MCP (`tabbio research …`, `tabbio artifact …`, `tabbio site …`), the
+file tools and `site publish` always need your approval first, because they
+spend credits or put something on the web: in a terminal `--yes` approves
+them for that run, and `tabbio approvals approve <id> --wait` approves one
+later and waits for the file.
+
+## Using Tabbio from MCP clients
+
+Clients that support remote (HTTP) MCP servers should connect to Tabbio
+directly:
+
+```sh
+claude mcp add --transport http tabbio "$(tabbio mcp url)"
+```
+
+For clients that only launch local stdio servers, `tabbio mcp serve` is a
+bridge: it speaks MCP on stdin/stdout and forwards every request to the remote
+server with the CLI's credentials (the app session, refreshed as needed, or a
+personal token). Sign in once with `tabbio login` (or set `TABBIO_TOKEN`), then
+point the client at it:
+
+```json
+{
+  "mcpServers": {
+    "tabbio": {
+      "command": "npx",
+      "args": ["-y", "@tabbio-technologies/cli", "mcp", "serve"]
+    }
+  }
+}
+```
+
+Use `"args": ["-y", "@tabbio-technologies/cli", "mcp", "serve", "--profile", "staging"]` for
+another profile. The bridge writes nothing but protocol messages to stdout; logs
+go to stderr.
+
+## Security
+
+- **Credentials** are stored in `credentials.json` with mode 0600 in a 0700
+  directory, written through a temporary file and an atomic rename. `tabbio
+  doctor` warns when the permissions are looser. The file is plain JSON: anyone
+  who can read your home directory as you can use it. OS keychain storage is a
+  planned follow-up.
+- **Environment tokens** (`TABBIO_TOKEN`, `TABBIO_ACCESS_TOKEN`) are never
+  written to disk.
+- **Redaction:** the CLI never prints tokens. `--debug` output and error
+  messages redact `Bearer …` values, `tabbio_mcp_…` tokens, JWTs, refresh
+  tokens, one-time codes, `state` values and session cookies.
+- **Refresh tokens rotate** on every refresh, and reusing an old one revokes
+  the whole session family. The CLI saves the new one before using it, so a
+  crash between the two cannot lock you out.
+- **The browser hand-off** only ever sends its one-time code to
+  `http://127.0.0.1:<port>/callback`, and only after you press Approve on a page
+  that shows that address. The code lives 60 seconds and works once. The CLI
+  rejects a callback whose `state` does not match the one it generated.
+- **Support sessions** (a Tabbio admin viewing your account) cannot connect a
+  CLI, and their access tokens are refused by the MCP endpoint.
+- **Revoking access:**
+  - on the computer: `tabbio logout`;
+  - a lost or compromised computer: change your password. That ends every app
+    session at once, including the CLI's tool access, which otherwise keeps
+    itself signed in by refreshing;
+  - a personal token: revoke it in Settings › MCP Access.
+
+See `docs/cli/security-review.md` for the threat model.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `✗ Not signed in` / exit 3 / HTTP 401 | Run `tabbio login`. The refresh token was revoked (logout elsewhere, password change) or expired. |
+| `This MCP token does not allow writes` (or `…is not scoped to that company workspace`) | You are using a personal token that is read-only or scoped to other data. Run `tabbio login` for a full app session, or create a broader token in Settings › MCP Access. |
+| A personal token stopped working | Only one personal MCP token is active per account, so a newer one made in Settings replaced it. Run `tabbio login --with-token` with the new token, or switch to `tabbio login`. |
+| `chat` or `approvals approve` says it needs a full sign-in | The profile uses a personal token. Run `tabbio login` (browser or `--email`). |
+| Browser shows "This site can't be reached" at `127.0.0.1` | The CLI stopped waiting (5-minute timeout, Ctrl+C) or the browser is on a different computer. Run `tabbio login` again in the terminal, or use `--email` over SSH. |
+| "This sign-in link is not valid" | The link was edited or truncated. Run `tabbio login` again. |
+| `Access token has expired` right after login, or `doctor` reports clock skew | Your system clock is off. Enable automatic time sync and retry. |
+| Nothing works behind a corporate proxy | Node's built-in `fetch` does not read `HTTPS_PROXY` by default. On Node versions that support it (24.5 and later), set `NODE_USE_ENV_PROXY=1` along with `HTTPS_PROXY` and `NO_PROXY`. Keep `127.0.0.1` out of the browser's proxy so the sign-in hand-off can reach the CLI. |
+| Output has strange characters in CI logs | Pass `--no-color` or set `NO_COLOR=1`. |
+| `✗ Cannot GET /api/artifacts` (exit 5) | This Tabbio server predates documents, pages and images (PR #512). |
+| `Publishing is not available for this account yet.` / `… requires plus or higher.` (exit 4) | The server has that capability off for you (flag, canary or plan). The chat shows the same reason as a dim line. |
+| `artifacts download` says the file is still being created | Add `--wait`, or `tabbio artifacts wait <id>` first. |
+| `✗ Out of credits …` or `… requires plus or higher` (exit 4) | The daily pool is spent or the tool needs a paid plan. The message says when the pool refills. See [Limits](#limits). |
+| `This Tabbio server does not offer the ask_tabbio tool` (exit 5) | `ask` with a personal token or `--via-mcp`. Sign in with `tabbio login` and ask without `--via-mcp`. |
+| `tabbio workflows` lists nothing | Expected: workflows are not exposed over MCP. Use `tabbio chat`. |
+
+`tabbio doctor` checks most of this for you. `tabbio --debug <command>` shows
+every request (redacted) with its status and request id.
+
+## Screenshots
+
+Captured from the real CLI against a local API, in the repository under
+`qa-artifacts/cli-2026-09-25/`:
+
+| File | What it shows |
+|---|---|
+| `01-web-cli-connect-consent.jpg`, `02-web-cli-connect-done.jpg` | The browser consent page and its done state |
+| `10-status.png` to `14-tools-cv.png` | `status`, `doctor`, `tools describe`, `cv list` as a table, `tools cv` |
+| `20-home.png`, `21-tools-browser.png`, `22-chat.png` | The interactive home screen, tool browser and chat |
+| `30-out-of-credits.png` | A second `cv.tailor` refused on a free account (exit 4) |
+| `40-artifacts-list-512.png`, `41-chat-research-512.png` | `artifacts list` and a researched chat answer against a PR #512 API |
+
+## Contributing
+
+The CLI lives in `apps/cli` in the Tabbio monorepo.
+
+```sh
+pnpm install
+pnpm dev:cli -- status                         # run from source (tsx)
+pnpm --filter @tabbio-technologies/cli test                 # vitest
+pnpm --filter @tabbio-technologies/cli type-check
+pnpm --filter @tabbio-technologies/cli lint
+pnpm --filter @tabbio-technologies/cli build                # esbuild (scripts/build.mjs) → dist/cli.js
+
+# against a local API (port 3001) and app-web (port 8081)
+node apps/cli/dist/cli.js --profile local login
+```
+
+- `src/core` holds everything that talks to the network or the disk (config,
+  credentials, HTTP, auth, MCP, catalog, approvals, chat stream, errors,
+  output). Pure logic there needs a unit test.
+- `src/commands` wires commander commands to `core`.
+- `src/ui` is the Ink interface. It is only ever rendered in a terminal; every
+  command has a plain-text path for pipes and CI. Colours come only from
+  `src/ui/theme.ts`: no hex literals or background colours anywhere else.
+- The browser half of `tabbio login` is the `/cli/connect` page in
+  `apps/mobile` (`src/app/cli/connect`, `src/components/cli`,
+  `src/lib/cli-connect.ts`).
+- The server side the CLI depends on lives in `apps/api`: the app access
+  token on `/api/mcp` (`src/mastra/mcp/oauth.ts`), credit metering for direct
+  MCP calls (`src/mastra/tools/shared.ts`) and the tools-only MCP server
+  (`src/agent/mastra-agent.service.ts`). Raise any new server need before
+  building around it.
+
+Release steps are in `docs/cli/release-checklist.md` and
+`docs/cli/deployment-notes.md`.