@llmintel/cli 0.2.0

package/README.md

@@ -0,0 +1,118 @@
+# @llmintel/cli
+
+Fail your CI build when it references **retired or soon-to-be-retired AI models**.
+
+`llmintel check` scans your code/config for referenced model ids (and/or takes explicit ids),
+looks up their lifecycle state via the [LLMIntel API](https://llmintel.vercel.app/docs), and exits
+non-zero when any referenced model is **retired or past its retirement date** — so you migrate on
+your schedule, not the provider's shutoff date.
+
+## Install
+
+No install required — run it with `npx`:
+
+```bash
+npx @llmintel/cli@latest check src config
+```
+
+Or add it as a dev dependency:
+
+```bash
+npm install --save-dev @llmintel/cli
+```
+
+## Authenticate
+
+Create an API key from your [dashboard](https://llmintel.vercel.app/dashboard) and expose it as an
+environment variable:
+
+```bash
+export LLMINTEL_API_KEY="mc_live_..."
+```
+
+## Usage
+
+```bash
+# Scan files/directories for referenced model ids and gate on lifecycle state:
+llmintel check src config
+
+# Check explicit ids/aliases without scanning:
+llmintel check --models "gpt-4o,claude-3-opus-20240229"
+
+# Use a config file:
+llmintel check --config llmintel.json
+```
+
+### Options
+
+| Flag                  | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| `-m, --models <a,b,c>` | Explicit model ids/aliases to check (repeatable)                       |
+| `-c, --config <file>`  | JSON config: `{ "models": [...], "paths": [...], "warnDays": 90 }`     |
+| `--api-url <url>`      | API base URL (env `LLMINTEL_API_URL`, default `https://llmintel.vercel.app`) |
+| `--api-key <key>`      | API key (env `LLMINTEL_API_KEY`)                                     |
+| `--warn-days <n>`      | Warn when a model retires within this many days (default `90`)         |
+| `--fail-on-warn`       | Treat warnings (deprecated / retiring soon) as build failures          |
+| `--fail-on-unknown`    | Treat references LLMIntel does not track as build failures           |
+| `--no-policy`          | Ignore your account's central policy; use only the flags above         |
+| `--optimize`           | Also print advisory cheaper/faster model suggestions (paid; never fails the build) |
+| `--json`               | Machine-readable JSON output                                           |
+| `-q, --quiet`          | Only print failures                                                    |
+
+## Central gate policy
+
+By default `check` fails only on **retired** (or past-due) models — free forever. On a paid plan
+you can configure a stricter policy **once** in your [dashboard](https://llmintel.vercel.app/dashboard)
+and every pipeline picks it up automatically: fail on `deprecated`/`retiring`, set the warn
+window, and fail on untracked references.
+
+`check` fetches this policy on each run and uses it as the baseline. Explicit local flags
+(`--warn-days`, `--fail-on-unknown`) override it; pass `--no-policy` to ignore it entirely. Free
+accounts are always clamped to the retired-only gate regardless of any saved policy.
+
+## Auto-watch your codebase (`sync`)
+
+`llmintel sync` discovers the models your code references — the same scan as `check` — and
+registers them as your account's **watched set** server-side. Combined with push alerts
+(webhook / Slack / PagerDuty), this gives you "fire and forget" coverage: run `sync` in CI on
+merge to `main`, and you'll be notified the moment a model you actually use is deprecated or
+retired, with no watchlist to curate by hand.
+
+```bash
+# Replace your watched set with whatever your code references now:
+llmintel sync src config
+
+# Preview the diff without writing anything:
+llmintel sync src config --dry-run
+
+# Only add models; never remove ones you watch elsewhere:
+llmintel sync src config --no-prune
+```
+
+`sync` requires a paid plan with auto-watch enabled and an API key linked to an account. It prints
+the diff of `added` / `removed` / `unchanged` watches plus any `unresolved` references.
+
+### Exit codes
+
+| Code | Meaning                                                       |
+| ---- | ------------------------------------------------------------- |
+| `0`  | All referenced models healthy                                 |
+| `1`  | One or more errors (retired / past due), or warnings with `--fail-on-warn` |
+| `2`  | Usage / configuration error                                   |
+| `3`  | API or network error                                          |
+
+## GitHub Actions
+
+A composite action ships alongside the CLI:
+
+```yaml
+- uses: hivemindunit/llmintel-cli/packages/cli@main
+  with:
+    api-key: ${{ secrets.LLMINTEL_API_KEY }}
+    paths: "src config"
+    warn-days: "90"
+```
+
+## License
+
+MIT

package/action.yml

@@ -0,0 +1,61 @@
+name: "LLMIntel Check"
+description: "Fail your build when it references retired or soon-to-be-retired AI models."
+author: "LLMIntel"
+branding:
+  icon: "clock"
+  color: "orange"
+
+inputs:
+  api-key:
+    description: "LLMIntel API key. Store it as a repository secret and pass it here."
+    required: true
+  paths:
+    description: "Space-separated files/directories to scan for model references."
+    required: false
+    default: "."
+  models:
+    description: "Comma-separated explicit model ids/aliases to check (in addition to scanned paths)."
+    required: false
+    default: ""
+  config:
+    description: "Path to a JSON config file ({ models, paths, warnDays, apiUrl })."
+    required: false
+    default: ""
+  api-url:
+    description: "LLMIntel API base URL."
+    required: false
+    default: "https://llmintel.vercel.app"
+  warn-days:
+    description: "Warn when a model retires within this many days."
+    required: false
+    default: "90"
+  fail-on-warn:
+    description: "Treat warnings (deprecated / retiring soon) as build failures."
+    required: false
+    default: "false"
+  fail-on-unknown:
+    description: "Treat references that LLMIntel does not track as build failures."
+    required: false
+    default: "false"
+  version:
+    description: "npm version/tag of the CLI to run (e.g. latest, 0.1.0)."
+    required: false
+    default: "latest"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Run llmintel check
+      shell: bash
+      env:
+        LLMINTEL_API_KEY: ${{ inputs.api-key }}
+        LLMINTEL_API_URL: ${{ inputs.api-url }}
+      run: |
+        args=(check)
+        for p in ${{ inputs.paths }}; do args+=("$p"); done
+        if [ -n "${{ inputs.models }}" ]; then args+=(--models "${{ inputs.models }}"); fi
+        if [ -n "${{ inputs.config }}" ]; then args+=(--config "${{ inputs.config }}"); fi
+        args+=(--warn-days "${{ inputs.warn-days }}")
+        if [ "${{ inputs.fail-on-warn }}" = "true" ]; then args+=(--fail-on-warn); fi
+        if [ "${{ inputs.fail-on-unknown }}" = "true" ]; then args+=(--fail-on-unknown); fi
+        npx --yes @llmintel/cli@${{ inputs.version }} "${args[@]}"

package/dist/index.js

@@ -0,0 +1,806 @@
+#!/usr/bin/env node
+
+// src/client.ts
+var ApiError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "ApiError";
+  }
+  status;
+  code;
+};
+function networkError(base, cause) {
+  const raw = cause instanceof Error ? cause.message : String(cause);
+  const text = `${raw} ${String(cause?.cause?.code ?? "")}`;
+  const unreachable = /ENOTFOUND|EAI_AGAIN|getaddrinfo|ECONNREFUSED|ECONNRESET|ETIMEDOUT|UND_ERR/i.test(text);
+  if (unreachable) {
+    return new ApiError(
+      `Could not reach the LLMIntel API at ${base} (${raw}). Check the host is correct \u2014 override it with --api-url or the LLMINTEL_API_URL env var.`
+    );
+  }
+  return new ApiError(`Network error contacting ${base}: ${raw}`);
+}
+var PAGE_SIZE = 500;
+async function fetchAllModels(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  const all = [];
+  let offset = 0;
+  for (; ; ) {
+    const url = `${base}/v1/models?limit=${PAGE_SIZE}&offset=${offset}`;
+    let response;
+    try {
+      response = await fetchImpl(url, {
+        headers: { authorization: `Bearer ${options.apiKey}`, accept: "application/json" }
+      });
+    } catch (cause) {
+      throw networkError(base, cause);
+    }
+    if (!response.ok) {
+      let code;
+      let message = `${response.status} ${response.statusText}`;
+      try {
+        const body2 = await response.json();
+        code = body2.error;
+        if (body2.message) message = body2.message;
+      } catch {
+      }
+      throw new ApiError(message, response.status, code);
+    }
+    const body = await response.json();
+    all.push(...body.data);
+    if (body.data.length < PAGE_SIZE) break;
+    offset += PAGE_SIZE;
+  }
+  return all;
+}
+async function syncWatches(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  const url = `${base}/v1/watches`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: "PUT",
+      headers: {
+        authorization: `Bearer ${options.apiKey}`,
+        accept: "application/json",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ models: options.models, prune: options.prune })
+    });
+  } catch (cause) {
+    throw networkError(base, cause);
+  }
+  if (!response.ok) {
+    let code;
+    let message = `${response.status} ${response.statusText}`;
+    try {
+      const errBody = await response.json();
+      code = errBody.error;
+      if (errBody.message) message = errBody.message;
+    } catch {
+    }
+    throw new ApiError(message, response.status, code);
+  }
+  const body = await response.json();
+  return body.data;
+}
+async function fetchPolicy(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  const url = `${base}/v1/policy`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { authorization: `Bearer ${options.apiKey}`, accept: "application/json" }
+    });
+  } catch (cause) {
+    throw networkError(base, cause);
+  }
+  if (!response.ok) {
+    let code;
+    let message = `${response.status} ${response.statusText}`;
+    try {
+      const errBody = await response.json();
+      code = errBody.error;
+      if (errBody.message) message = errBody.message;
+    } catch {
+    }
+    throw new ApiError(message, response.status, code);
+  }
+  const body = await response.json();
+  return body.data;
+}
+async function fetchOptimization(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  const path = options.modelId.split("/").map(encodeURIComponent).join("/");
+  const url = `${base}/v1/models/${path}`;
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { authorization: `Bearer ${options.apiKey}`, accept: "application/json" }
+    });
+  } catch (cause) {
+    throw networkError(base, cause);
+  }
+  if (!response.ok) {
+    let code;
+    let message = `${response.status} ${response.statusText}`;
+    try {
+      const errBody = await response.json();
+      code = errBody.error;
+      if (errBody.message) message = errBody.message;
+    } catch {
+    }
+    throw new ApiError(message, response.status, code);
+  }
+  const body = await response.json();
+  return body.data.optimization ?? null;
+}
+
+// src/config.ts
+import { readFile } from "fs/promises";
+var ConfigError = class extends Error {
+};
+async function loadConfig(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (cause) {
+    throw new ConfigError(`Cannot read config file "${path}": ${cause.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new ConfigError(`Invalid JSON in "${path}": ${cause.message}`);
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new ConfigError(`Config "${path}" must be a JSON object.`);
+  }
+  const config = parsed;
+  const result = {};
+  if (config.models !== void 0) {
+    if (!Array.isArray(config.models) || config.models.some((m) => typeof m !== "string")) {
+      throw new ConfigError(`Config "models" must be an array of strings.`);
+    }
+    result.models = config.models;
+  }
+  if (config.paths !== void 0) {
+    if (!Array.isArray(config.paths) || config.paths.some((p) => typeof p !== "string")) {
+      throw new ConfigError(`Config "paths" must be an array of strings.`);
+    }
+    result.paths = config.paths;
+  }
+  if (config.warnDays !== void 0) {
+    if (typeof config.warnDays !== "number" || config.warnDays < 0) {
+      throw new ConfigError(`Config "warnDays" must be a non-negative number.`);
+    }
+    result.warnDays = Math.floor(config.warnDays);
+  }
+  if (config.apiUrl !== void 0) {
+    if (typeof config.apiUrl !== "string") throw new ConfigError(`Config "apiUrl" must be a string.`);
+    result.apiUrl = config.apiUrl;
+  }
+  return result;
+}
+
+// src/extract.ts
+var QUOTED = /['"`]([A-Za-z0-9][A-Za-z0-9._/-]{2,80})['"`]/g;
+function looksLikeModel(token) {
+  if (!/\d/.test(token)) return false;
+  if (!/[-/]/.test(token)) return false;
+  if (token.includes("://") || token.startsWith("/") || token.includes("\\")) return false;
+  if (/\.(js|ts|tsx|jsx|json|py|go|rb|java|css|html|md|png|svg|lock)$/i.test(token)) return false;
+  return true;
+}
+function extractReferences(text, source) {
+  const found = /* @__PURE__ */ new Map();
+  for (const match of text.matchAll(QUOTED)) {
+    const token = match[1];
+    if (token && looksLikeModel(token) && !found.has(token)) {
+      found.set(token, { value: token, source });
+    }
+  }
+  return [...found.values()];
+}
+function dedupeReferences(lists) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (const ref of list) {
+      if (!seen.has(ref.value)) seen.set(ref.value, ref);
+    }
+  }
+  return [...seen.values()];
+}
+
+// src/gate.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function daysUntil(isoDate, now) {
+  const target = (/* @__PURE__ */ new Date(`${isoDate}T00:00:00Z`)).getTime();
+  const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  return Math.round((target - today) / DAY_MS);
+}
+function buildIndex(models) {
+  const index = /* @__PURE__ */ new Map();
+  for (const model of models) {
+    index.set(model.id.toLowerCase(), model);
+    for (const alias of model.aliases) {
+      index.set(alias.toLowerCase(), model);
+    }
+  }
+  return index;
+}
+function evaluateReference(reference, index, options, now) {
+  const model = index.get(reference.value.toLowerCase()) ?? null;
+  const failOn = options.failOn ?? ["retired"];
+  if (!model) {
+    return {
+      reference,
+      model: null,
+      severity: options.failOnUnknown ? "error" : "unknown",
+      reason: "not tracked by LLMIntel",
+      daysUntilRetirement: null
+    };
+  }
+  const days = model.retirementDate ? daysUntil(model.retirementDate, now) : null;
+  if (failOn.includes(model.lifecycleState)) {
+    const reason = model.lifecycleState === "retired" ? "retired \u2014 API calls fail" : `${model.lifecycleState} (policy fails on this state)`;
+    return { reference, model, severity: "error", reason, daysUntilRetirement: days };
+  }
+  if (days !== null && days < 0) {
+    return {
+      reference,
+      model,
+      severity: "error",
+      reason: `retirement date ${model.retirementDate} has passed`,
+      daysUntilRetirement: days
+    };
+  }
+  const within = days !== null && days <= options.warnDays;
+  if (model.lifecycleState === "deprecated" || model.lifecycleState === "retiring" || within) {
+    const when = days !== null ? `retires in ${days} day${days === 1 ? "" : "s"} (${model.retirementDate})` : model.lifecycleState;
+    return { reference, model, severity: "warn", reason: when, daysUntilRetirement: days };
+  }
+  return { reference, model, severity: "ok", reason: model.lifecycleState, daysUntilRetirement: days };
+}
+var EMPTY_COUNTS = () => ({ ok: 0, warn: 0, error: 0, unknown: 0 });
+function buildReport(references, models, options, now = /* @__PURE__ */ new Date()) {
+  const index = buildIndex(models);
+  const findings = references.map((ref) => evaluateReference(ref, index, options, now));
+  const counts = EMPTY_COUNTS();
+  for (const finding of findings) counts[finding.severity] += 1;
+  let exitCode = 0;
+  if (counts.error > 0) exitCode = 1;
+  else if (options.failOnWarn && counts.warn > 0) exitCode = 1;
+  return { findings, counts, exitCode };
+}
+
+// src/report.ts
+var SYMBOLS = {
+  ok: "ok   ",
+  warn: "WARN ",
+  error: "FAIL ",
+  unknown: "?    "
+};
+function formatHuman(report, quiet) {
+  const lines = [];
+  const rows = report.findings.filter((f) => quiet ? f.severity === "error" || f.severity === "warn" : true);
+  for (const finding of rows) {
+    const id = finding.model?.id ?? finding.reference.value;
+    lines.push(`  ${SYMBOLS[finding.severity]} ${id} \u2014 ${finding.reason}  [${finding.reference.source}]`);
+  }
+  if (lines.length > 0) lines.push("");
+  lines.push(
+    `Checked ${report.findings.length} reference(s): ${report.counts.error} error, ${report.counts.warn} warn, ${report.counts.unknown} unknown, ${report.counts.ok} ok.`
+  );
+  return lines.join("\n");
+}
+function formatJson(report, optimizations = []) {
+  return JSON.stringify(
+    {
+      exitCode: report.exitCode,
+      counts: report.counts,
+      findings: report.findings.map((f) => ({
+        reference: f.reference.value,
+        source: f.reference.source,
+        modelId: f.model?.id ?? null,
+        provider: f.model?.provider ?? null,
+        lifecycleState: f.model?.lifecycleState ?? null,
+        retirementDate: f.model?.retirementDate ?? null,
+        daysUntilRetirement: f.daysUntilRetirement,
+        severity: f.severity,
+        reason: f.reason
+      })),
+      optimizations: optimizations.map((o) => ({
+        modelId: o.modelId,
+        candidateId: o.candidateId,
+        candidateProvider: o.candidateProvider,
+        reasons: o.reasons,
+        crossProvider: o.crossProvider
+      }))
+    },
+    null,
+    2
+  );
+}
+function formatOptimization(optimizations) {
+  if (optimizations.length === 0) return "";
+  const lines = ["", "Optimization suggestions (advisory \u2014 does not affect the build):"];
+  for (const o of optimizations) {
+    const switchNote = o.crossProvider ? ` (switch to ${o.candidateProvider})` : "";
+    lines.push(`  ~ ${o.modelId} \u2192 ${o.candidateId}${switchNote}: ${o.reasons.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+// src/scan.ts
+import { readdir, readFile as readFile2, stat } from "fs/promises";
+import { join } from "path";
+var IGNORE_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  ".next",
+  "dist",
+  "build",
+  "coverage",
+  ".turbo",
+  ".vercel",
+  "vendor",
+  "__pycache__"
+]);
+var MAX_FILE_BYTES = 2 * 1024 * 1024;
+async function scanPath(path) {
+  let info;
+  try {
+    info = await stat(path);
+  } catch {
+    return [];
+  }
+  if (info.isDirectory()) {
+    const entries = await readdir(path, { withFileTypes: true });
+    const results = await Promise.all(
+      entries.map((entry) => {
+        if (entry.isDirectory() && IGNORE_DIRS.has(entry.name)) return Promise.resolve([]);
+        return scanPath(join(path, entry.name));
+      })
+    );
+    return results.flat();
+  }
+  if (info.size > MAX_FILE_BYTES) return [];
+  try {
+    const text = await readFile2(path, "utf8");
+    return extractReferences(text, path);
+  } catch {
+    return [];
+  }
+}
+async function scanPaths(paths) {
+  const lists = await Promise.all(paths.map(scanPath));
+  return lists.flat();
+}
+
+// src/sync.ts
+function formatSyncHuman(summary, quiet) {
+  const lines = [];
+  const prefix = summary.dryRun ? "Would" : "Did";
+  if (!quiet) {
+    for (const id of summary.added) lines.push(`  + ${id}`);
+    for (const id of summary.removed) lines.push(`  - ${id}`);
+  }
+  for (const ref of summary.unresolved) lines.push(`  ? ${ref} \u2014 not tracked by LLMIntel`);
+  if (lines.length > 0) lines.push("");
+  lines.push(
+    `${prefix} sync ${summary.discovered} discovered reference(s): ${summary.added.length} added, ${summary.removed.length} removed, ${summary.unchanged.length} unchanged, ${summary.unresolved.length} unresolved.`
+  );
+  return lines.join("\n");
+}
+function formatSyncJson(summary) {
+  return JSON.stringify(
+    {
+      dryRun: summary.dryRun,
+      discovered: summary.discovered,
+      added: summary.added,
+      removed: summary.removed,
+      unchanged: summary.unchanged,
+      unresolved: summary.unresolved
+    },
+    null,
+    2
+  );
+}
+
+// src/args.ts
+var DEFAULT_API_URL = "https://llmintel.vercel.app";
+var DEFAULT_WARN_DAYS = 90;
+var UsageError = class extends Error {
+};
+function parseModelsList(value) {
+  return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function parseArgs(argv, env = process.env) {
+  const options = {
+    command: "help",
+    models: [],
+    paths: [],
+    config: null,
+    apiUrl: env.LLMINTEL_API_URL ?? DEFAULT_API_URL,
+    apiKey: env.LLMINTEL_API_KEY ?? null,
+    warnDays: DEFAULT_WARN_DAYS,
+    failOnWarn: false,
+    failOnUnknown: false,
+    json: false,
+    quiet: false,
+    dryRun: false,
+    prune: true,
+    usePolicy: true,
+    optimize: false,
+    explicit: { warnDays: false, failOnWarn: false, failOnUnknown: false }
+  };
+  const positional = [];
+  let i = 0;
+  const first = argv[0];
+  if (first === "check" || first === "sync" || first === "help" || first === "version") {
+    options.command = first;
+    i = 1;
+  } else if (first === "--version" || first === "-v") {
+    options.command = "version";
+    return options;
+  } else if (first === "--help" || first === "-h" || first === void 0) {
+    options.command = "help";
+    return options;
+  } else {
+    options.command = "check";
+  }
+  const need = (flag, value) => {
+    if (value === void 0) throw new UsageError(`Missing value for ${flag}`);
+    return value;
+  };
+  for (; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === void 0) continue;
+    switch (arg) {
+      case "--models":
+      case "-m":
+        options.models.push(...parseModelsList(need(arg, argv[++i])));
+        break;
+      case "--config":
+      case "-c":
+        options.config = need(arg, argv[++i]);
+        break;
+      case "--api-url":
+        options.apiUrl = need(arg, argv[++i]);
+        break;
+      case "--api-key":
+        options.apiKey = need(arg, argv[++i]);
+        break;
+      case "--warn-days": {
+        const raw = need(arg, argv[++i]);
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n < 0) throw new UsageError(`--warn-days must be a non-negative number, got "${raw}"`);
+        options.warnDays = Math.floor(n);
+        options.explicit.warnDays = true;
+        break;
+      }
+      case "--fail-on-warn":
+        options.failOnWarn = true;
+        options.explicit.failOnWarn = true;
+        break;
+      case "--fail-on-unknown":
+        options.failOnUnknown = true;
+        options.explicit.failOnUnknown = true;
+        break;
+      case "--no-policy":
+        options.usePolicy = false;
+        break;
+      case "--optimize":
+        options.optimize = true;
+        break;
+      case "--dry-run":
+        options.dryRun = true;
+        break;
+      case "--prune":
+        options.prune = true;
+        break;
+      case "--no-prune":
+        options.prune = false;
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      case "--quiet":
+      case "-q":
+        options.quiet = true;
+        break;
+      case "--help":
+      case "-h":
+        options.command = "help";
+        return options;
+      default:
+        if (arg.startsWith("-")) throw new UsageError(`Unknown flag: ${arg}`);
+        positional.push(arg);
+    }
+  }
+  options.paths = positional;
+  return options;
+}
+var HELP_TEXT = `llmintel \u2014 gate and track AI model lifecycle state in CI/CD
+
+Usage:
+  llmintel check [paths...] [options]   Fail the build on retired/at-risk models
+  llmintel sync  [paths...] [options]   Auto-watch the models your code uses (paid)
+
+check
+  Scans the given files/directories (and/or --models) for referenced AI model ids,
+  looks up their lifecycle state via the LLMIntel API, and exits non-zero when any
+  referenced model is retired (or past due). Deprecated/retiring models, or models
+  retiring within --warn-days, are reported as warnings.
+
+  The gate also applies your account's central policy (configured in the dashboard):
+  the baseline failOn set, warn window, and fail-on-unknown. Explicit local flags
+  override the policy; pass --no-policy to ignore it and use only local flags.
+
+sync
+  Discovers the models referenced in your codebase (same scan as check) and registers
+  them as your account's watched set, so push alerts (webhook/Slack/PagerDuty) track
+  your real footprint with no manual upkeep. Run it in CI on merge to keep the set in
+  sync with your code. Replaces the watch set by default; use --no-prune to only add.
+  Requires a paid plan.
+
+Options:
+  -m, --models <a,b,c>     Explicit model ids/aliases (repeatable)
+  -c, --config <file>      JSON config: { "models": [...], "paths": [...] }
+      --api-url <url>      API base URL        (env LLMINTEL_API_URL, default https://llmintel.vercel.app)
+      --api-key <key>      API key             (env LLMINTEL_API_KEY)
+      --warn-days <n>      check: warn window in days (default 90)
+      --fail-on-warn       check: exit non-zero on warnings too
+      --fail-on-unknown    check: treat unresolved references as errors
+      --no-policy          check: ignore the account's central policy (use local flags only)
+      --optimize           check: also show advisory cheaper/faster model suggestions (paid; never fails the build)
+      --dry-run            sync: print the diff without writing
+      --no-prune           sync: only add models, never remove
+      --json               Machine-readable JSON output
+  -q, --quiet              Only print failures / changes
+  -h, --help               Show this help
+  -v, --version            Show version
+
+Exit codes:
+  0  success (check: all healthy; sync: applied or dry-run)
+  1  check: one or more errors (retired / past due), or warnings with --fail-on-warn
+  2  usage/configuration error
+  3  API or network error
+`;
+
+// src/index.ts
+import { pathToFileURL } from "url";
+import { realpathSync } from "fs";
+var EXIT_OK = 0;
+var EXIT_USAGE = 2;
+var EXIT_API = 3;
+var VERSION = "0.1.1";
+async function mergeConfig(options, env) {
+  let paths = options.paths;
+  let models = options.models;
+  let warnDays = options.warnDays;
+  let apiUrl = options.apiUrl;
+  if (options.config) {
+    const config = await loadConfig(options.config);
+    if (config.models) models = [...models, ...config.models];
+    if (config.paths) paths = [...paths, ...config.paths];
+    if (config.warnDays !== void 0 && options.warnDays === 90) warnDays = config.warnDays;
+    if (config.apiUrl && env.LLMINTEL_API_URL === void 0) apiUrl = config.apiUrl;
+  }
+  return { paths, models, warnDays, apiUrl };
+}
+async function gatherReferences(models, paths) {
+  const explicit = models.map((value) => ({ value, source: "--models" }));
+  const scanned = paths.length > 0 ? await scanPaths(paths) : [];
+  return dedupeReferences([explicit, scanned]);
+}
+async function run(deps) {
+  let options;
+  try {
+    options = parseArgs(deps.argv, deps.env);
+  } catch (cause) {
+    if (cause instanceof UsageError) {
+      deps.error(`error: ${cause.message}
+`);
+      deps.error(HELP_TEXT);
+      return EXIT_USAGE;
+    }
+    throw cause;
+  }
+  if (options.command === "help") {
+    deps.log(HELP_TEXT);
+    return EXIT_OK;
+  }
+  if (options.command === "version") {
+    deps.log(VERSION);
+    return EXIT_OK;
+  }
+  let config;
+  try {
+    config = await mergeConfig(options, deps.env);
+  } catch (cause) {
+    if (cause instanceof ConfigError) {
+      deps.error(`error: ${cause.message}`);
+      return EXIT_USAGE;
+    }
+    throw cause;
+  }
+  if (!options.apiKey) {
+    deps.error("error: no API key. Pass --api-key or set LLMINTEL_API_KEY.");
+    return EXIT_USAGE;
+  }
+  if (config.models.length === 0 && config.paths.length === 0) {
+    deps.error("error: nothing to check. Pass file paths and/or --models.");
+    deps.error(HELP_TEXT);
+    return EXIT_USAGE;
+  }
+  const references = await gatherReferences(config.models, config.paths);
+  if (references.length === 0) {
+    deps.error("error: no model references found in the given paths.");
+    return EXIT_USAGE;
+  }
+  if (options.command === "sync") {
+    return runSync(deps, options, config, references);
+  }
+  return runCheck(deps, options, config, references);
+}
+async function runCheck(deps, options, config, references) {
+  const fetchModels = deps.fetchModels ?? fetchAllModels;
+  let apiModels;
+  try {
+    apiModels = await fetchModels({ baseUrl: config.apiUrl, apiKey: options.apiKey });
+  } catch (cause) {
+    if (cause instanceof ApiError) {
+      deps.error(`error: API request failed: ${cause.message}`);
+      return EXIT_API;
+    }
+    throw cause;
+  }
+  let warnDays = config.warnDays;
+  let failOnUnknown = options.failOnUnknown;
+  let failOn = ["retired"];
+  if (options.usePolicy) {
+    const getPolicy = deps.fetchPolicy ?? fetchPolicy;
+    try {
+      const policy = await getPolicy({ baseUrl: config.apiUrl, apiKey: options.apiKey });
+      failOn = policy.failOn.filter(
+        (s) => ["announced", "active", "legacy", "deprecated", "retiring", "retired"].includes(s)
+      );
+      if (failOn.length === 0) failOn = ["retired"];
+      if (!options.explicit.warnDays) warnDays = policy.warnWindowDays;
+      if (!options.explicit.failOnUnknown) failOnUnknown = policy.failOnUnknown;
+    } catch (cause) {
+      if (!options.quiet) {
+        const detail = cause instanceof ApiError ? cause.message : String(cause);
+        deps.error(`note: could not fetch account policy (${detail}); using local flags only.`);
+      }
+    }
+  }
+  const report = buildReport(references, apiModels, {
+    warnDays,
+    failOnWarn: options.failOnWarn,
+    failOnUnknown,
+    failOn
+  });
+  let nudges = [];
+  if (options.optimize) {
+    nudges = await gatherOptimizations(deps, options, config, references, apiModels);
+  }
+  if (options.json) {
+    deps.log(formatJson(report, nudges));
+  } else {
+    deps.log(formatHuman(report, options.quiet));
+    const opt = formatOptimization(nudges);
+    if (opt) deps.log(opt);
+  }
+  return report.exitCode;
+}
+var MAX_OPTIMIZE_LOOKUPS = 25;
+async function gatherOptimizations(deps, options, config, references, apiModels) {
+  const getOptimization = deps.fetchOptimization ?? fetchOptimization;
+  const index = buildIndex(apiModels);
+  const activeIds = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const ref of references) {
+    const model = index.get(ref.value.toLowerCase());
+    if (!model || model.lifecycleState !== "active") continue;
+    if (seen.has(model.id)) continue;
+    seen.add(model.id);
+    activeIds.push(model.id);
+    if (activeIds.length >= MAX_OPTIMIZE_LOOKUPS) break;
+  }
+  const nudges = [];
+  for (const modelId of activeIds) {
+    try {
+      const optimization = await getOptimization({
+        baseUrl: config.apiUrl,
+        apiKey: options.apiKey,
+        modelId
+      });
+      if (!optimization) continue;
+      for (const c of optimization.candidates) {
+        nudges.push({
+          modelId,
+          candidateId: c.candidateId,
+          candidateDisplayName: c.candidateDisplayName,
+          candidateProvider: c.candidateProvider,
+          reasons: c.reasons,
+          crossProvider: c.crossProvider
+        });
+      }
+    } catch (cause) {
+      if (!options.quiet) {
+        const detail = cause instanceof ApiError ? cause.message : String(cause);
+        deps.error(`note: optimization lookup for ${modelId} failed (${detail}); skipping.`);
+      }
+    }
+  }
+  return nudges;
+}
+async function runSync(deps, options, config, references) {
+  const sync = deps.syncWatches ?? syncWatches;
+  const discovered = [...new Set(references.map((r) => r.value))];
+  if (options.dryRun) {
+    const summary2 = {
+      added: discovered.sort(),
+      removed: [],
+      unchanged: [],
+      unresolved: [],
+      dryRun: true,
+      discovered: discovered.length
+    };
+    deps.log(options.json ? formatSyncJson(summary2) : formatSyncHuman(summary2, options.quiet));
+    return EXIT_OK;
+  }
+  let result;
+  try {
+    result = await sync({
+      baseUrl: config.apiUrl,
+      apiKey: options.apiKey,
+      models: discovered,
+      prune: options.prune
+    });
+  } catch (cause) {
+    if (cause instanceof ApiError) {
+      deps.error(`error: API request failed: ${cause.message}`);
+      return EXIT_API;
+    }
+    throw cause;
+  }
+  const summary = { ...result, dryRun: false, discovered: discovered.length };
+  deps.log(options.json ? formatSyncJson(summary) : formatSyncHuman(summary, options.quiet));
+  return EXIT_OK;
+}
+async function main() {
+  const code = await run({
+    argv: process.argv.slice(2),
+    env: process.env,
+    log: (msg) => process.stdout.write(`${msg}
+`),
+    error: (msg) => process.stderr.write(`${msg}
+`)
+  });
+  process.exit(code);
+}
+var isEntrypoint = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    return false;
+  }
+})();
+if (isEntrypoint) {
+  void main();
+}
+export {
+  run
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@llmintel/cli",
+  "version": "0.2.0",
+  "description": "Fail your CI build when it references retired or soon-to-be-retired AI models. The LLMIntel lifecycle gate.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "llmintel": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "action.yml",
+    "README.md"
+  ],
+  "keywords": [
+    "ai",
+    "llm",
+    "deprecation",
+    "lifecycle",
+    "ci",
+    "cd",
+    "openai",
+    "anthropic",
+    "model"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hivemindunit/llmintel-cli.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://llmintel.vercel.app/docs",
+  "bugs": "https://github.com/hivemindunit/llmintel-cli/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "check": "tsx src/index.ts check",
+    "prepublishOnly": "tsup"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@llmintel/schema": "workspace:*",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}