Command-line interface for Kablewy — upload documents, search your knowledge base, chat with context, call tools, and script repeatable AI workflows.
npm install -g @kablewy/clikablewy 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 modeAdd --json to any automation-capable command when its output feeds another script:
kablewy status --json
kablewy docs list --json
kablewy chat --message "Return the top three open questions" --jsonNode.js >= 18. macOS and Linux are supported; Windows is not yet tested.
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.
npm install -g @kablewy/cli@latestSet KABLEWY_DISABLE_UPDATE_CHECK=1 to disable update checks. Notices are suppressed in CI, non-interactive output, and JSON mode.
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.
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 possibleAPI key inventory lives under auth keys:
kablewy auth keys list
kablewy auth keys revoke <keyId>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=....
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.
Most users only need kablewy login. Use config to inspect local settings, validate required values, or set support-directed overrides.
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=<org-id>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:
kablewy --api-url https://kablewy.ai --org-id <org-id> --user-id <user-id> --api-key <api_-scoped-key> status --jsonHuman output and verbose diagnostics redact bearer tokens, refresh tokens, API keys, cookies, authorization headers, and related secret fields.
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.
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.
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.
kablewy status
kablewy status --health
kablewy status --tools
kablewy status --jsonDocument commands live under docs (top-level upload remains a compatibility alias). Supported extensions include PDF, Word, PowerPoint, Markdown, text, CSV, and Excel.
kablewy docs upload ./documents/*.pdf
kablewy docs upload ./documents ./notes/*.md --parse-mode balanced --concurrency 4
kablewy docs upload ./documents/*.pdf --dry-runUpload 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).
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:
kablewy docs list --limit 50 --json
kablewy docs search "termination clause" --limit 5 --json
kablewy docs get <documentId>
kablewy docs status <documentId>
kablewy docs delete <documentId> --yes # prompts without --yesContainer-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.
export KABLEWY_DOC_WORKER_URL=https://doc-worker.example.com
export KABLEWY_DOC_PROCESSOR_TOKEN=<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.
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" --jsonUseful options:
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" --streamkablewy 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.
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:
@ 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:
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 onlyDangerous 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 expose the Kablewy MCP integrations available to the configured organization and user. Use tools describe <toolName> --schema before scripting a direct call.
kablewy tools list --search document
kablewy tools list --server kablewy --json
kablewy tools describe <toolName> --schema
kablewy tools call <toolName> --args '{"query":"renewal terms"}'
kablewy tools call <toolName> --interactive
kablewy tools test # probes each server; exits 70 if any is unreachablemcp 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:
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 <remote-mcp-token>'
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 --yesDeploy a Kablewy-hosted catalog server:
kablewy mcp catalog list
kablewy mcp catalog show wheniwork
kablewy mcp catalog deploy wheniwork --credentials ./wheniwork-credentials.json
kablewy mcp deployment status <serverId>
kablewy mcp deployment upgrade <serverId>
kablewy mcp deployment stop <serverId> --yes
kablewy mcp deployment delete <serverId> --yesDeploy a custom MCP worker module:
kablewy mcp deploy ./dist/worker.mjs \
--name customer-crm \
--description "Customer CRM lookup and renewal workflows" \
--tool-prefix crmThe 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 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.
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 <taskId> --jsonUse --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.
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).
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 <destinationId>
kablewy webhooks test <destinationId> --event quick_action.completed
kablewy webhooks deliveries <destinationId>
kablewy webhooks delete <destinationId> --yes
kablewy webhooks trigger <jobId> --payload ./event.jsonCustom headers and auth config can be attached when the destination requires them:
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=<remote-webhook-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 is the canonical command group (skill is a compatibility alias).
kablewy skills list --json
kablewy skills show <skillId>
kablewy skills create <skillId> --name "Renewal Review"
kablewy skills upload <skillId> ./bundle.zip --version 0.1.0
kablewy skills execute <skillId> --runtime python --entry main.py
kablewy skills execute <skillId> --args '["customer-a"]' --json
kablewy skills versions <skillId>
kablewy skills delete <skillId> --force # prompts without --forceAutomation-capable commands support --json with a stable envelope:
{ "success": true, "data": {} }{
"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).
# 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=<api_-scoped-key> \
KABLEWY_ORG_ID=<org-id> \
KABLEWY_USER_ID=<user-id> \
KABLEWY_CONFIG_DIR=/tmp/kablewy-cli-config \
kablewy docs list --json0.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.
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 <sessionId>.
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.
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 identityIf a backend or network command fails, rerun with --json and include error.requestId in the support request when present.
Report bugs and feature requests at github.com/KablewyAI/kablewy-cli/issues. See CHANGELOG.md for release history.
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/ so documentation changes can be reviewed with code before being published to the GitHub wiki.
Do not publish from this checklist unless release approval is explicit.
npm run build
npm run test:ci
npm audit --omit=dev --json
npm pack --dry-run --json
npm run preflight:npmBefore 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.