CLI

Manage your Backbone projects, schemas, extractions, and more — straight from the terminal.

Overview

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

Installation

Install the CLI globally via npm:

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

Verify the installation:

backbone --version

Short alias

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

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 project file	`.backbone` JSON file in the current directory

Setting a Default Project

Many commands are scoped to a project. Set a default to avoid passing --project every time:

backbone config set project <project-id>

You can also use the BACKBONE_PROJECT environment variable or a .backbone file in your project root.

Commands

Global Options

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

Projects

Manage projects within your organization.

backbone projects list                    # List all projects
backbone projects list --search "demo"    # Search projects
backbone projects get <id>                # Get project details
backbone projects create -n "My Project"  # Create a project
backbone projects update <id> -n "New Name"
backbone projects delete <id>

Schemas

Define and manage extraction schemas within a project.

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

Schema Versions

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

Schema Labels

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

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-4o

# 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 <id>
backbone prompts create -n "My Prompt"
backbone prompts update <id>
backbone prompts delete <id>

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

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

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 <id> -m gpt-4o --text "John Doe, [email protected]"

# Extract from a file
backbone extractions create --schema <id> -m gpt-4o --file ./invoice.pdf

# Extract from images
backbone extractions create --schema <id> -m gpt-4o --images ./page1.png ./page2.png

# Async extraction
backbone extractions create --schema <id> -m gpt-4o --text "..." --async

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

# Estimate token usage
backbone extractions estimate --schema <id> -m gpt-4o --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-4o --message "Explain recursion in one sentence"
backbone ai chat -m gpt-4o --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, 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 project-level 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 project   # Can I create another project?

Configuration

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

CLI flags — --api-key, --base-url, --project
Environment variables — BACKBONE_API_KEY, BACKBONE_BASE_URL, BACKBONE_PROJECT
Local .backbone file — JSON file in the current working directory
Config store — ~/.config/backbone/config.json

Manage the config store directly:

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

What's Next?

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