CLI

Manage your 2kw.ai schemas, prompts, extractions, and more — straight from the terminal.

Overview

The 2kw.ai CLI (backbone / bb) gives you full access to the platform without leaving your terminal. Define schemas, run extractions, convert documents, chat with AI models, and manage your entire workflow from the command line.

Installation

Install the CLI globally via npm:

# Latest stable release
npm install -g @manfred-kunze-dev/backbone-cli

# Pre-release (dev channel)
npm install -g @manfred-kunze-dev/backbone-cli@dev

The CLI will notify you when a newer version is available.

Verify the installation:

backbone --version

Short alias

The CLI is also available as bb for quick access — e.g. bb schemas list.

Updating

Update to the latest version:

npm update -g @manfred-kunze-dev/backbone-cli

The CLI automatically checks for newer versions and will notify you when an update is available.

Authentication

Get an API key

Head to the API Keys page in the sidebar and create a new key. Copy it — you'll need it for login.

Log in

backbone auth login

You'll be prompted for your base URL and API key. Credentials are stored locally in ~/.config/backbone/config.json.

Verify

backbone auth status

This validates your credentials against the API and shows available models.

You can also authenticate via environment variables or CLI flags:

Method	Example
Environment variables	`BACKBONE_API_KEY=sk_...` `BACKBONE_BASE_URL=https://...`
CLI flags	`--api-key sk_... --base-url https://...`
Local config file	`.backbone` JSON file in the current directory

Commands

Global Options

Flag	Description
`--api-key <key>`	Override the API key
`--base-url <url>`	Override the base URL
`--json`	Output raw JSON instead of formatted tables
`--no-color`	Disable colored output

Schemas

Define and manage extraction schemas within your organization.

backbone schemas list
backbone schemas get <schemaId>
backbone schemas create -n "Invoice Schema"
backbone schemas update <schemaId> -n "Updated Name"
backbone schemas delete <schemaId>

Schema Versions

backbone schemas versions list --schema <schemaId>
backbone schemas versions create --schema <schemaId> -c '{"type":"object","properties":{}}'
backbone schemas versions get <versionId> --schema <schemaId>
backbone schemas versions activate <versionId> --schema <schemaId>

Schema Labels

backbone schemas labels list --schema <schemaId>
backbone schemas labels create --schema <schemaId> -n "production" --version-id <versionId>
backbone schemas labels update "production" --schema <schemaId> --version-id <versionId>
backbone schemas labels delete "production" --schema <schemaId>

Schema Testing

# Validate a JSON Schema definition
backbone schemas validate <schemaId> -c '{"type":"object"}'

# Test extraction against sample text
backbone schemas test <schemaId> -t "John Doe, [email protected]" -m gpt-5.1

# Resolve active or labeled schema
backbone schemas resolve <schemaId>
backbone schemas resolve <schemaId> -l production

Prompts

Version-controlled prompt templates with variables and labels.

backbone prompts list
backbone prompts get <promptId>
backbone prompts create -n "My Prompt"
backbone prompts update <promptId>
backbone prompts delete <promptId>

# Compile template with variables
backbone prompts compile <promptId> --vars '{"name":"World"}'

# Test prompt against a model
backbone prompts test <promptId> -m gpt-5.1

Prompts also support versions and labels sub-commands with the same syntax as schemas.

Extractions

Extract structured data from text, files, or images.

# Extract from text
backbone extractions create --schema <schemaId> -m gpt-5.1 --text "John Doe, [email protected]"

# Extract from a file
backbone extractions create --schema <schemaId> -m gpt-5.1 --file ./invoice.pdf

# Extract from images
backbone extractions create --schema <schemaId> -m gpt-5.1 --images ./page1.png ./page2.png

# Async extraction
backbone extractions create --schema <schemaId> -m gpt-5.1 --text "..." --async

# List and manage
backbone extractions list --status COMPLETED
backbone extractions get <extractionId>
backbone extractions rerun <extractionId>

# Estimate token usage
backbone extractions estimate --schema <schemaId> -m gpt-5.1 --text "..."

Document Conversion

Convert documents (PDF, DOCX, images, etc.) to Markdown, text, HTML, or JSON.

# Convert local files
backbone convert file ./document.pdf --format md
backbone convert file ./scan.png --pipeline vlm --format md

# Convert from URL
backbone convert url https://example.com/doc.pdf --format text

# Async conversion
backbone convert file ./large.pdf --format md --async
backbone convert status <taskId>
backbone convert status <taskId> --wait    # Block until done
backbone convert result <taskId>

AI Gateway

Chat with AI models and list available providers.

# Chat completion
backbone ai chat -m gpt-5.1 --message "Explain recursion in one sentence"
backbone ai chat -m gpt-5.1 --message "Hello" --system "You are a pirate" --temperature 0.9

# List available models
backbone ai models

Transcription

Transcribe audio files to text.

backbone transcribe ./meeting.mp3 -m openai/whisper-1
backbone transcribe ./audio.wav -m openai/whisper-1 --language en --format srt

Supported formats: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm.

Providers

Manage BYOK (Bring Your Own Key) AI providers.

backbone providers list
backbone providers get <id>
backbone providers create -n "My OpenAI" --type openai --api-key sk-...
backbone providers update <id> --enabled false
backbone providers delete <id>
backbone providers models    # List all models across providers

Analytics

View organization usage analytics.

backbone analytics summary
backbone analytics time-series --group-by week --start 2025-01-01 --end 2025-12-31
backbone analytics schemas --limit 10
backbone analytics providers
backbone analytics errors
backbone analytics status

API Documentation

Browse the backend's OpenAPI documentation by section.

backbone docs sections              # List available doc sections
backbone docs get <section>         # Fetch docs for a specific section

Billing

Check subscription tier and usage limits.

backbone billing tier        # Current tier
backbone billing tiers       # All available tiers
backbone billing limits      # Detailed usage and limits
backbone billing check schema    # Can I create another schema?

Configuration

The CLI resolves configuration in this order (highest priority first):

CLI flags — --api-key, --base-url
Environment variables — BACKBONE_API_KEY, BACKBONE_BASE_URL
Local .backbone file — JSON file in the current working directory
Active context — stored in ~/.config/backbone/config.json

Manage the config store directly:

backbone config set <key> <value>
backbone config get <key>
backbone config list

Contexts

For users working across multiple organizations or environments, the CLI supports named contexts. Each context stores its own base URL and API key — making it easy to switch between organizations (e.g. different clients or teams) or environments (production, staging, local dev).

# Create a new context
backbone context create acme-corp --base-url https://api.2kw.ai --api-key sk_acme_...

# List all contexts (* marks the active one)
backbone context list

# Switch to a different context
backbone context use acme-corp

# Show the active context
backbone context current

# Rename or delete a context
backbone context rename acme-corp acme
backbone context delete acme

Default behavior

If you only use one organization, you never need to think about contexts. backbone auth login stores credentials in a default context automatically.

What's Next?

Check out the MCP Server to give AI coding assistants direct access to 2kw.ai, or learn about API Keys to manage your authentication tokens.