@2kw/ai 5.1.0 → 5.2.0-dev.8

package/README.md

@@ -1,31 +1,40 @@
-# Backbone CLI
+# 2kw.ai CLI
 
-A command-line interface for the [Backbone AI](https://backbone.manfred-kunze.dev) platform. Manage schemas, prompts, extractions, documents, and more — straight from your terminal.
+The command-line interface for [2kw.ai](https://2kw.ai) — the EU-hosted AI integration platform. Run [schema-driven document extraction](https://2kw.ai/extraction), route LLM calls through an [OpenAI-compatible gateway](https://2kw.ai/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
 
 ```bash
 # Latest stable release
-npm install -g @manfred-kunze-dev/backbone-cli
+npm install -g @2kw/ai
 
 # Pre-release (dev channel)
-npm install -g @manfred-kunze-dev/backbone-cli@dev
+npm install -g @2kw/ai@dev
 ```
 
-The CLI will notify you when a newer version is available.
+The CLI notifies you when a newer version is available.
 
 ## Quick Start
 
 ```bash
-# Authenticate
-backbone auth login
+# Authenticate (get an API key from your 2kw.ai dashboard — 7-day free trial)
+2kw auth login
 
 # Define a schema and run an extraction
-backbone schemas create -n "Invoice"
-backbone extractions create --schema <id> -m gpt-4o --text "Invoice #123, Total: $500"
+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"
 ```
 
-The CLI is also available as `bb` for quick access — e.g. `bb schemas list`.
+All commands work identically as `bb` for quick access — e.g. `bb schemas list`.
 
 ## Authentication
 
@@ -34,27 +43,24 @@ The CLI supports multiple authentication methods (highest priority first):
 | Method | Example |
 |--------|---------|
 | CLI flags | `--api-key sk_... --base-url https://...` |
-| Environment variables | `BACKBONE_API_KEY`, `BACKBONE_BASE_URL` |
-| Local `.backbone` file | JSON file in the current directory |
-| Config store | `~/.config/backbone/config.json` (set via `backbone auth login`) |
+| 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` |
 
 ```bash
-backbone auth login     # Interactive setup
-backbone auth status    # Verify credentials
-backbone auth logout    # Clear stored credentials
+2kw auth login     # Interactive setup
+2kw auth status    # Verify credentials
+2kw auth logout    # Clear stored credentials
 ```
 
 ## Contexts
 
-The CLI supports kubectl-style contexts for switching between organizations and environments:
+kubectl-style contexts switch between organizations and environments:
 
 ```bash
-# Contexts are created automatically via `backbone auth login`
-backbone context list              # List all contexts
-backbone context use acme-corp     # Switch active context
-backbone context create staging    # Create a new context
-backbone context rename old new    # Rename a context
-backbone context delete old        # Remove a context
+2kw context list              # List all contexts
+2kw context use acme-corp     # Switch active context
+2kw context create staging    # Create a new context
 ```
 
 ## Commands
@@ -63,15 +69,20 @@ backbone context delete old        # Remove a context
 |---------|-------------|
 | `auth` | Login, logout, and check auth status |
 | `config` | Get, set, and list configuration values |
-| `context` | Manage CLI contexts for multiple environments |
+| `context` | Manage contexts for multiple orgs/environments |
 | `schemas` | Manage schemas, versions, labels, validation, and testing |
-| `prompts` | Manage prompts, versions, labels, compilation, and testing |
+| `prompts` | Versioned prompt management, labels, compilation, testing |
 | `extractions` | Create extractions (text, file, images), list, re-run, estimate tokens |
-| `convert` | Convert documents (PDF, DOCX, images) to Markdown/text/HTML/JSON |
-| `ai` | Chat completions and model listing via the LLM Gateway |
-| `transcribe` | Transcribe audio files (mp3, wav, flac, ogg, etc.) |
+| `convert` | Convert PDF, DOCX, XLSX, images, and 20+ formats to Markdown/text/HTML/JSON |
+| `ai` | Chat completions 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` | View organization usage analytics |
+| `analytics` | Usage analytics: spend, quality, providers, errors |
 | `billing` | Check subscription tier and usage limits |
 | `docs` | Browse API documentation from the terminal |
 
@@ -80,11 +91,21 @@ backbone context delete old        # Remove a context
 | Flag | Description |
 |------|-------------|
 | `--api-key <key>` | Override the API key |
-| `--base-url <url>` | Override the base URL (default: `https://backbone.manfred-kunze.dev/api`) |
-| `--json` | Output raw JSON instead of formatted tables |
+| `--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 |
 
-For full command documentation, see the [Backbone docs](https://backbone.manfred-kunze.dev).
+## 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](https://2kw.ai) — platform overview and pricing
+- [Documentation](https://docs.2kw.ai) — full command and API reference
+- [`@2kw/ai-mcp-server`](https://www.npmjs.com/package/@2kw/ai-mcp-server) — the 2kw.ai MCP server for Claude Code, Cursor, and Windsurf
 
 ## License
 

package/dist/commands/auth.js

@@ -2,7 +2,15 @@ import { Command } from "commander";
 import chalk from "chalk";
 import { store, resolveConfig, isJsonOutput, getActiveContextName, getActiveContext, getContextCount, setContext, setActiveContext, deleteContext, DEFAULT_BASE_URL, } from "../lib/config.js";
 import { getClient, runAction } from "../lib/client.js";
+import { classifyAuthFailure } from "../lib/errors.js";
 import { createInterface } from "node:readline/promises";
+// Human-readable, actionable line per failure kind for the non-JSON output.
+const FAILURE_HINTS = {
+    UNAUTHORIZED: 'Key rejected. Run "2kw auth login" to re-authenticate.',
+    FORBIDDEN: "Key is valid but lacks access. Check the key's organization in the 2kw UI.",
+    UNREACHABLE: "Could not reach the host. Check the base URL and your connection.",
+    UNKNOWN: 'Validation failed. Run "2kw auth login" and, if it persists, check the base URL.',
+};
 export function makeAuthCommand() {
     const cmd = new Command("auth").description("Manage authentication");
     cmd
@@ -71,6 +79,8 @@ export function makeAuthCommand() {
                 config = resolveConfig(command);
             }
             catch {
+                // No credentials configured at all — distinct from a rejected key.
+                process.exitCode = 1;
                 if (json) {
                     console.log(JSON.stringify({ authenticated: false }));
                 }
@@ -108,13 +118,19 @@ export function makeAuthCommand() {
                     console.log(`  Models:    ${modelCount} available`);
                 }
             }
-            catch {
+            catch (err) {
+                // Credentials are present but the check failed. Surface WHY, so
+                // callers stop guessing among a bad key, missing permissions, and an
+                // unreachable host.
+                const failureKind = classifyAuthFailure(err);
+                process.exitCode = 1;
                 if (json) {
                     console.log(JSON.stringify({
                         authenticated: false,
                         ...(multiContext ? { context: contextName } : {}),
                         baseUrl,
                         apiKeyPreview: keyPreview,
+                        failureKind,
                         error: "Failed to validate credentials",
                     }));
                 }
@@ -125,6 +141,7 @@ export function makeAuthCommand() {
                     }
                     console.log(`  Base URL:  ${baseUrl}`);
                     console.log(`  API Key:   ${keyPreview}`);
+                    console.log(chalk.yellow(`  ${FAILURE_HINTS[failureKind]}`));
                 }
             }
         });

package/dist/lib/config.js

@@ -22,6 +22,14 @@ function warnLegacyEnv(legacyName, canonicalName) {
         `Switch to ${canonicalName} — the BACKBONE_* names will be removed ` +
         `in a future release.\n`);
 }
+/**
+ * Optional override for where the config store lives. Set AI_2KW_CONFIG_DIR to
+ * relocate the store — e.g. to isolate an environment, or so the test suite
+ * never touches the real user profile. When set, it applies to both the active
+ * store and the legacy store the migration reads, so a redirected run stays
+ * fully self-contained.
+ */
+const CONFIG_DIR_OVERRIDE = process.env.AI_2KW_CONFIG_DIR;
 const store = new Conf({
     projectName: "2kw",
     projectSuffix: "",
@@ -29,6 +37,7 @@ const store = new Conf({
         activeContext: "default",
         contexts: {},
     },
+    ...(CONFIG_DIR_OVERRIDE ? { cwd: CONFIG_DIR_OVERRIDE } : {}),
 });
 // One-shot migration: copy any legacy ~/.config/backbone/ store into the new
 // ~/.config/2kw/ store on first run. Triggered only if the new store has no
@@ -48,6 +57,7 @@ const store = new Conf({
         projectName: "backbone",
         projectSuffix: "",
         defaults: { activeContext: "default", contexts: {} },
+        ...(CONFIG_DIR_OVERRIDE ? { cwd: CONFIG_DIR_OVERRIDE } : {}),
     });
     if (!existsSync(legacy.path))
         return;

package/dist/lib/errors.d.ts

@@ -10,5 +10,22 @@ export declare class BackboneApiError extends Error {
     readonly timestamp: string;
     constructor(body: ApiErrorBody);
 }
+/**
+ * Discriminated cause of a failed credential check. Lets callers give a
+ * precise message instead of guessing, because `2kw auth status` otherwise
+ * collapses every failure into one string.
+ */
+export type AuthFailureKind = "UNAUTHORIZED" | "FORBIDDEN" | "UNREACHABLE" | "UNKNOWN";
+/**
+ * Classify why a credential check failed, from the thrown error alone.
+ *
+ * - An HTTP rejection arrives as {@link BackboneApiError}: 401 → UNAUTHORIZED,
+ *   403 → FORBIDDEN, anything else → UNKNOWN.
+ * - A network fault (fetch throws before any response) → UNREACHABLE, detected
+ *   by undici's `fetch failed` TypeError or a known network error code on the
+ *   error or its `cause`.
+ * - Everything else → UNKNOWN.
+ */
+export declare function classifyAuthFailure(err: unknown): AuthFailureKind;
 export declare function handleError(err: unknown, json: boolean): void;
 //# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.js

@@ -11,6 +11,53 @@ export class BackboneApiError extends Error {
         this.timestamp = body.timestamp;
     }
 }
+// Node/undici surface network faults through the error's `code`. A DNS or
+// connection failure means the host was never reached — distinct from the
+// API rejecting the key.
+const NETWORK_ERROR_CODES = new Set([
+    "ENOTFOUND",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "ECONNRESET",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+]);
+/**
+ * Classify why a credential check failed, from the thrown error alone.
+ *
+ * - An HTTP rejection arrives as {@link BackboneApiError}: 401 → UNAUTHORIZED,
+ *   403 → FORBIDDEN, anything else → UNKNOWN.
+ * - A network fault (fetch throws before any response) → UNREACHABLE, detected
+ *   by undici's `fetch failed` TypeError or a known network error code on the
+ *   error or its `cause`.
+ * - Everything else → UNKNOWN.
+ */
+export function classifyAuthFailure(err) {
+    if (err instanceof BackboneApiError) {
+        if (err.status === 401)
+            return "UNAUTHORIZED";
+        if (err.status === 403)
+            return "FORBIDDEN";
+        return "UNKNOWN";
+    }
+    if (isNetworkError(err))
+        return "UNREACHABLE";
+    return "UNKNOWN";
+}
+function isNetworkError(err) {
+    if (!(err instanceof Error))
+        return false;
+    // undici throws `TypeError: fetch failed` when the request never completes.
+    if (err instanceof TypeError && /fetch failed/i.test(err.message))
+        return true;
+    const code = err.code;
+    if (typeof code === "string" && NETWORK_ERROR_CODES.has(code))
+        return true;
+    const cause = err.cause;
+    const causeCode = cause?.code;
+    return typeof causeCode === "string" && NETWORK_ERROR_CODES.has(causeCode);
+}
 const HINTS = {
     401: 'Invalid or missing API key. Run "backbone auth login" to configure credentials.',
     402: "Billing limit reached. Check your plan limits or upgrade at the dashboard.",

package/dist/lib/update-notifier.js

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import chalk from "chalk";
-const PKG_NAME = "@manfred-kunze-dev/backbone-cli";
+const PKG_NAME = "@2kw/ai";
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // 1 day
 const CACHE_DIR = join(homedir(), ".config", "backbone");
 const CACHE_FILE = join(CACHE_DIR, "update-check.json");

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@2kw/ai",
-  "version": "5.1.0",
-  "description": "CLI for the 2kw.ai platform (engineering name: Backbone)",
+  "version": "5.2.0-dev.8",
+  "description": "CLI for 2kw.ai — schema-driven document extraction, an OpenAI-compatible EU LLM gateway, transcription, prompts, datasets, and experiments from your terminal or agentic workflows. Ships as 2kw, backbone, and bb.",
+  "keywords": [
+    "cli",
+    "llm-gateway",
+    "ai-gateway",
+    "document-extraction",
+    "structured-data-extraction",
+    "pdf-extraction",
+    "openai-compatible",
+    "transcription",
+    "prompt-management",
+    "llm-evaluation",
+    "llm-observability",
+    "agentic-workflows",
+    "gdpr",
+    "eu-data-residency",
+    "2kw",
+    "backbone"
+  ],
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -17,7 +35,11 @@
     "generate:types": "openapi-typescript openapi/openapi.json -o src/generated/openapi.d.ts",
     "generate": "npm run generate:spec && npm run generate:types",
     "check:spec": "tsx --env-file=.env openapi/scripts/check-drift.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:contract": "vitest run tests/contract"
   },
   "dependencies": {
     "chalk": "^5.6.2",
@@ -31,7 +53,8 @@
     "@types/node": "^22.19.17",
     "openapi-typescript": "^7.13.0",
     "tsx": "^4.21.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=18.20.8"