@abliteration/cli 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# abliteration CLI
+
+Command-line client for the [abliteration.org](https://abliteration.org) catalog API. The same catalog you browse on the web, served as JSON from your terminal — models, datasets, methods, indices, and the curated field timeline.
+
+## Install
+
+```bash
+npm install -g @abliteration/cli
+```
+
+Or use the installer that also works on machines without Node.js installed:
+
+```bash
+curl -sSf https://abliteration.org/install | bash
+```
+
+Both give you two commands: `abliteration` (the full name) and `abl` (the short one). Everywhere you can type one, you can type the other.
+
+## Getting started
+
+```bash
+$ abl login
+# Opens https://abliteration.org/shop/account#api-keys in your browser.
+# Generate a key on that page, paste it here.
+
+$ abl models --method M4 --limit 5
+ID                                                     Method  Family   License      Downloads
+-----------------------------------------------------  ------  -------  -----------  ---------
+mlabonne/Qwen3-30B-A3B-abliterated                     M4      qwen     apache-2.0     249,452
+mlabonne/Meta-Llama-3.1-8B-Instruct-abliterated-GGUF   M4      llama-3  llama-3         30,768
+mlabonne/NeuralDaredevil-8B-abliterated                M4      llama-3  llama-3         14,765
+mlabonne/gemma-2-9b-it-abliterated                     M4      gemma-2  gemma           12,890
+mlabonne/Daredevil-8B-abliterated                      M4      llama-3  llama-3         11,432
+cost: 5 cr · balance: 495 · rate: 59/60
+```
+
+## Commands
+
+| Command | What it does | Cost |
+|---|---|---|
+| `abl login` | Sign in, save key locally | free (once) |
+| `abl logout` | Remove local key | free |
+| `abl whoami` | Show key prefix + balance | 5 cr |
+| `abl credits` | Show credit balance | 5 cr |
+| `abl models` | List catalog models | 5-300+ cr |
+| `abl models <id>` | Fetch one model | 10 cr |
+| `abl authors` | List authors | 5-15 cr |
+| `abl authors <id>` | Fetch one author | 1 cr |
+| `abl methods` | List M-code taxonomy | 5-15 cr |
+| `abl methods <id>` | Fetch one method | 1 cr |
+| `abl datasets` | List alignment datasets | 5-15 cr |
+| `abl datasets <id>` | Fetch one dataset | 1 cr |
+| `abl indices` | All four flagship indices | 20 cr |
+| `abl indices <id>` | One index with history | 10 cr |
+| `abl timeline` | Curated field events | 50 cr |
+
+Every command has `--help` for full flag documentation.
+
+## Pricing shape
+
+Model routes carry an anti-scrape price shape: the cost of `abl models` grows steeply as you page deeper into the catalog. A filtered lookup up to 200 rows always costs 5 credits. A full 1000-row page on the first page costs 300; on page 10, 5100. Filter cheap, dump expensive — see [/api#pricing](https://abliteration.org/api#pricing) for the full formula.
+
+Every response prints the actual cost and your remaining balance in the footer.
+
+## Machine-readable output
+
+Add `--json` to any command to get the full envelope as JSON on stdout:
+
+```bash
+$ abl models --method M4 --limit 3 --json
+{
+  "data": [ ... ],
+  "cost": 5,
+  "credits_remaining": 495,
+  "rate_limit_limit": 60,
+  "rate_limit_remaining": 59,
+  "metering": "billed",
+  "request_id": "..."
+}
+```
+
+## Environment
+
+- `ABLITERATION_API_KEY` — overrides `~/.abliteration/config.json`
+- `ABLITERATION_API_BASE` — overrides `https://abliteration.org`
+- `ABL_DEBUG=1` — print full stack traces on errors
+
+## Docs
+
+- Full API reference: <https://abliteration.org/api>
+- Machine-readable spec: <https://abliteration.org/api/v1/openapi.json>
+- Source: <https://github.com/neymark/abliteration/tree/main/cli>
+
+## License
+
+MIT

package/bin/cli.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * @abliteration/cli entry point.
+ *
+ * The shebang and the file extension together let the same file work as both
+ * `abliteration` and `abl` bin entries declared in package.json. Nothing runs
+ * here beyond delegating to src/main.mjs — the wrapper stays small so a stack
+ * trace never blames a line in the shebang file.
+ */
+import { main } from '../src/main.mjs';
+
+main(process.argv.slice(2)).catch((err) => {
+  // Errors bubbled all the way up are the ones we could not classify; print
+  // a plain message rather than a full stack unless the caller asked for
+  // debug output. Node exits with the code we set.
+  const debug = process.env.ABL_DEBUG === '1';
+  if (debug) {
+    console.error(err);
+  } else {
+    console.error('abl:', err?.message ?? err);
+  }
+  process.exit(err?.exitCode ?? 1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@abliteration/cli",
+  "version": "1.0.0",
+  "description": "Command-line client for the abliteration.org catalog API",
+  "type": "module",
+  "bin": {
+    "abliteration": "./bin/cli.mjs",
+    "abl": "./bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/cli.mjs"
+  },
+  "keywords": [
+    "abliteration",
+    "cli",
+    "llm",
+    "catalog",
+    "api"
+  ],
+  "author": "Catyonic OÜ",
+  "license": "MIT",
+  "homepage": "https://abliteration.org/api",
+  "bugs": {
+    "url": "https://github.com/neymark/abliteration/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neymark/abliteration.git",
+    "directory": "cli"
+  }
+}

package/src/commands/auth.mjs

@@ -0,0 +1,228 @@
+/**
+ * Authentication and account commands.
+ *
+ * `abl login` — paste-a-key flow. Opens the ~/shop/account#api-keys page in
+ *   the user's default browser, prompts them to paste a freshly generated
+ *   key, verifies it with a live /whoami-style call to the API, then writes
+ *   ~/.abliteration/config.json. Deliberately not an OAuth device-code flow:
+ *   the account page already knows how to mint a key, and a copy-paste is
+ *   what a user does anyway when they generate one — the CLI just meets
+ *   them where they are.
+ *
+ * `abl logout` — deletes the config file. Does NOT revoke the key server-
+ *   side because a shared key on a shared laptop might be in use elsewhere;
+ *   the server call to revoke lives at `abl keys revoke <id>` (future PR).
+ *
+ * `abl whoami` — shows the local state (key prefix, config path) plus the
+ *   server's answer to `GET /api/v1/authors/{whatever}` — actually we call
+ *   a cheap route (methods/list is 5cr flat) and read the metering fields.
+ *   Cost is real and shown as such.
+ *
+ * `abl credits` — the cheapest possible way to check balance. Calls
+ *   /methods (5 credits) which is a small fixed cost the server has to
+ *   compute anyway. No dedicated /whoami endpoint exists yet, so this
+ *   piggybacks on an existing route; the trade-off (5 credits per check)
+ *   is documented in the help text.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline/promises';
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+import { get, CliError } from '../lib/client.mjs';
+import { readConfig, writeConfig, deleteConfig, configPath, configExists } from '../lib/config.mjs';
+import { renderFooter, fmtNum } from '../lib/output.mjs';
+
+const ACCOUNT_URL = 'https://abliteration.org/shop/account#api-keys';
+
+/**
+ * Open a URL in the user's default browser. Cross-platform without a
+ * dependency: macOS gets `open`, Windows gets `start`, Linux gets `xdg-open`.
+ * On WSL we fall through to xdg-open which usually routes to the Windows
+ * shell anyway.
+ *
+ * Silently returns on failure — the CLI prints the URL as a fallback, so a
+ * headless machine without a browser still knows where to go.
+ */
+async function openUrl(url) {
+  const p = platform();
+  const cmd = p === 'darwin' ? 'open'
+            : p === 'win32'  ? 'start'
+            :                  'xdg-open';
+  try {
+    const child = spawn(cmd, [url], {
+      detached: true,
+      stdio: 'ignore',
+      shell: p === 'win32', // `start` is a shell builtin, not a binary
+    });
+    child.unref();
+  } catch {
+    /* ignore — the caller printed the URL already */
+  }
+}
+
+/**
+ * Simple TTY prompt with echo. We do NOT hide the key on read because a
+ * masked prompt would fight the user's clipboard-based paste (browser →
+ * terminal) which is the exact flow we designed for. A revoked key is
+ * cheap; a paste that fails silently is not.
+ */
+async function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(question);
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function loginCmd(args) {
+  if (args.help) {
+    console.log(
+      [
+        'Usage: abl login',
+        '',
+        'Opens https://abliteration.org/shop/account#api-keys in your browser,',
+        'prompts for the key you generate there, and saves it to',
+        `  ${configPath()}`,
+        '',
+        'After login, every subsequent `abl` command uses this key until you',
+        'run `abl logout` or overwrite it with another `abl login`.',
+      ].join('\n'),
+    );
+    return 0;
+  }
+
+  console.log('Opening your account page:');
+  console.log(`  ${ACCOUNT_URL}`);
+  console.log('');
+  console.log('If your browser did not open, copy the URL above.');
+  console.log('Generate a new key on that page - the key is shown once, then hashed.');
+  console.log('');
+
+  await openUrl(ACCOUNT_URL);
+
+  const key = await prompt('Paste your API key here: ');
+  if (!key) {
+    throw new CliError('no key entered — aborting.', { code: 'no_key', exitCode: 2 });
+  }
+  if (!key.startsWith('abl_live_') && !key.startsWith('abl_test_')) {
+    throw new CliError(
+      'that does not look like an abliteration key. Keys start with abl_live_ or abl_test_.',
+      { code: 'bad_key', exitCode: 4 },
+    );
+  }
+
+  // Verify against the API by making one cheap authenticated call. If it
+  // works, the key is real, the account is not revoked, and the paywall
+  // recognises this user — all in one 5-credit round trip.
+  //
+  // We temporarily inject the key via env so client.mjs picks it up without
+  // us having to duplicate the fetch logic. Restore afterwards regardless.
+  const savedEnv = process.env.ABLITERATION_API_KEY;
+  process.env.ABLITERATION_API_KEY = key;
+  try {
+    const { meta } = await get('/api/v1/methods');
+    await writeConfig({ key, saved_at: new Date().toISOString() });
+    console.log('');
+    console.log(`Signed in. Key: ${key.slice(0, 12)}...${key.slice(-6)}`);
+    if (meta.creditsRemaining !== null) {
+      console.log(`Balance:    ${fmtNum(meta.creditsRemaining)} credits`);
+    }
+    console.log(`Config:     ${configPath()}`);
+    console.log('');
+    console.log('Try:  abl models --method M4 --limit 5');
+  } finally {
+    if (savedEnv === undefined) delete process.env.ABLITERATION_API_KEY;
+    else process.env.ABLITERATION_API_KEY = savedEnv;
+  }
+  return 0;
+}
+
+export async function logoutCmd(args) {
+  if (args.help) {
+    console.log(
+      [
+        'Usage: abl logout',
+        '',
+        'Removes your local key from the config file. Does NOT revoke the key',
+        'server-side — visit ' + ACCOUNT_URL + ' if you want to revoke it.',
+      ].join('\n'),
+    );
+    return 0;
+  }
+  const existed = await configExists();
+  await deleteConfig();
+  if (existed) {
+    console.log('Signed out. Local config removed.');
+  } else {
+    console.log('No local config to remove.');
+  }
+  return 0;
+}
+
+export async function whoamiCmd(args) {
+  if (args.help) {
+    console.log(
+      [
+        'Usage: abl whoami',
+        '',
+        'Prints the key prefix currently in use, where it came from (env or',
+        'config), and the balance the server reports for it. Costs 5 credits',
+        '(one /methods call) to check because the API has no dedicated whoami.',
+      ].join('\n'),
+    );
+    return 0;
+  }
+
+  // Prefer env; fall back to config. Do NOT print the full key — only the
+  // prefix. Anyone shoulder-surfing the terminal already sees the prefix
+  // on the CF /shop/account page, so this leaks nothing new.
+  const envKey = process.env.ABLITERATION_API_KEY;
+  let source, prefix;
+  if (envKey) {
+    source = 'ABLITERATION_API_KEY';
+    prefix = envKey.slice(0, 12);
+  } else {
+    const cfg = await readConfig();
+    if (!cfg?.key) {
+      console.log('Not signed in. Run `abl login`.');
+      return 2;
+    }
+    source = configPath();
+    prefix = cfg.key.slice(0, 12);
+  }
+
+  const { meta } = await get('/api/v1/methods');
+  console.log(`Key source:  ${source}`);
+  console.log(`Key prefix:  ${prefix}...`);
+  if (meta.creditsRemaining !== null) {
+    console.log(`Balance:     ${fmtNum(meta.creditsRemaining)} credits`);
+  }
+  console.log('');
+  process.stdout.write(renderFooter(meta));
+  return 0;
+}
+
+export async function creditsCmd(args) {
+  if (args.help) {
+    console.log(
+      [
+        'Usage: abl credits',
+        '',
+        'Prints your current credit balance. Costs 5 credits because it uses',
+        'the /methods list route as a probe (no dedicated balance endpoint).',
+        'Use `abl whoami` for the same info plus the key prefix.',
+      ].join('\n'),
+    );
+    return 0;
+  }
+  const { meta } = await get('/api/v1/methods');
+  if (meta.creditsRemaining === null) {
+    console.log('Balance unavailable (metering is in preview).');
+  } else {
+    console.log(`${fmtNum(meta.creditsRemaining)} credits`);
+  }
+  return 0;
+}

package/src/commands/catalog.mjs

@@ -0,0 +1,312 @@
+/**
+ * Catalog commands.
+ *
+ * One command per API resource. Each command has two shapes:
+ *   - `abl <resource>` — list route, prints a table (or JSON)
+ *   - `abl <resource> <id>` — single-entity route, prints a key/value block
+ *
+ * List commands share the same set of paging and format flags: --limit,
+ * --offset, --sort, --json. Filter flags vary by resource and are declared
+ * in the `filters` map below.
+ *
+ * The output layer is always the same: for --json we JSON.stringify the raw
+ * server payload including cost and credits_remaining, so a script consuming
+ * the CLI sees the same envelope it would see from curl. For the human
+ * output we render a table or entity block plus the standard footer.
+ */
+
+import { get } from '../lib/client.mjs';
+import { renderTable, renderEntity, renderFooter, fmtNum } from '../lib/output.mjs';
+
+/**
+ * Emit either JSON or the human-readable rendering. Return the exit code.
+ *
+ * Kept in one place so every list command follows the same rule: when
+ * --json is on, stdout is machine-readable and stderr carries any warnings;
+ * when --json is off, stdout is human-readable and the footer prints there.
+ */
+function emit(payload, options) {
+  if (options.json) {
+    // Reconstruct the full envelope shape rather than dumping `data` alone,
+    // so a piped consumer can read cost + credits_remaining without a second
+    // API call.
+    process.stdout.write(
+      JSON.stringify(
+        {
+          data: payload.data,
+          cost: payload.meta.cost,
+          credits_remaining: payload.meta.creditsRemaining,
+          rate_limit_limit: payload.meta.rateLimit.limit,
+          rate_limit_remaining: payload.meta.rateLimit.remaining,
+          rate_limit_reset: payload.meta.rateLimit.reset,
+          metering: payload.meta.metering,
+          request_id: payload.meta.requestId,
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+  } else {
+    if (Array.isArray(payload.data)) {
+      process.stdout.write(renderTable(payload.data, options.columns));
+    } else if (payload.data && typeof payload.data === 'object') {
+      process.stdout.write(renderEntity(payload.data));
+    } else {
+      process.stdout.write(String(payload.data) + '\n');
+    }
+    process.stdout.write(renderFooter(payload.meta));
+  }
+  return 0;
+}
+
+/* ---------- models ---------- */
+
+const MODEL_COLUMNS = [
+  { header: 'ID',        key: 'id',        align: 'left'  },
+  { header: 'Method',    key: 'method',    align: 'left'  },
+  { header: 'Family',    key: 'family',    align: 'left'  },
+  { header: 'License',   key: 'license',   align: 'left'  },
+  { header: 'Downloads', key: 'downloads', align: 'right' },
+];
+
+export async function modelsCmd(args) {
+  if (args.help) return printModelsHelp();
+  if (args._[0]) return getModel(args._[0], args);
+
+  const payload = await get('/api/v1/models', {
+    method: args.method,
+    family: args.family,
+    author: args.author,
+    license: args.license,
+    downloads_gte: args['downloads-gte'],
+    downloads_lte: args['downloads-lte'],
+    created_after: args['created-after'],
+    created_before: args['created-before'],
+    sort: args.sort,
+    limit: args.limit,
+    offset: args.offset,
+  });
+  return emit(payload, { json: args.json, columns: MODEL_COLUMNS });
+}
+
+async function getModel(id, args) {
+  const payload = await get(`/api/v1/models/${encodeURIComponent(id)}`);
+  return emit(payload, { json: args.json });
+}
+
+function printModelsHelp() {
+  console.log(
+    [
+      'Usage: abl models [flags]',
+      '       abl models <id>',
+      '',
+      'List catalog models or fetch one by id (author/name).',
+      '',
+      'Filter flags:',
+      '  --method <code>          M-code, e.g. M4',
+      '  --family <str>           base family, e.g. qwen, llama',
+      '  --author <handle>        publisher handle',
+      '  --license <str>          SPDX-ish license',
+      '  --downloads-gte <n>      minimum downloads',
+      '  --downloads-lte <n>      maximum downloads',
+      '  --created-after <date>   ISO date, inclusive',
+      '  --created-before <date>  ISO date, inclusive',
+      '',
+      'Sort and paging:',
+      '  --sort <key>             -downloads (default), created_at, -created_at, ...',
+      '  --limit <n>              rows to return, 1-1000',
+      '  --offset <n>             rows to skip',
+      '',
+      'Output:',
+      '  --json                   machine-readable envelope (data + cost + ...)',
+      '',
+      'Cost:',
+      '  - one model by id: 10 credits (models are priced above authors/methods',
+      '    because iterating over ids is functionally a slow dump)',
+      '  - list: 5-300+ credits, stepped by returned rows and multiplied by',
+      '    (1 + (offset/2500)²). Filter cheap, dump expensive — see',
+      '    https://abliteration.org/api#pricing for the full table.',
+    ].join('\n'),
+  );
+  return 0;
+}
+
+/* ---------- authors ---------- */
+
+const AUTHOR_COLUMNS = [
+  { header: 'Author',    key: 'author',          align: 'left'  },
+  { header: 'Models',    key: 'total_models',    align: 'right' },
+  { header: 'Downloads', key: 'total_downloads', align: 'right' },
+  { header: 'Likes',     key: 'total_likes',     align: 'right' },
+];
+
+export async function authorsCmd(args) {
+  if (args.help) return printResourceHelp('authors', ['-total_downloads', '-total_models']);
+  if (args._[0]) return emit(
+    await get(`/api/v1/authors/${encodeURIComponent(args._[0])}`),
+    { json: args.json },
+  );
+  const payload = await get('/api/v1/authors', {
+    sort: args.sort,
+    limit: args.limit,
+    offset: args.offset,
+  });
+  return emit(payload, { json: args.json, columns: AUTHOR_COLUMNS });
+}
+
+/* ---------- methods ---------- */
+
+const METHOD_COLUMNS = [
+  { header: 'Code',      key: 'id',              align: 'left'  },
+  { header: 'Label',     key: 'label',           align: 'left'  },
+  { header: 'Category',  key: 'category',        align: 'left'  },
+  { header: 'Models',    key: 'model_count',     align: 'right' },
+  { header: 'Downloads', key: 'total_downloads', align: 'right' },
+];
+
+export async function methodsCmd(args) {
+  if (args.help) return printResourceHelp('methods', []);
+  if (args._[0]) return emit(
+    await get(`/api/v1/methods/${encodeURIComponent(args._[0])}`),
+    { json: args.json },
+  );
+  return emit(await get('/api/v1/methods'), { json: args.json, columns: METHOD_COLUMNS });
+}
+
+/* ---------- datasets ---------- */
+
+const DATASET_COLUMNS = [
+  { header: 'ID',        key: 'id',             align: 'left'  },
+  { header: 'Category',  key: 'category',       align: 'left'  },
+  { header: 'License',   key: 'license',        align: 'left'  },
+  { header: 'Downloads', key: 'downloads_all',  align: 'right' },
+  { header: 'Likes',     key: 'likes',          align: 'right' },
+];
+
+export async function datasetsCmd(args) {
+  if (args.help) return printResourceHelp('datasets', ['-downloads', 'created_at']);
+  if (args._[0]) return emit(
+    await get(`/api/v1/datasets/${encodeURIComponent(args._[0])}`),
+    { json: args.json },
+  );
+  const payload = await get('/api/v1/datasets', {
+    category: args.category,
+    author: args.author,
+    license: args.license,
+    sort: args.sort,
+    limit: args.limit,
+    offset: args.offset,
+  });
+  return emit(payload, { json: args.json, columns: DATASET_COLUMNS });
+}
+
+/* ---------- indices ---------- */
+
+const INDEX_COLUMNS = [
+  { header: 'ID',       key: 'id',       align: 'left'  },
+  { header: 'Name',     key: 'name',     align: 'left'  },
+  { header: 'Value',    key: 'value',    align: 'right', format: (v, r) => v === null ? '-' : `${fmtNum(v)}${r.unit === 'percent' ? '%' : r.unit === 'days' ? 'd' : ''}` },
+  { header: 'Source',   key: 'source',   align: 'left'  },
+  { header: 'Measured', key: 'measured', align: 'left', format: (v) => v ? 'yes' : 'no' },
+];
+
+export async function indicesCmd(args) {
+  if (args.help) {
+    console.log(
+      [
+        'Usage: abl indices',
+        '       abl indices <id>',
+        '',
+        'Fetch the four flagship indices at once (Freedom Velocity, Weaponization,',
+        'F2W Latency, DAI) or one by id with its full history.',
+        '',
+        'Cost:',
+        '  - all four: 20 credits (heavy: Freedom Velocity is a full scan)',
+        '  - one by id: 10 credits (full time-series, not a row lookup)',
+      ].join('\n'),
+    );
+    return 0;
+  }
+  if (args._[0]) return emit(
+    await get(`/api/v1/indices/${encodeURIComponent(args._[0])}`),
+    { json: args.json },
+  );
+  return emit(await get('/api/v1/indices'), { json: args.json, columns: INDEX_COLUMNS });
+}
+
+/* ---------- timeline ---------- */
+
+const TIMELINE_COLUMNS = [
+  { header: 'Date',  key: 'date',  align: 'left' },
+  { header: 'Type',  key: 'type',  align: 'left' },
+  { header: 'Title', key: 'title', align: 'left' },
+];
+
+export async function timelineCmd(args) {
+  if (args.help) {
+    console.log(
+      [
+        'Usage: abl timeline [flags]',
+        '',
+        'Fetch curated field events - delistings, takedowns, notable releases.',
+        '',
+        'Filter flags:',
+        '  --from <date>            ISO date, inclusive lower bound',
+        '  --to <date>              ISO date, inclusive upper bound',
+        '  --event-type <str>       filter by event type',
+        '  --limit <n>              rows to return, default 100',
+        '',
+        'Output:',
+        '  --json                   machine-readable envelope',
+        '',
+        'Cost: 50 credits, flat. Timeline is the largest single response the API',
+        'serves, hence the higher cost.',
+      ].join('\n'),
+    );
+    return 0;
+  }
+  const payload = await get('/api/v1/timeline', {
+    from: args.from,
+    to: args.to,
+    event_type: args['event-type'],
+    limit: args.limit,
+  });
+  return emit(payload, { json: args.json, columns: TIMELINE_COLUMNS });
+}
+
+/* ---------- shared help printer ---------- */
+
+function printResourceHelp(name, sortHints) {
+  const filterHints = {
+    authors: [],
+    methods: [],
+    datasets: [
+      '  --category <str>         workflow stage, e.g. heal',
+      '  --author <handle>        publisher handle',
+      '  --license <str>          SPDX-ish license',
+    ],
+  }[name] || [];
+  console.log(
+    [
+      `Usage: abl ${name} [flags]`,
+      `       abl ${name} <id>`,
+      '',
+      `List ${name} or fetch one by id.`,
+      '',
+      ...(filterHints.length ? ['Filter flags:', ...filterHints, ''] : []),
+      'Sort and paging:',
+      `  --sort <key>             ${sortHints.join(', ') || 'default sort'}`,
+      '  --limit <n>              rows to return, 1-1000',
+      '  --offset <n>             rows to skip',
+      '',
+      'Output:',
+      '  --json                   machine-readable envelope',
+      '',
+      'Cost:',
+      `  - single entity: 1 credit`,
+      `  - list: 5-15 credits, by rows returned (5 for the first 100 rows,`,
+      `    +1 per further 100, capped at 15). Empty result still costs 5.`,
+    ].join('\n'),
+  );
+  return 0;
+}

package/src/lib/client.mjs

@@ -0,0 +1,167 @@
+/**
+ * HTTP client for the abliteration.org API.
+ *
+ * One place that talks to the network so every command benefits from the
+ * same error mapping. Callers get either the parsed `data` payload (unwrapped
+ * from the envelope) plus meta on success, or a typed CliError on failure —
+ * they never touch fetch, headers, or status codes themselves.
+ *
+ * The envelope shape mirrors src/lib/api/v1/response.ts on the server:
+ *   { data, cost, credits_remaining, rate_limit_*, metering, request_id }
+ * Only `data` gets returned to callers; everything else is bundled into
+ * `meta` for commands that want to print it (all of them do, for the
+ * "cost: 5 · balance: 495" footer).
+ */
+
+import { readConfig } from './config.mjs';
+
+/** Default API base for the abliteration.org production deployment. */
+const DEFAULT_BASE = 'https://abliteration.org';
+
+/**
+ * A CliError carries an exit code so the top-level catch can hand it to
+ * process.exit. Kept small: `message` is what the user sees, `code` is the
+ * machine-readable slug returned by the server or one we minted locally,
+ * `exitCode` is the shell exit status. Nothing else — a stack trace on a
+ * 402 would just be noise.
+ */
+export class CliError extends Error {
+  constructor(message, { code = 'error', exitCode = 1 } = {}) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Resolve the API base URL. Env var wins so a developer testing against a
+ * staging deployment can point every command at it in one place; otherwise
+ * we use the production host. The trailing slash is stripped so callers can
+ * always append `/api/v1/...` without a double slash.
+ */
+export function apiBase() {
+  const raw = process.env.ABLITERATION_API_BASE ?? DEFAULT_BASE;
+  return raw.replace(/\/+$/, '');
+}
+
+/**
+ * Resolve the API key. Env variable ABLITERATION_API_KEY wins so a CI job can
+ * override without editing the on-disk config; otherwise we read the config
+ * file written by `abl login`. Missing key is a CliError, not undefined,
+ * because every non-help command needs one.
+ */
+export async function apiKey() {
+  const env = process.env.ABLITERATION_API_KEY;
+  if (env && env.trim()) return env.trim();
+  const cfg = await readConfig();
+  if (cfg?.key) return cfg.key;
+  throw new CliError(
+    'no API key found. run `abl login`, or export ABLITERATION_API_KEY=abl_live_...',
+    { code: 'no_key', exitCode: 2 },
+  );
+}
+
+/**
+ * Perform an authenticated GET against /api/v1/<path>. Returns
+ * `{ data, meta }` on success. Errors are mapped to CliError with the
+ * server's own slug when we can extract one.
+ *
+ * `params` accepts strings, numbers, and booleans. Undefined and null are
+ * dropped so a call site can pass every flag it received without filtering
+ * first. Arrays are joined with commas because the current API takes CSV
+ * for list-valued filters (methods, families).
+ */
+export async function get(path, params = {}) {
+  const key = await apiKey();
+  const url = new URL(apiBase() + path);
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === null || v === '') continue;
+    if (Array.isArray(v)) {
+      if (v.length === 0) continue;
+      url.searchParams.set(k, v.join(','));
+    } else {
+      url.searchParams.set(k, String(v));
+    }
+  }
+
+  let res;
+  try {
+    res = await fetch(url.toString(), {
+      headers: {
+        authorization: `Bearer ${key}`,
+        'user-agent': `abliteration-cli/1.0.0 node/${process.versions.node}`,
+        accept: 'application/json',
+      },
+    });
+  } catch (err) {
+    // Network-layer failure — DNS, TLS, connection refused. The server side
+    // never saw the request, so nothing was charged. Callers get a
+    // network_error slug so a wrapper script can retry with backoff.
+    throw new CliError(`network error: ${err?.message ?? err}`, {
+      code: 'network_error',
+      exitCode: 3,
+    });
+  }
+
+  // A response with no body at all (204, or a proxy blip) is not something
+  // the API produces on this route. Bail before parsing so json() does not
+  // throw an opaque SyntaxError.
+  const text = await res.text();
+  let body;
+  try {
+    body = text ? JSON.parse(text) : {};
+  } catch {
+    throw new CliError(
+      `unexpected non-JSON response from ${url.pathname} (status ${res.status})`,
+      { code: 'bad_response', exitCode: 4 },
+    );
+  }
+
+  if (!res.ok) {
+    // Server-returned errors carry an `error` slug and a `message` from
+    // response.ts. Prefer the server's message when present because it names
+    // the specific route and the specific balance for 402s.
+    const code = body?.error ?? `http_${res.status}`;
+    const msg = body?.message ?? `HTTP ${res.status}`;
+    const cliCode =
+      res.status === 401 ? 'unauthorized' :
+      res.status === 402 ? code :
+      res.status === 404 ? 'not_found' :
+      res.status === 429 ? 'rate_limit' :
+      code;
+    throw new CliError(msg, { code: cliCode, exitCode: exitFor(res.status) });
+  }
+
+  return {
+    data: body?.data,
+    meta: {
+      cost: body?.cost ?? 0,
+      creditsRemaining: body?.credits_remaining ?? null,
+      rateLimit: {
+        limit: body?.rate_limit_limit ?? null,
+        remaining: body?.rate_limit_remaining ?? null,
+        reset: body?.rate_limit_reset ?? null,
+      },
+      metering: body?.metering ?? null,
+      requestId: body?.request_id ?? null,
+    },
+  };
+}
+
+/**
+ * Map HTTP status to a shell exit code. Not every status gets a distinct
+ * number — a wrapper script only cares about the coarse category:
+ *   2 – configuration / auth (401)
+ *   3 – transient (429, 5xx)
+ *   4 – permanent input problem (400, 404, 422)
+ *   5 – payment (402)
+ * Anything else is a plain 1.
+ */
+function exitFor(status) {
+  if (status === 401) return 2;
+  if (status === 402) return 5;
+  if (status === 429 || status >= 500) return 3;
+  if (status === 400 || status === 404 || status === 422) return 4;
+  return 1;
+}

package/src/lib/config.mjs

@@ -0,0 +1,116 @@
+/**
+ * Read and write ~/.abliteration/config.json.
+ *
+ * Storing an API key on disk is a permission-and-portability problem more
+ * than a cryptographic one — anyone who can read the file can already read
+ * the process env of a script that uses it. What we buy with a real config
+ * file is:
+ *   1. One place the CLI reads from, so a login persists across shells.
+ *   2. File-mode 0600 so a shared laptop's other users cannot cat it.
+ *   3. A JSON shape we can extend (per-profile keys, region overrides)
+ *      without rewriting the loader.
+ *
+ * Env variables still take precedence in client.mjs — that path never
+ * touches this file. The config is the "no ceremony" default for the
+ * interactive terminal user.
+ */
+
+import { readFile, writeFile, mkdir, chmod, unlink, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * Location of the config directory and file. Resolved at call time (not at
+ * import) so tests can set HOME to a temp dir and get isolated files without
+ * a module reload.
+ */
+export function configPath() {
+  return join(homedir(), '.abliteration', 'config.json');
+}
+
+/**
+ * Read the config file if it exists. Returns null when the file is missing —
+ * that is the normal state before `abl login`. A file that exists but is
+ * unreadable, malformed, or contains something other than an object counts
+ * as "no config"; the CLI then falls through to whatever env var the caller
+ * set, or prompts for `abl login`. Silent recovery matches the "the CLI just
+ * works" expectation better than a syntax-error trace.
+ */
+export async function readConfig() {
+  const path = configPath();
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return null;
+    // Anything else — permission denied, disk error — is worth surfacing
+    // rather than silently ignoring, because the user might have chmod'd
+    // themselves out of their own config.
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  return parsed;
+}
+
+/**
+ * Write a fresh config file. Always overwrites — the CLI has one key at a
+ * time and login supersedes whatever was there. Creates the directory tree
+ * if needed and clamps permissions to 0600 (owner read/write only) after
+ * the write, because writeFile alone honours the process umask which may
+ * be 022 (world-readable). Directory perms follow the same logic at 0700.
+ *
+ * We write to a temp file and rename so a partial write during a crash
+ * leaves the previous config intact instead of a truncated JSON that
+ * subsequent reads would treat as no config at all.
+ */
+export async function writeConfig(cfg) {
+  const path = configPath();
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  // mkdir + recursive does not chmod an existing directory, so set it
+  // explicitly. Failures here are not fatal — the file itself will still
+  // be 0600, which is what actually protects the secret.
+  try { await chmod(dir, 0o700); } catch { /* best effort */ }
+
+  const tmp = `${path}.tmp.${process.pid}`;
+  await writeFile(tmp, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+  await chmod(tmp, 0o600);
+  // Atomic rename replaces the old file in one step, so any concurrent
+  // reader sees either the old file or the new one, never a truncation.
+  const { rename } = await import('node:fs/promises');
+  await rename(tmp, path);
+}
+
+/**
+ * Remove the config file. Used by `abl logout`. Missing file is not an
+ * error — the caller wanted "no config" and got it.
+ */
+export async function deleteConfig() {
+  const path = configPath();
+  try {
+    await unlink(path);
+  } catch (err) {
+    if (err?.code === 'ENOENT') return;
+    throw err;
+  }
+}
+
+/**
+ * Whether the config file exists at all. Cheaper than reading it and used
+ * by `abl whoami` to decide between "signed in as X" and "not signed in".
+ */
+export async function configExists() {
+  try {
+    await stat(configPath());
+    return true;
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false;
+    throw err;
+  }
+}

package/src/lib/output.mjs

@@ -0,0 +1,157 @@
+/**
+ * Human-readable table output.
+ *
+ * The CLI has two output modes: default (a formatted table into a TTY) and
+ * --json (a machine-readable dump into anything). Everything here lives in
+ * default mode; --json bypasses this file entirely by JSON.stringifying the
+ * server payload as-is.
+ *
+ * The table is width-aware but not smart. Every column measures the widest
+ * string in itself, pads with spaces to that width, and joins with two
+ * spaces. That produces the plain aligned columns the tizer on the home
+ * page promises — no borders, no boxes, no colour. Boxes and colour are
+ * the two most common ways a CLI becomes unreadable on the wrong terminal
+ * (paged into less -R, dumped into a file, viewed on a light theme with a
+ * dark palette). Plain columns render everywhere.
+ */
+
+/**
+ * Return the visible width of a string. process.stdout carries the terminal
+ * columns when stdout is a TTY; when it is piped we default to 80 so a
+ * `abl models | less` still produces a sensible table rather than a single
+ * wrapped line.
+ */
+export function termWidth() {
+  return process.stdout.columns || 80;
+}
+
+/**
+ * Format a number with thousand separators, matching the download counts on
+ * the /models pages. `null` and `undefined` render as `-` so a row with a
+ * missing column does not collapse the whole table.
+ */
+export function fmtNum(n) {
+  if (n === null || n === undefined) return '-';
+  const int = Math.trunc(n);
+  return int.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+/**
+ * Render a list of objects as an aligned table.
+ *
+ * `columns` is an array of { header, key, align?, format? }. `align` is
+ * 'left' by default; 'right' is honoured on numeric columns (downloads,
+ * likes, params_b). `format(value, row)` returns a string; when omitted we
+ * use `fmtNum` on numbers and `String()` on everything else.
+ *
+ * Rows are truncated per-column if the total width would exceed the
+ * terminal width. The truncation adds a trailing `…` so the reader knows
+ * the string is cut. Header line uses `-` separators one line down, styled
+ * like `git log --pretty=short` output.
+ */
+export function renderTable(rows, columns) {
+  if (!rows.length) return '(no rows)\n';
+
+  // Compute each cell's formatted string once so we can measure widths and
+  // print without recomputing. Store parallel to `rows` in the same order.
+  const cells = rows.map((row) =>
+    columns.map((col) => {
+      const raw = row[col.key];
+      if (col.format) return col.format(raw, row);
+      if (typeof raw === 'number') return fmtNum(raw);
+      if (raw === null || raw === undefined) return '-';
+      return String(raw);
+    }),
+  );
+
+  // Column widths: max of header and every cell in that column.
+  const widths = columns.map((col, i) => {
+    const cellMax = cells.reduce((max, r) => Math.max(max, r[i].length), 0);
+    return Math.max(col.header.length, cellMax);
+  });
+
+  // If the sum of widths + separators is wider than the terminal, shrink
+  // the longest text column (the leftmost 'left' column by default). This
+  // keeps the numeric columns readable and truncates the id/name column.
+  const sep = 2;
+  const target = termWidth();
+  let total = widths.reduce((a, b) => a + b, 0) + sep * (widths.length - 1);
+  if (total > target) {
+    // Find the widest left-aligned column and shrink it by the overflow.
+    const overflow = total - target;
+    let idx = -1;
+    let widest = -1;
+    for (let i = 0; i < columns.length; i++) {
+      const align = columns[i].align ?? 'left';
+      if (align === 'left' && widths[i] > widest) {
+        widest = widths[i];
+        idx = i;
+      }
+    }
+    if (idx >= 0 && widths[idx] - overflow > 4) {
+      widths[idx] -= overflow;
+    }
+  }
+
+  const pad = (str, width, align) => {
+    if (str.length > width) {
+      // Truncate with an ellipsis so the reader sees the row was cut.
+      return str.slice(0, Math.max(1, width - 1)) + '…';
+    }
+    return align === 'right' ? str.padStart(width, ' ') : str.padEnd(width, ' ');
+  };
+
+  const line = (values) => values.map((v, i) => pad(v, widths[i], columns[i].align ?? 'left')).join('  ');
+
+  const out = [];
+  out.push(line(columns.map((c) => c.header)));
+  out.push(line(widths.map((w) => '-'.repeat(Math.min(w, 32)))));
+  for (const c of cells) out.push(line(c));
+  return out.join('\n') + '\n';
+}
+
+/**
+ * Render a single-entity payload as an aligned "key: value" block. Used by
+ * `abl models <id>`, `abl authors <id>`, etc. — every field on its own line
+ * so grep and awk work naturally.
+ */
+export function renderEntity(obj) {
+  const entries = Object.entries(obj).filter(([, v]) => v !== undefined);
+  const keyWidth = Math.max(...entries.map(([k]) => k.length));
+  return (
+    entries
+      .map(([k, v]) => {
+        const key = k.padEnd(keyWidth);
+        const value = v === null
+          ? '-'
+          : typeof v === 'object'
+          ? JSON.stringify(v)
+          : typeof v === 'number'
+          ? fmtNum(v)
+          : String(v);
+        return `${key}  ${value}`;
+      })
+      .join('\n') + '\n'
+  );
+}
+
+/**
+ * Footer line printed after every successful command:
+ *   cost: 5 credits · balance: 495 · request_id: abc-…
+ *
+ * When metering is off (preview mode on the server) we replace the balance
+ * with the word "preview" so a scripted caller does not read a stale number
+ * as if it were the truth.
+ */
+export function renderFooter(meta) {
+  const parts = [`cost: ${meta.cost} cr`];
+  if (meta.metering === 'preview') {
+    parts.push('preview (not billed)');
+  } else if (meta.creditsRemaining !== null) {
+    parts.push(`balance: ${fmtNum(meta.creditsRemaining)}`);
+  }
+  if (meta.rateLimit?.remaining !== null && meta.rateLimit?.limit !== null) {
+    parts.push(`rate: ${meta.rateLimit.remaining}/${meta.rateLimit.limit}`);
+  }
+  return parts.join(' · ') + '\n';
+}

package/src/main.mjs

@@ -0,0 +1,178 @@
+/**
+ * Argument parser and command dispatcher.
+ *
+ * The parser is deliberately small: no external dependency, no plugin
+ * system, just enough to route `abl models --method M4 --limit 5` and
+ * `abl models mlabonne/Qwen3-30B-A3B-abliterated` to the right handler.
+ *
+ * Rules:
+ *   - The first non-flag argument is the command (`models`, `login`, …).
+ *   - Anything after that until the next flag is a positional (the id).
+ *   - `--flag value` and `--flag=value` are equivalent.
+ *   - `--flag` with no value is a boolean true.
+ *   - `--` stops flag parsing so an id containing `--` still passes through.
+ *   - Unknown commands print the top-level help and exit 2.
+ *
+ * We do not implement short flags (`-m` for `--method`). Every abbreviation
+ * is another rule the reader has to remember and the CLI already lives at
+ * the terminal, where tab completion covers the "short" case.
+ */
+
+import { loginCmd, logoutCmd, whoamiCmd, creditsCmd } from './commands/auth.mjs';
+import {
+  modelsCmd, authorsCmd, methodsCmd, datasetsCmd, indicesCmd, timelineCmd,
+} from './commands/catalog.mjs';
+
+const COMMANDS = {
+  login: loginCmd,
+  logout: logoutCmd,
+  whoami: whoamiCmd,
+  credits: creditsCmd,
+  models: modelsCmd,
+  authors: authorsCmd,
+  methods: methodsCmd,
+  datasets: datasetsCmd,
+  indices: indicesCmd,
+  timeline: timelineCmd,
+};
+
+const COMMAND_HELP = {
+  login: 'sign in and save a key to ~/.abliteration/config.json',
+  logout: 'remove the local key',
+  whoami: 'show the current key prefix and balance',
+  credits: 'show credit balance only',
+  models: 'list catalog models or fetch one by id',
+  authors: 'list authors or fetch one by id',
+  methods: 'list the M-code taxonomy or fetch one by id',
+  datasets: 'list alignment datasets or fetch one by id',
+  indices: 'fetch the four flagship indices or one by id',
+  timeline: 'fetch curated field events',
+};
+
+/**
+ * Parse process.argv-style tokens into `{ _: [positional], flag: value, … }`.
+ * Values that look like numbers become numbers. `--json` alone is `true`.
+ */
+export function parseArgs(argv) {
+  const out = { _: [] };
+  let stopFlags = false;
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (stopFlags) {
+      out._.push(tok);
+      continue;
+    }
+    if (tok === '--') {
+      stopFlags = true;
+      continue;
+    }
+    if (tok.startsWith('--')) {
+      const eq = tok.indexOf('=');
+      let name, value;
+      if (eq >= 0) {
+        name = tok.slice(2, eq);
+        value = tok.slice(eq + 1);
+      } else {
+        name = tok.slice(2);
+        // A flag consumes the next token as its value unless that token
+        // starts with `--` (another flag), in which case the current flag
+        // is a boolean.
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith('--')) {
+          value = next;
+          i++;
+        } else {
+          value = true;
+        }
+      }
+      if (typeof value === 'string' && /^-?\d+(\.\d+)?$/.test(value)) {
+        value = Number(value);
+      }
+      out[name] = value;
+      continue;
+    }
+    out._.push(tok);
+  }
+  return out;
+}
+
+function printTopHelp() {
+  console.log(
+    [
+      'abliteration CLI - abliteration.org catalog client',
+      '',
+      'Usage: abl <command> [args] [flags]',
+      '',
+      'Auth:',
+      '  abl login              sign in and save a key',
+      '  abl logout             remove the local key',
+      '  abl whoami             show key prefix and balance (5 cr)',
+      '  abl credits            show credit balance (5 cr)',
+      '',
+      'Catalog:',
+      '  abl models             list models (5-300+ cr, offset-multiplied)',
+      '  abl models <id>        fetch one model (10 cr)',
+      '  abl authors            list authors (5-15 cr)',
+      '  abl authors <id>       fetch one author (1 cr)',
+      '  abl methods            list the M-code taxonomy (5-15 cr)',
+      '  abl methods <id>       fetch one method (1 cr)',
+      '  abl datasets           list alignment datasets (5-15 cr)',
+      '  abl datasets <id>      fetch one dataset (1 cr)',
+      '  abl indices            all four flagship indices (20 cr)',
+      '  abl indices <id>       one index with history (10 cr)',
+      '  abl timeline           curated field events (50 cr)',
+      '',
+      'Global flags:',
+      '  --json                 machine-readable envelope on stdout',
+      '  --help                 command-specific help',
+      '',
+      'Environment:',
+      '  ABLITERATION_API_KEY   overrides the config file',
+      '  ABLITERATION_API_BASE  overrides the default server (staging)',
+      '  ABL_DEBUG=1            print full stack traces on errors',
+      '',
+      'Full documentation: https://abliteration.org/api',
+      'Machine spec:       https://abliteration.org/api/v1/openapi.json',
+    ].join('\n'),
+  );
+}
+
+/**
+ * Dispatch a parsed argv into a command. Returns the command's exit code,
+ * which the shell script wrapper hands to process.exit.
+ */
+export async function main(argv) {
+  const args = parseArgs(argv);
+
+  // `abl` with no args, `abl --help`, and `abl help` all print the top help.
+  if (args._.length === 0 || args.help && args._.length === 0) {
+    printTopHelp();
+    return 0;
+  }
+
+  const [command, ...rest] = args._;
+
+  // `abl help models` is the same as `abl models --help`.
+  if (command === 'help' && rest[0]) {
+    const target = rest[0];
+    const fn = COMMANDS[target];
+    if (!fn) {
+      console.error(`abl: unknown command "${target}"`);
+      printTopHelp();
+      return 2;
+    }
+    return fn({ ...args, _: rest.slice(1), help: true });
+  }
+
+  const fn = COMMANDS[command];
+  if (!fn) {
+    console.error(`abl: unknown command "${command}"`);
+    console.error('');
+    printTopHelp();
+    return 2;
+  }
+
+  // Re-parse so the command sees positionals that were AFTER its name and
+  // not the command name itself. --help is preserved.
+  return fn({ ...args, _: rest });
+}