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. Scripts needing the raw key should use AI_2KW_API_KEY or read the config file (path shown by config list).

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    # Create a new context

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, streaming), 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 | | providers | Manage BYOK AI providers | | analytics | Usage analytics: spend, quality, providers, errors | | billing | Check subscription tier and usage limits | | agents | Manage agents, versions, labels, approvals, and tool catalogs | | 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.