# Kablewy CLI Command-line interface for Kablewy — upload documents, search your knowledge base, chat with context, call tools, and script repeatable AI workflows. [![npm version](https://img.shields.io/npm/v/%40kablewy%2Fcli.svg)](https://www.npmjs.com/package/@kablewy/cli) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/KablewyAI/kablewy-cli/blob/main/LICENSE) [![node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org) ## Install ```bash npm install -g @kablewy/cli ``` ## 60-second quickstart ```bash kablewy login # sign in, store a scoped API key kablewy docs upload ./documents/*.pdf # upload documents kablewy docs search "renewal terms" # search the knowledge base kablewy chat --message "Summarize the renewal risk" # one-shot chat with context kablewy agent # beta local terminal agent mode ``` Add `--json` to any automation-capable command when its output feeds another script: ```bash kablewy status --json kablewy docs list --json kablewy chat --message "Return the top three open questions" --json ``` ## Requirements & platform support Node.js `>= 18`. macOS and Linux are supported; **Windows is not yet tested**. ## Updates The CLI never auto-updates itself. In interactive terminals, it may check npm at most once per day and print a short notice when a newer version is available. ```bash npm install -g @kablewy/cli@latest ``` Set `KABLEWY_DISABLE_UPDATE_CHECK=1` to disable update checks. Notices are suppressed in CI, non-interactive output, and JSON mode. ## Authentication `kablewy login` signs you in and stores a scoped API key for CLI use. If an existing Kablewy desktop session is available, the CLI can reuse it. Otherwise it opens Kablewy in your browser, uses your normal web login/SSO/MFA session, and returns a one-time OAuth code to the CLI through a local loopback callback. ```bash kablewy login kablewy login --no-browser # print the authorization URL instead of opening it kablewy login --loopback --email you@example.com # legacy email-link fallback kablewy login --ttl 12h --name "CI smoke key" kablewy whoami # verifies the active credential with a real request kablewy logout # clears local credentials, revokes the key when possible ``` API key inventory lives under `auth keys`: ```bash kablewy auth keys list kablewy auth keys revoke ``` If your organization requires MFA, run the default browser-based `kablewy login` flow. The CLI does not collect MFA codes itself; Kablewy handles MFA in the browser before returning to the local CLI callback. The legacy `--loopback` email-link fallback is not MFA-capable. Normal CLI commands use only scoped Kablewy API keys that start with `api_`. Browser, desktop, magic-link, and refresh tokens are used only during `kablewy login` and are rejected if passed through `--api-key`, `KABLEWY_API_KEY`, or `config --set apiKey=...`. ## Kablewy service The public CLI connects to the Kablewy production service at `https://kablewy.ai`. Customers do not need to choose an environment. Run `kablewy login`, then use the commands normally. ## Configuration Most users only need `kablewy login`. Use `config` to inspect local settings, validate required values, or set support-directed overrides. ```bash kablewy config --show kablewy config --init # write the default config file kablewy config --validate # exits 2 when required fields are missing/invalid kablewy config --get apiUrl kablewy config --set orgId= ``` Environment variables for CI or one-off shells: `KABLEWY_API_URL`, `KABLEWY_ORG_ID`, `KABLEWY_USER_ID`, `KABLEWY_API_KEY`. Set `KABLEWY_CONFIG_DIR` to read and write config in an isolated directory so automation never touches your personal CLI profile. Global flags override config for a single invocation and are positional — place them before the subcommand: ```bash kablewy --api-url https://kablewy.ai --org-id --user-id --api-key status --json ``` Human output and verbose diagnostics redact bearer tokens, refresh tokens, API keys, cookies, authorization headers, and related secret fields. ## Security boundary The CLI is a Node.js program that runs on your machine with your user's filesystem and network permissions. It is not a sandbox and does not run inside Wasm. Treat file uploads, local config, shell history, external MCP headers, and any local MCP process you configure as part of your own trusted environment. `kablewy agent` includes a local safety harness: command approval by default, command risk classification, working-directory boundaries, command timeouts, output caps, redacted audit logs, and explicit escape hatches. Approved commands still run with your normal local permissions. Hosted skill and MCP execution runs on Kablewy's platform; the CLI only packages, configures, and invokes those platform surfaces. ## Privacy-safe reliability telemetry Kablewy API requests include minimal CLI metadata for support and product reliability: the package version, `cli` as the client type, and the command family such as `docs.upload`, `chat`, or `agent`. The same command family is included in the `User-Agent` so Kablewy support can find CLI traffic in Cloudflare logs by request ID, version, and command surface. The CLI does **not** send prompts, document contents, file paths, shell commands, stdout/stderr, environment variables, local audit logs, API keys, bearer tokens, cookies, or MCP auth headers as telemetry. In `kablewy agent`, each model turn includes a compact local workspace snapshot as model context: cwd, platform, git root when available, top-level entries, key project files, and lightweight package metadata. Local tool results are also sent as model context when needed to answer your request, for example when you ask the agent to read a file, list a directory, or inspect command output. To omit the Kablewy-specific client metadata entirely, set `KABLEWY_DISABLE_TELEMETRY=1`. External MCP servers configured through `kablewy mcp connect` do not receive Kablewy telemetry headers. The CLI only adds those headers to Kablewy API/MCP endpoints. ## Status Run `status` first when setting up a machine or debugging client access. It validates required configuration, backend reachability, credential validity, and tool discovery, and exits `0` when overall health is healthy or degraded and `1` when any check is unhealthy. ```bash kablewy status kablewy status --health kablewy status --tools kablewy status --json ``` ## Documents Document commands live under `docs` (top-level `upload` remains a compatibility alias). Supported extensions include PDF, Word, PowerPoint, Markdown, text, CSV, and Excel. ```bash kablewy docs upload ./documents/*.pdf kablewy docs upload ./documents ./notes/*.md --parse-mode balanced --concurrency 4 kablewy docs upload ./documents/*.pdf --dry-run ``` Upload sessions are persisted so interrupted uploads can be inspected or resumed. `--resume-from` re-queues pending and failed files, so it is the standard way to retry failures. `docs upload` exits `1` when any file fails (and `0` for success and `--dry-run`). ```bash kablewy docs upload ./documents/*.pdf --session-id client-renewal-q2 kablewy docs upload ./documents/*.pdf --resume-from client-renewal-q2 kablewy docs status ``` `--skip-existing` computes each file's SHA-256 and skips files the backend already has (recorded as `skipped` in the session manifest). If the existence check itself fails, the CLI fails open and uploads the file. List, search, inspect, and delete: ```bash kablewy docs list --limit 50 --json kablewy docs search "termination clause" --limit 5 --json kablewy docs get kablewy docs status kablewy docs delete --yes # prompts without --yes ``` Container-routed ingestion is an enterprise/private deployment path. It only works when Kablewy has explicitly provisioned a dedicated document-processing worker endpoint and a processor token for that customer or deployment. Normal users should use `kablewy docs upload` without `--use-container`. ```bash export KABLEWY_DOC_WORKER_URL=https://doc-worker.example.com export KABLEWY_DOC_PROCESSOR_TOKEN= kablewy docs upload ./documents/*.pdf --use-container ``` `--use-container` requires both `KABLEWY_DOC_WORKER_URL` and `KABLEWY_DOC_PROCESSOR_TOKEN` (or the matching CLI flags). The CLI will not fall back to your normal scoped API key for this path. ## Chat ```bash kablewy chat # interactive session kablewy chat --session renewal-review kablewy chat --message "Summarize the uploaded renewal documents" # one-shot kablewy chat --message "Find contract risk and cite titles" --json ``` Useful options: ```bash kablewy chat --message "Draft next steps" --model gpt-5.4 kablewy chat --message "Use the customer lookup tool" --tools '["customer_lookup"]' kablewy chat --message "Use these tool definitions" --tools-json ./tools.json kablewy chat --message "Stream the answer" --stream ``` ## Agent `kablewy agent` starts a beta local terminal agent mode. It is useful for project inspection, local file reads/searches, root-bound file writes/edits, approved shell commands, local file attachments, Kablewy context, and model-switched terminal sessions. It is not intended to be full Claude Code parity in `0.1.x`. ```bash kablewy agent kablewy agent --model gpt-5.4 kablewy agent --cwd ~/projects/acme-renewal kablewy agent --self-test kablewy agent --tools '["customer_lookup"]' ``` Inside the agent: ```text @ src/index.ts attach a local file to the next message ! npm test propose a local shell command; approval is required /model gpt-5.4 switch the model for future turns /help show agent controls ``` The agent can list, recursively inventory, read, search, write, and edit files during agent turns. File changes are constrained to the agent root by default. Every agent turn includes a compact local workspace snapshot: cwd, platform, git root when available, top-level entries, key project files, and lightweight package metadata. The snapshot is only orientation. Agent mode can use Kablewy/cloud tools for documents, integrations, and platform resources, and it always includes the local tool set (`Read`, `Write`, `Edit`, `Grep`, `LS`, `Inventory`, and `Bash`) for local workspace interaction. For direct local requests such as `pwd`, checking a named subdirectory, reading a named file, recursively inventorying a project, or writing a test file and reading it back, the CLI can also run a targeted local operation before the model response and give that result to the model. Truncated listings are treated as incomplete: follow-up path questions run fresh targeted checks instead of inferring that a missing path does not exist. Common read-only shell requests such as `pwd`, `ls`/`dir`, and `cat`/`type` are handled portably by the CLI when possible, so basic inspection works across macOS, Linux, and Windows. Autonomous shell execution is restricted to read-only commands; mutating or dangerous shell commands must go through the explicit `!` approval flow. Use `--allow-shell-without-confirmation` only in trusted local sessions where immediate `!` command execution is expected. Run `kablewy agent --self-test` to verify local agent tools before a client session. It writes, reads, edits, searches, lists, runs read-only shell checks, and confirms outside-root writes plus unsafe autonomous shell commands are blocked, then cleans up its temporary test directory. Local safety options: ```bash kablewy agent --self-test # verify local file/shell tools and safety blocks kablewy agent --self-test --json # machine-readable self-test result kablewy agent --cwd ./project # set the agent root kablewy agent --shell-timeout-ms 120000 # default command timeout kablewy agent --max-output-bytes 262144 # retained stdout/stderr cap per stream kablewy agent --audit-log .kablewy/session.jsonl # redacted JSONL audit log path kablewy agent --no-audit-log # disable local audit logging kablewy agent --allow-outside-cwd # allow attachments/commands outside cwd kablewy agent --allow-dangerous-shell # allow dangerous commands after confirmation kablewy agent --allow-shell-without-confirmation # trusted sessions only ``` Dangerous shell patterns such as `sudo`, `rm -rf`, `git reset --hard`, `git clean -fd`, `curl | sh`, recursive permission changes, and disk/system commands are blocked unless `--allow-dangerous-shell` is set. Commands that appear to leave the agent root are blocked unless `--allow-outside-cwd` is set. ## Tools Tools expose the Kablewy MCP integrations available to the configured organization and user. Use `tools describe --schema` before scripting a direct call. ```bash kablewy tools list --search document kablewy tools list --server kablewy --json kablewy tools describe --schema kablewy tools call --args '{"query":"renewal terms"}' kablewy tools call --interactive kablewy tools test # probes each server; exits 70 if any is unreachable ``` ## MCP servers `mcp` is the first-class surface for MCP servers: connect an externally hosted server, deploy a Kablewy-hosted catalog server, deploy a custom worker module, or manage hosted deployment lifecycle. Connect a server you host elsewhere: ```bash kablewy mcp test https://crm.example.com/mcp kablewy mcp connect customer-crm \ --url https://crm.example.com/mcp \ --tool-prefix crm \ --header 'Authorization=Bearer ' kablewy mcp list kablewy mcp health customer-crm kablewy mcp tools customer-crm kablewy mcp show customer-crm kablewy mcp disconnect customer-crm kablewy mcp remove customer-crm --yes ``` Deploy a Kablewy-hosted catalog server: ```bash kablewy mcp catalog list kablewy mcp catalog show wheniwork kablewy mcp catalog deploy wheniwork --credentials ./wheniwork-credentials.json kablewy mcp deployment status kablewy mcp deployment upgrade kablewy mcp deployment stop --yes kablewy mcp deployment delete --yes ``` Deploy a custom MCP worker module: ```bash kablewy mcp deploy ./dist/worker.mjs \ --name customer-crm \ --description "Customer CRM lookup and renewal workflows" \ --tool-prefix crm ``` The worker module must be a built ES module exporting a Worker `fetch` handler that implements MCP JSON-RPC methods such as `initialize`, `tools/list`, `tools/call`, and `ping`. OAuth catalog templates require browser OAuth setup in the Kablewy app in the `0.1.x` beta; after setup, manage them from the CLI as usual. ## Quick Actions Quick Actions are published, repeatable agent runs configured for an organization. They create a background chat, dispatch the agent task, and can emit `quick_action.completed` / `quick_action.failed` webhook events. ```bash kablewy quick-actions list kablewy quick-actions run renewal-review --input "Review Acme renewal" kablewy quick-actions run "Renewal Review" --context ./context.json --wait kablewy quick-actions status --json ``` Use `--context` for structured JSON context (account IDs, CRM record IDs, run metadata). Long-running actions return a `taskId`; recheck with `quick-actions status`. Use `--callback-url` / `--callback-secret` only when the receiving system verifies signed task callbacks. ## Webhooks Webhook commands manage outbound destinations and can manually trigger webhook-enabled Automation Jobs. Destinations receive signed Kablewy events (Quick Action, document, chat, MCP, tool, Automation Job, A2A). ```bash kablewy webhooks list kablewy webhooks create \ --name CRM \ --url https://hooks.example.com/kablewy \ --event quick_action.completed \ --event quick_action.failed kablewy webhooks show kablewy webhooks test --event quick_action.completed kablewy webhooks deliveries kablewy webhooks delete --yes kablewy webhooks trigger --payload ./event.json ``` Custom headers and auth config can be attached when the destination requires them: ```bash kablewy webhooks create \ --name "Customer Automation" \ --url https://hooks.example.com/kablewy \ --event automation_job.completed \ --header 'X-Customer=acme' \ --auth-type bearer \ --auth 'token=' ``` The API returns a webhook signing secret on create. CLI output redacts secret fields, so configure HMAC verification through the Kablewy app or a controlled API workflow when the receiver needs the raw secret. ## Skills `skills` is the canonical command group (`skill` is a compatibility alias). ```bash kablewy skills list --json kablewy skills show kablewy skills create --name "Renewal Review" kablewy skills upload ./bundle.zip --version 0.1.0 kablewy skills execute --runtime python --entry main.py kablewy skills execute --args '["customer-a"]' --json kablewy skills versions kablewy skills delete --force # prompts without --force ``` ## JSON and exit codes Automation-capable commands support `--json` with a stable envelope: ```json { "success": true, "data": {} } ``` ```json { "success": false, "error": { "code": "AUTH_ERROR", "message": "Authentication failed", "requestId": "request-id-when-available" } } ``` Exit codes are stable by category: | Code | Meaning | | --- | --- | | `0` | Success | | `1` | Unexpected failure | | `2` | Usage or validation error | | `65` | Authentication error | | `66` | Not found | | `70` | Network or backend error | | `77` | Permission error | Three diagnostics also reflect their findings in the exit code: `status` exits `1` when overall health is unhealthy, `config --validate` exits `2` when the configuration is invalid, and `tools test` exits `70` when any server fails its connectivity probe. `docs upload` exits `1` when any file in the batch fails, and `skills` subcommand failures map onto the table above (for example `404` exits `66` and network failures exit `70`). ## Scripting patterns ```bash # Gate a batch job on healthy credentials (status exits nonzero when unhealthy) kablewy status --json # Upload, then search kablewy docs upload ./client-docs/*.pdf --concurrency 3 kablewy docs search "open obligations" --limit 10 --json # Run a published Quick Action and wait for the result kablewy quick-actions run renewal-review \ --input "Review Acme renewal" \ --context ./acme-renewal-context.json \ --wait --json # Non-persistent overrides for CI KABLEWY_API_KEY= \ KABLEWY_ORG_ID= \ KABLEWY_USER_ID= \ KABLEWY_CONFIG_DIR=/tmp/kablewy-cli-config \ kablewy docs list --json ``` ## Public beta scope `0.1.x` is a public beta for deterministic client workflows, not full web-app parity. The public command surface is: `login` / `logout` / `whoami`, `auth keys list|revoke`, `docs upload|list|search|get|delete|status` (with top-level `upload` alias), `chat`, `agent`, `tools`, `mcp`, `quick-actions`, `webhooks`, `skills` (with `skill` alias), `config`, and `status`. The first beta intentionally does not expose plugin management, graph exploration, workcells, image/video generation, queue/log inspection, full workflow-job authoring, or admin command groups. OAuth entry for MCP catalog templates remains app-led in `0.1.x`. ## Troubleshooting **Authentication errors (exit `65`).** Your stored key is missing, expired, revoked, or not a scoped `api_` key. Re-run `kablewy login`, then verify with `kablewy whoami --json`. If a browser cannot be opened automatically, run `kablewy login --no-browser` and paste the printed URL into your browser. **429 / rate limiting on bulk uploads.** `docs upload` retries rate-limited files automatically (default 3 attempts, configurable with `--retry` / `--retry-delay`), honors the server's `Retry-After` header (capped at 60 s), and adaptively backs off concurrency on repeated errors. For large batches, lower `--concurrency` and resume any remaining failures with `--resume-from `. **CI isolation.** Set `KABLEWY_CONFIG_DIR` to a throwaway directory so CI jobs never read or write your real CLI config, and pass a scoped `api_` key via `KABLEWY_API_KEY` with `KABLEWY_ORG_ID` / `KABLEWY_USER_ID` environment variables. **General checks.** ```bash kablewy --help # command discovery kablewy config --show # local configuration kablewy config --validate # exits 2 when invalid kablewy status --json # connectivity + credentials kablewy whoami --json # active identity ``` If a backend or network command fails, rerun with `--json` and include `error.requestId` in the support request when present. ## Issues & feedback Report bugs and feature requests at [github.com/KablewyAI/kablewy-cli/issues](https://github.com/KablewyAI/kablewy-cli/issues). See [CHANGELOG.md](https://github.com/KablewyAI/kablewy-cli/blob/main/CHANGELOG.md) for release history. ## Documentation This README is the npm landing page. The GitHub wiki contains the expanded CLI guide, command workflows, troubleshooting, and release runbook. The wiki source lives in [`wiki/`](./wiki/) so documentation changes can be reviewed with code before being published to the GitHub wiki. ## License [MIT](https://github.com/KablewyAI/kablewy-cli/blob/main/LICENSE) --- ### Maintainer release checklist Do not publish from this checklist unless release approval is explicit. ```bash npm run build npm run test:ci npm audit --omit=dev --json npm pack --dry-run --json npm run preflight:npm ``` Before release, also run an installed-tarball smoke test, scan the source and packed artifact for secrets, and complete an authenticated smoke against a test organization.