octarin-cli 0.2.0

package/README.md

@@ -0,0 +1,202 @@
+# 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.
+
+```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` /
+`@x.y.z`) and npm provenance are the integrity story. Requires Node.js >= 18
+(uses the built-in `fetch`); `init`'s history import additionally uses the
+system `python3`.
+
+## Capture install
+
+`init` and `init-repo` install the Octarin capture hooks for Claude Code,
+Cursor, and Codex entirely from the package's **bundled, version-pinned assets**
+— nothing is fetched at install time.
+
+### `octarin init <oct_key>`
+
+Personal, per-machine install. Writes your write-only ingest key to
+`~/.octarin/octarin.env` (mode 600, never git), copies the hook files into each
+detected tool's config dir, **merges** the hook registration into that tool's
+settings (no hand-editing), and imports your existing history.
+
+```bash
+npx octarin-cli@latest init oct_xxx                 # all detected tools, last 90 days
+npx octarin-cli@latest init oct_xxx --backfill off  # skip the history import
+npx octarin-cli@latest init oct_xxx --tools cursor  # only Cursor
+```
+
+### `octarin init-repo <org/project>`
+
+Team install. Run at a repo root: commits shared hook config + the public
+project slug to `.claude/.cursor/.codex` + `.octarin/project` (no key, ever),
+and opens a PR. Each teammate then runs `octarin login` once.
+
+### `octarin login`
+
+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).
+- **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.
+
+## Development
+
+```bash
+npm install
+npm run build        # tsc -> dist/
+node dist/index.js sql schema
+# or run the local checkout via npx:
+npx . sql schema
+```
+
+## 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
+```
+
+(`files` ships `dist/`, the bundled `assets/`, and this README; `prepublishOnly`
+rebuilds, which re-stages `assets/` from `../clients` via `copy-assets`.)
+
+## License
+
+MIT