@2kw/ai 5.2.0-dev.6 → 5.2.0

package/README.md

@@ -1,60 +1,91 @@
-# 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 — opens your browser, no API key needed (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
 
-The CLI supports multiple authentication methods (highest priority first):
+Sign in via the browser (recommended):
+
+```bash
+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):
+
+```bash
+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 | `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` (browser session or saved key) |
 
 ```bash
-backbone auth login     # Interactive setup
-backbone auth status    # Verify credentials
-backbone auth logout    # Clear stored credentials
+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
 
-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 +94,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 +116,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.d.ts

@@ -1,3 +1,93 @@
 import { Command } from "commander";
-export declare function makeAuthCommand(): Command;
+import { setContext, setActiveContext, type ResolvedConfig } from "../lib/config.js";
+import { getSessionInfo, listOrganizations, pollDeviceToken, requestDeviceCode, revokeSession, setActiveOrganization } from "../lib/auth-service.js";
+import { runDevicePolling, selectOrganization } from "../lib/auth-session.js";
+type SessionConfig = Extract<ResolvedConfig, {
+    kind: "session";
+}>;
+/**
+ * Group an 8-character device user code as XXXX-XXXX.
+ *
+ * Purely presentational: the code is read off a terminal and typed into a
+ * browser, and a grouped one survives that trip with fewer mistakes. Anything
+ * that is not exactly 8 characters (a service configured for another length,
+ * or a code that already carries its own separator) is shown untouched.
+ */
+export declare function formatUserCode(code: string): string;
+/** Injection points for {@link deviceFlowLogin}; all default to the real thing. */
+export interface DeviceLoginDeps {
+    requestCode?: typeof requestDeviceCode;
+    poll?: typeof pollDeviceToken;
+    runPolling?: typeof runDevicePolling;
+    sessionInfo?: typeof getSessionInfo;
+    listOrgs?: typeof listOrganizations;
+    chooseOrg?: typeof selectOrganization;
+    setActiveOrg?: typeof setActiveOrganization;
+    /** Used to clean up a session that never got an organization. */
+    revoke?: typeof revokeSession;
+    openBrowser?: (url: string) => Promise<void>;
+    saveContext?: typeof setContext;
+    activateContext?: typeof setActiveContext;
+}
+export interface DeviceLoginTarget {
+    contextName: string;
+    baseUrl: string;
+    authUrl: string;
+}
+/**
+ * The browser login, end to end: ask for a device code, wait for the user to
+ * approve it, then record who they are and which organization they act as.
+ *
+ * A refused or expired approval is reported and swallowed (exit code 1, no
+ * context written) because it is the user's answer, not a fault. Everything
+ * else — an unreachable auth service, a rejected client id — propagates to
+ * `runAction`, which renders it once and machine-readably under `--json`.
+ *
+ * By design this is an interactive surface: it prints a code, opens a browser,
+ * and may ask which organization to use. Its own outcomes are therefore prose
+ * even under `--json` — a device approval that was denied is a conversation,
+ * not a payload. Faults still leave through handleError and are rendered as
+ * JSON there.
+ */
+export declare function deviceFlowLogin(target: DeviceLoginTarget, deps?: DeviceLoginDeps): Promise<void>;
+/** Injection point for {@link performLogout}; defaults to the real call. */
+export interface LogoutDeps {
+    revoke?: typeof revokeSession;
+}
+/**
+ * Sign out: drop the local credentials, then tell the auth service.
+ *
+ * That order is deliberate. `revokeSession` has no timeout, so an auth host
+ * that black-holes the request would hang the command with the credentials
+ * still on disk — while the user, having read "Credentials cleared", believes
+ * they are signed out. Clearing first makes the local half unconditional and
+ * leaves the network call as what it is: best-effort, and the only part that
+ * can fail. A host that refuses the connection fails fast either way.
+ *
+ * The token and URL are copied out first because the store no longer holds
+ * them by the time they are used.
+ */
+export declare function performLogout(deps?: LogoutDeps): Promise<void>;
+/** How the caller wants the status rendered. */
+export interface SessionStatusView {
+    json: boolean;
+    contextName: string;
+    multiContext: boolean;
+}
+/** Injection points for {@link sessionStatus}. */
+export interface SessionStatusDeps {
+    /** The probe that decides "authenticated" — normally a bound
+     *  {@link countModels}. Required: it is the whole test. */
+    countModels: () => Promise<number>;
+    /** Identity lookup; defaults to the real auth-service call. */
+    sessionInfo?: typeof getSessionInfo;
+}
+/** `auth status` for a browser-session context. */
+export declare function sessionStatus(config: SessionConfig, view: SessionStatusView, deps: SessionStatusDeps): Promise<void>;
+/**
+ * @param deviceDeps forwarded to {@link deviceFlowLogin} — a seam for tests
+ *   that need to prove the browser flow was NOT entered.
+ */
+export declare function makeAuthCommand(deviceDeps?: DeviceLoginDeps): Command;
+export {};
 //# sourceMappingURL=auth.d.ts.map