2kw.ai CLI
The command-line interface for 2kw.ai — the EU-hosted AI integration platform. Run schema-driven document extraction, route LLM calls through an OpenAI-compatible gateway, transcribe audio, and manage prompts, datasets, and experiments — from your terminal or inside agentic workflows.
Installs three equivalent binaries: 2kw, backbone, and bb.
Installation
# Latest stable release
npm install -g @2kw/ai
# Pre-release (dev channel)
npm install -g @2kw/ai@dev
The CLI notifies you when a newer version is available.
Quick Start
# Authenticate — opens your browser, no API key needed (7-day free trial)
2kw auth login
# Define a schema and run an extraction
2kw schemas create -n "Invoice"
2kw extractions create --schema <id> -m gpt-4o --text "Invoice #123, Total: €500"
# Convert and transcribe
2kw convert file report.docx --format md
2kw transcribe call.mp3 --format srt
# Chat through the gateway
2kw ai chat -m gpt-4o --message "Draft a summary of this quarter's extraction volume"
All commands work identically as bb for quick access — e.g. bb schemas list.
Authentication
Sign in via the browser (recommended):
2kw auth login
This opens your browser, asks you to confirm a short code, and signs the CLI
in with your user account — no API key to copy. Your session lasts 7 days of
inactivity and renews itself while you keep using the CLI. If you belong to
several organizations you pick one at login, and can switch any time with
2kw context set-org — no re-login needed. 2kw auth logout clears the local
credentials and signs the session out server-side (best-effort).
For CI, scripts, or air-gapped machines, store an org API key instead (create one under Settings → API Keys in the web app):
2kw auth login --api-key sk_... # save a key directly
2kw auth login --manual # prompted setup (legacy flow)
Explicit API keys always take priority over a stored browser session (highest priority first):
| Method | Example |
|---|---|
| CLI flags | --api-key sk_... --base-url https://... |
| Environment variables | AI_2KW_API_KEY, AI_2KW_BASE_URL (legacy: BACKBONE_*) |
Local .2kw file | JSON file in the current directory (legacy: .backbone) |
| Config store | Set via 2kw auth login (browser session or saved key) |
2kw auth status # Verify credentials (works for both auth types)
2kw auth logout # Clear credentials and send a server-side sign-out
Note: config get apiKey --json returns a masked value — stored secrets do
not round-trip through stdout by default. Scripts needing the raw key pass
--reveal (config get apiKey --reveal) or use AI_2KW_API_KEY.
Contexts
kubectl-style contexts switch between organizations and environments:
2kw context list # List all contexts
2kw context use acme-corp # Switch active context
2kw context create staging --base-url https://api.staging.example # Create a context, sign in through the browser
2kw context create ci --api-key sk_... # Or store an API key instead
2kw config set memory true makes an API-key context send X-Backbone-Memory: enabled on ai respond and agents run calls, which opts those runs into agent memory; AI_2KW_MEMORY=true|false overrides it per shell. Runs from a browser-login (session) context are always eligible for agent memory regardless of this setting, so memory false only affects API-key contexts.
Commands
| Command | Description |
|---|---|
auth | Login, logout, and check auth status |
config | Get, set, and list configuration values |
context | Manage contexts for multiple orgs/environments |
schemas | Manage schemas, versions, labels, validation, and testing |
prompts | Versioned prompt management, labels, compilation, testing |
extractions | Create extractions (text, file, images), list, re-run, estimate tokens |
convert | Convert PDF, DOCX, XLSX, images, and 20+ formats to Markdown/text/HTML/JSON |
ai | Chat completions, Responses (agent or direct model), and model listing via the OpenAI-compatible gateway |
transcribe | Transcribe audio (FLAC, MP3, MP4, OGG, WAV, WebM) |
datasets | Build datasets and dataset versions for evaluation |
experiments | Run experiments against datasets |
evaluators | Manage evaluator templates |
scores | Record and inspect quality scores |
tracing | Inspect request traces and tracing settings |
memory | Your agent memory files (list, read, write, delete, forget); member totals and erasure for admins |
providers | Manage BYOK AI providers |
analytics | Usage analytics: operations, tokens, quality, providers, errors |
billing | Check subscription tier and usage limits |
agents | Run agents and answer paused runs (approvals and relayed tool calls); apply, export and scaffold agent.yaml; manage versions, labels, approvals and tool catalogs |
skills | Import and export SKILL.md bundles; manage skill versions and labels |
plugins | Install plugin repositories, sync them, and inspect their reports |
conversations | Create and manage conversations and their items |
knowledge | Manage knowledge bases, documents, search, and citations |
files | Upload, download, and manage files |
installations | Manage surface installations, keys, origins, and pairing |
docs | Browse API documentation from the terminal |
Global Options
| Flag | Description |
|---|---|
--api-key <key> | Override the API key |
--base-url <url> | Override the base URL (defaults to the 2kw.ai cloud API) |
--json | Output raw JSON instead of formatted tables — built for scripting and agents |
--no-color | Disable colored output |
Why 2kw.ai
- EU data residency — built-in models run GDPR-compliant and EU-hosted, operated by Manfred Kunze Development GmbH (Germany)
- Grounding scores — every extracted value links back to where it came from in the source document
- One platform — gateway, extraction, transcription, and observability share one API and one bill
Related
- 2kw.ai — platform overview and pricing
- Documentation — full command and API reference
@2kw/ai-mcp-server— the 2kw.ai MCP server for Claude Code, Cursor, and Windsurf
License
Proprietary — see LICENSE for details.