octarin-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,15 +1,12 @@
 # octarin-cli
 
 The per-user CLI for [Octarin](https://octarin.ai) AI-usage analytics (binary:
-`octarin`). One
-centralized, `npx`-based install path for AI-coding capture, plus a scoped,
-**read-only SQL** layer over your own data.
+`octarin`). One centralized, `npx`-based install path for AI-coding capture.
 
 ```bash
 npx octarin-cli@latest init <oct_key>          # personal capture install (this machine)
 npx octarin-cli@latest init-repo <org/project> # team install (commits config, opens a PR)
 npx octarin-cli@latest login                    # authorize a machine (team installs)
-npx octarin-cli@latest sql query "<SELECT ...>" # read-only SQL over your own data
 ```
 
 No `curl | bash`, no sha256-verify dance — version pinning (`@latest` /
@@ -17,7 +14,7 @@ No `curl | bash`, no sha256-verify dance — version pinning (`@latest` /
 (uses the built-in `fetch`); `init`'s history import additionally uses the
 system `python3`.
 
-## Capture install
+## Commands
 
 `init` and `init-repo` install the Octarin capture hooks for Claude Code,
 Cursor, and Codex entirely from the package's **bundled, version-pinned assets**
@@ -36,6 +33,9 @@ npx octarin-cli@latest init oct_xxx --backfill off  # skip the history import
 npx octarin-cli@latest init oct_xxx --tools cursor  # only Cursor
 ```
 
+Options: `--tools <claude,cursor,codex>`, `--backfill <30d|90d|all|off>`,
+`--base-url <url>`, `--url <ingest-url>`, `--port <port>`.
+
 ### `octarin init-repo <org/project>`
 
 Team install. Run at a repo root: commits shared hook config + the public
@@ -48,147 +48,25 @@ Device-code browser flow that mints a per-user ingest key into
 `~/.octarin/octarin.env`. Reads the project from `.octarin/project` (or
 `--project <org/project>`).
 
-## SQL
-
-A scoped, **read-only SQL** layer over your own data. Run SELECTs against your
-traces, spans, sessions, and events — or pipe machine-readable JSON into `jq`
-and your agents.
-
-The CLI holds **only your API key**, never database credentials. All query
-safety (single read-only SELECT, table allowlist, no `system.*`) and tenant
-scoping (every result is filtered to your organization's projects) are enforced
-**server-side** by the Octarin API. A query can only ever see your own data.
-
-## Auth (SQL)
-
-The `sql` commands authenticate with a read-only **query key** (`oct_...`) — a
-key that can run scoped SELECTs over your org's data but can NEVER ingest. This
-is a *distinct* key from the write-only **ingest key** used for capture (the one
-`octarin init` writes to `~/.octarin/octarin.env`); an ingest key is rejected
-here with a `403`.
-
-Mint a query key in the dashboard under **Settings → CLI / Query keys** (it is
-shown exactly once — copy it then). Then either:
-
-```bash
-export OCTARIN_API_KEY=oct_xxxxxxxxxxxxxxxxxxxx
-octarin sql query "SELECT count() FROM spans"
-```
-
-or pass it per-command:
-
-```bash
-octarin sql query "SELECT count() FROM spans" --api-key oct_xxxx
-```
-
-## Commands
-
-### `octarin sql schema`
-
-List the tables you can query and their columns.
-
-```bash
-octarin sql schema            # human-readable tables
-octarin sql schema --json     # machine-readable JSON
-```
-
-Queryable tables: `spans`, `traces`, `session_insights`, `span_vectors`,
-`events` (all in the `octarin` database; you may write them qualified as
-`octarin.spans` or bare as `spans`).
-
-### `octarin sql query "<SELECT ...>"`
-
-Run a single **read-only** SELECT. Default output is a readable ASCII table;
-`--json` emits structured JSON on stdout.
-
-```bash
-# Top models by token-bearing spans
-octarin sql query "SELECT model, count() AS c FROM spans GROUP BY model ORDER BY c DESC"
-
-# Cap the rows
-octarin sql query "SELECT * FROM traces ORDER BY start_time DESC" --limit 20
-
-# JSON for piping
-octarin sql query "SELECT model, count() AS c FROM spans GROUP BY model" --json
-```
-
-#### Pipe into `jq`
-
-Structured output goes to **stdout**; all progress/log/error messages go to
-**stderr**, so JSON pipes cleanly:
-
-```bash
-octarin sql query "SELECT model, count() AS c FROM spans GROUP BY model" --json \
-  | jq '.rows[] | {model: .[0], spans: .[1]}'
-```
-
-The response shape is:
-
-```json
-{
-  "columns": ["model", "c"],
-  "rows": [["claude-opus-4-8", 7594], ["claude-sonnet-4-6", 6188]],
-  "row_count": 2
-}
-```
-
-## Options
-
-| Option | Env var | Default | Description |
-|--------|---------|---------|-------------|
-| `--api-key <key>` | `OCTARIN_API_KEY` | — | Octarin **query** key (`oct_...`). Required. |
-| `--base-url <url>` | `OCTARIN_BASE_URL` | `https://api.octarin.ai` | API base URL. |
-| `--port <port>` | — | — | Override the port (self-host parity). |
-| `--limit <N>` | — | server cap | Max rows (server caps at 10000). |
-| `--json` | — | off | Emit JSON on stdout instead of a table. |
-| `-h`, `--help` | — | — | Show help (on every command). |
-| `--version` | — | — | Print the CLI version. |
-
-Self-host example:
-
-```bash
-octarin sql schema --base-url http://localhost:8000
-octarin sql schema --port 8000   # shorthand for http://localhost:8000
-```
-
 ## Agent-friendly I/O
 
-- **stdout** — only the structured result (the table, or `--json` JSON).
+- **stdout** — reserved for structured output.
 - **stderr** — all human/progress/error messages.
-- **exit code** — `0` on success, non-zero on failure (`2` for usage/auth
-  errors, `1` for request/execution errors).
-
-This makes the CLI safe to drive from scripts and LLM agents: capture stdout,
-check the exit code, read stderr for diagnostics.
-
-## What you can and can't query
-
-You can run exactly **one read-only `SELECT`** (a `WITH ... SELECT` CTE is fine)
-over the allowlisted `octarin.*` tables. The server rejects, with a clear `400`:
-
-- anything that isn't a single SELECT (no `INSERT/UPDATE/DELETE/ALTER/DROP/...`),
-- multiple `;`-separated statements,
-- references to other databases or tables — especially `system.*` and
-  `information_schema.*`,
-- table functions (`url`, `file`, `remote`, `s3`, `numbers`, ...).
-
-Every result is automatically scoped to your organization's projects — you
-never need to (and cannot) widen it.
+- **exit code** — `0` on success, non-zero on failure (`2` for usage errors,
+  `1` for runtime errors).
 
 ## Development
 
 ```bash
 npm install
-npm run build        # tsc -> dist/
-node dist/index.js sql schema
+npm run build        # copy-assets (from ../clients) + tsc -> dist/
+node dist/index.js --help
 # or run the local checkout via npx:
-npx . sql schema
+npx . init --help
 ```
 
 ## Publishing (maintainers)
 
-This package is publish-ready but not yet published. To release:
-
 ```bash
 npm version <patch|minor|major>
 npm publish            # runs prepublishOnly -> npm run build

package/dist/args.js

@@ -11,10 +11,8 @@
  */
 /** Flags that consume the following token as their value. */
 const VALUE_FLAGS = new Set([
-    "api-key",
     "base-url",
     "port",
-    "limit",
     // init / init-repo / login
     "key",
     "url",
@@ -24,7 +22,7 @@ const VALUE_FLAGS = new Set([
     "device-label",
 ]);
 /** Boolean flags that never consume a value. */
-const BOOL_FLAGS = new Set(["json", "help"]);
+const BOOL_FLAGS = new Set(["help"]);
 /** Map of short aliases to their long-flag names. */
 const ALIASES = { h: "help" };
 /** Parse an argv tail (after the node + script entries) into positionals+flags. */

package/dist/client.js

@@ -1,13 +1,8 @@
 /**
- * HTTP client for the Octarin SQL gateway.
+ * Shared CLI helpers: the user-facing error type and base-URL resolution.
  *
- * Resolves auth + base URL from flags/env, then calls `POST /v1/sql/query` and
- * `GET /v1/sql/schema` with the API key as a Bearer token. The CLI holds ONLY
- * the API key — never ClickHouse credentials; all scoping/safety is server-side.
- *
- * Errors map the gateway's JSON envelope (`{ "error": { code, message } }`) to a
- * thrown `CliError` so the command layer can print a clean message to stderr and
- * exit non-zero.
+ * Used by every command (`init`, `init-repo`, `login`) to map failures to exit
+ * codes and to resolve the Octarin API base URL from flags/env.
  */
 /** A user-facing error carrying a process exit code. */
 export class CliError extends Error {
@@ -41,65 +36,3 @@ export function resolveBaseUrl(opts) {
     }
     return base.replace(/\/+$/, "");
 }
-/**
- * Resolve the API key from explicit flag or env, or throw a clear `CliError`.
- *
- * Precedence: `--api-key` > `OCTARIN_API_KEY`.
- */
-export function resolveApiKey(apiKeyFlag) {
-    const key = apiKeyFlag || process.env.OCTARIN_API_KEY;
-    if (!key) {
-        throw new CliError("No API key. Set OCTARIN_API_KEY or pass --api-key <oct_...>.", 2);
-    }
-    return key;
-}
-/** Perform a request to the gateway and parse its JSON, mapping errors. */
-async function request(cfg, path, init) {
-    const url = `${cfg.baseUrl}${path}`;
-    let resp;
-    try {
-        resp = await fetch(url, {
-            ...init,
-            headers: {
-                Authorization: `Bearer ${cfg.apiKey}`,
-                "Content-Type": "application/json",
-                ...(init.headers || {}),
-            },
-        });
-    }
-    catch (err) {
-        const detail = err instanceof Error ? err.message : String(err);
-        throw new CliError(`Could not reach ${url}: ${detail}`, 1);
-    }
-    const text = await resp.text();
-    let body = undefined;
-    if (text) {
-        try {
-            body = JSON.parse(text);
-        }
-        catch {
-            // Non-JSON body (e.g. a proxy 502 page). Fall through to status handling.
-        }
-    }
-    if (!resp.ok) {
-        const envelope = body;
-        const msg = envelope?.error?.message || text || `HTTP ${resp.status}`;
-        const code = envelope?.error?.code;
-        throw new CliError(`Request failed (${resp.status}${code ? ` ${code}` : ""}): ${msg}`, 1);
-    }
-    return body;
-}
-/** POST a SELECT to `/v1/sql/query`. */
-export function runQuery(cfg, query, limit) {
-    const payload = { query };
-    if (limit !== undefined)
-        payload.limit = limit;
-    return request(cfg, "/v1/sql/query", {
-        method: "POST",
-        body: JSON.stringify(payload),
-    });
-}
-/** GET the queryable schema from `/v1/sql/schema`. */
-export function getSchema(cfg) {
-    return request(cfg, "/v1/sql/schema", { method: "GET" });
-}

package/dist/index.js

@@ -1,30 +1,26 @@
 #!/usr/bin/env node
 /**
- * `octarin` — a thin, agent-friendly CLI over the Octarin SQL gateway.
+ * `octarin` — the per-user CLI for Octarin AI-usage analytics.
  *
- * Two commands today, mirroring `lmnr-cli`'s stable noun-verb surface:
- *   octarin sql query "<SELECT ...>" [--json] [--limit N]
- *   octarin sql schema [--json]
+ * Install AI-coding capture and authorize a machine:
+ *   octarin init <oct_key>            personal capture install (this machine)
+ *   octarin init-repo <org/project>   team install (commits config, opens a PR)
+ *   octarin login                     authorize a machine via browser sign-in
  *
- * Auth: `OCTARIN_API_KEY` env var or `--api-key`. Base URL: `https://api.octarin.ai`
- * by default, overridable with `--base-url` / `OCTARIN_BASE_URL` (and `--port`
- * for self-host parity). The CLI holds only the API key — never DB credentials;
- * the server enforces read-only access, the table allowlist, and tenant scoping.
- *
- * I/O contract (so `--json | jq` pipes cleanly): structured results on stdout,
- * all human/progress/error messages on stderr, non-zero exit on failure.
+ * All human/progress/error messages go to stderr; the exit code signals success
+ * (0) or failure (non-zero), so the CLI is safe to drive from scripts/agents.
  */
-import { flagBool, flagStr, parseArgs } from "./args.js";
-import { CliError, getSchema, resolveApiKey, resolveBaseUrl, runQuery, } from "./client.js";
+import { flagBool, parseArgs } from "./args.js";
+import { CliError } from "./client.js";
 import { cmdLogin } from "./login.js";
 import { cmdInit } from "./init.js";
 import { cmdInitRepo } from "./init_repo.js";
-import { logErr, outJson, outTable } from "./output.js";
-const VERSION = "0.2.0";
+import { logErr } from "./output.js";
+const VERSION = "0.3.0";
 const ROOT_HELP = `octarin — per-user CLI for Octarin AI-usage analytics
 
 USAGE
-  octarin <command> [subcommand] [args] [options]
+  octarin <command> [args] [options]
 
 COMMANDS
   init <oct_key>             Install AI-coding capture on THIS machine (personal).
@@ -35,120 +31,23 @@ COMMANDS
   login                      Authorize this machine via a browser sign-in.
                              Writes ~/.octarin/octarin.env so capture hooks
                              pick up your per-user ingest key.
-  sql query "<SELECT ...>"   Run a read-only SELECT against your octarin.* tables
-  sql schema                 List the queryable tables and their columns
 
 GLOBAL OPTIONS
-  --api-key <key>     Octarin API key (oct_...). Or set OCTARIN_API_KEY.
-                      (Not used by \`octarin login\` — that's how you GET a key.)
   --base-url <url>    API base URL. Or set OCTARIN_BASE_URL.
                       Default: https://api.octarin.ai
   --port <port>       Override the port (self-host parity).
-  --json              Emit machine-readable JSON on stdout (pipe to jq).
-  -h, --help          Show help.
+  -h, --help          Show help (on every command).
   --version           Show the CLI version.
 
 EXAMPLES
   octarin init oct_xxx                              # personal capture install
   octarin init-repo nace/default                    # team install (opens a PR)
   octarin login                                     # per-user auth (team installs)
-  octarin sql schema
-  octarin sql query "SELECT model, count() FROM spans GROUP BY model"
 `;
-const SQL_HELP = `octarin sql — query your own Octarin data (read-only)
-
-USAGE
-  octarin sql query "<SELECT ...>" [--json] [--limit N]
-  octarin sql schema [--json]
-
-OPTIONS
-  --limit N           Max rows to return (server caps at 10000).
-  --json              Emit JSON on stdout instead of a table.
-  --api-key <key>     Octarin API key (oct_...). Or set OCTARIN_API_KEY.
-  --base-url <url>    API base URL. Or set OCTARIN_BASE_URL.
-  --port <port>       Override the port (self-host parity).
-  -h, --help          Show this help.
-
-NOTES
-  Only a single read-only SELECT over your octarin.* tables is allowed
-  (spans, traces, session_insights, span_vectors, events). The server enforces
-  the table allowlist and scopes every result to your organization's projects.
-`;
-/** Build the client config (auth + base URL) from parsed flags. */
-function buildConfig(flags) {
-    const apiKey = resolveApiKey(flagStr(flags, "api-key"));
-    const baseUrl = resolveBaseUrl({
-        baseUrl: flagStr(flags, "base-url"),
-        port: flagStr(flags, "port"),
-    });
-    return { apiKey, baseUrl };
-}
-/** `octarin sql query "<SELECT>"` */
-async function cmdSqlQuery(positionals, flags) {
-    const query = positionals[0];
-    if (!query) {
-        throw new CliError('Missing query. Usage: octarin sql query "<SELECT ...>"', 2);
-    }
-    let limit;
-    const limitStr = flagStr(flags, "limit");
-    if (limitStr !== undefined) {
-        const n = Number(limitStr);
-        if (!Number.isInteger(n) || n < 1) {
-            throw new CliError(`--limit must be a positive integer, got "${limitStr}".`, 2);
-        }
-        limit = n;
-    }
-    const cfg = buildConfig(flags);
-    logErr(`> querying ${cfg.baseUrl} ...`);
-    const result = await runQuery(cfg, query, limit);
-    if (flagBool(flags, "json")) {
-        outJson(result);
-    }
-    else {
-        outTable(result.columns, result.rows);
-        logErr(`(${result.row_count} row${result.row_count === 1 ? "" : "s"})`);
-    }
-}
-/** `octarin sql schema` */
-async function cmdSqlSchema(flags) {
-    const cfg = buildConfig(flags);
-    logErr(`> fetching schema from ${cfg.baseUrl} ...`);
-    const schema = await getSchema(cfg);
-    if (flagBool(flags, "json")) {
-        outJson(schema);
-        return;
-    }
-    // Human-readable: one block per table.
-    for (const table of schema.tables) {
-        outTable(["column", "type"], table.columns.map((c) => [c.name, c.type]));
-        logErr(`  ${table.qualified_name} — ${table.columns.length} columns\n`);
-    }
-}
-/** Dispatch the `sql` command group. */
-async function cmdSql(positionals, flags) {
-    const sub = positionals[0];
-    const rest = positionals.slice(1);
-    if (flagBool(flags, "help") || !sub) {
-        logErr(SQL_HELP);
-        if (!sub)
-            throw new CliError("Missing subcommand (query | schema).", 2);
-        return;
-    }
-    switch (sub) {
-        case "query":
-            return cmdSqlQuery(rest, flags);
-        case "schema":
-            return cmdSqlSchema(flags);
-        default:
-            logErr(SQL_HELP);
-            throw new CliError(`Unknown sql subcommand: ${sub}`, 2);
-    }
-}
 /** Entry point: parse argv, route to a command, map errors to exit codes. */
 async function main() {
     const { positionals, flags } = parseArgs(process.argv.slice(2));
     if (flags.version === true) {
-        // Version is structured-ish output; print to stdout.
         process.stdout.write(VERSION + "\n");
         return;
     }
@@ -170,9 +69,6 @@ async function main() {
         case "login":
             await cmdLogin(rest, flags);
             break;
-        case "sql":
-            await cmdSql(rest, flags);
-            break;
         case "help":
             logErr(ROOT_HELP);
             break;

package/dist/output.js

@@ -1,56 +1,11 @@
 /**
- * Output helpers — strict stdout/stderr separation for agent-friendly piping.
+ * Output helper.
  *
- * Contract (mirrors Laminar's `lmnr-cli`): *structured* output (the actual
- * query result / schema, as JSON or a rendered table) goes to **stdout**;
- * *everything else* — progress, hints, warnings, errors — goes to **stderr**.
- * That way `octarin sql query "..." --json | jq` receives clean JSON on stdout
- * with no log noise, and a non-zero exit code signals failure to the caller.
+ * The CLI keeps stdout clean and writes all human/progress/diagnostic messages
+ * to stderr, so callers (scripts, agents) can rely on the exit code and capture
+ * stderr for context without parsing noise.
  */
 /** Write a line to stderr (human/progress/diagnostic messages). */
 export function logErr(message) {
     process.stderr.write(message + "\n");
 }
-/** Write structured output to stdout (the machine-readable result). */
-export function out(text) {
-    process.stdout.write(text + "\n");
-}
-/** Pretty-print a value as indented JSON to stdout. */
-export function outJson(value) {
-    out(JSON.stringify(value, null, 2));
-}
-/**
- * Render rows as a monospace ASCII table to stdout.
- *
- * `columns` are the header names; `rows` are arrays aligned to them. Cells are
- * stringified (null → "" , objects → compact JSON) and each column is padded to
- * its widest cell. Designed for human reading in a terminal — use `--json` for
- * anything a program will parse.
- */
-export function outTable(columns, rows) {
-    if (columns.length === 0) {
-        out("(no columns)");
-        return;
-    }
-    const cells = rows.map((r) => r.map(formatCell));
-    const widths = columns.map((c, i) => Math.max(c.length, ...cells.map((row) => (row[i] ?? "").length), 0));
-    const sep = "+" + widths.map((w) => "-".repeat(w + 2)).join("+") + "+";
-    const renderRow = (vals) => "| " + vals.map((v, i) => v.padEnd(widths[i])).join(" | ") + " |";
-    out(sep);
-    out(renderRow(columns));
-    out(sep);
-    for (const row of cells) {
-        // Pad short rows so the table stays rectangular.
-        const padded = columns.map((_, i) => row[i] ?? "");
-        out(renderRow(padded));
-    }
-    out(sep);
-}
-/** Stringify a single cell value for the ASCII table. */
-function formatCell(value) {
-    if (value === null || value === undefined)
-        return "";
-    if (typeof value === "object")
-        return JSON.stringify(value);
-    return String(value);
-}

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "octarin-cli",
-  "version": "0.2.0",
-  "description": "Octarin's per-user CLI: install AI-coding capture (`octarin init` / `init-repo`), authorize a machine (`octarin login`), and run scoped read-only SQL over your own data. Never holds database credentials.",
+  "version": "0.3.0",
+  "description": "Octarin's per-user CLI: install AI-coding capture (`octarin init` / `init-repo`) and authorize a machine (`octarin login`). Streams your Claude Code / Cursor / Codex usage to your Octarin workspace.",
   "keywords": [
     "octarin",
-    "sql",
     "cli",
     "observability",
     "llm",