@index365/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 index365
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @index365/cli
+
+Run [index365](https://index365.co) website audits from your terminal, CI, or an AI agent. The CLI is a thin wrapper over the public `/api/v1`, so anything it does, your own agents can do too.
+
+index365 runs two audits: **AI-Readiness** (how well AI agents and AI search can read a site) and **Marketing Signal** (can demand find the site, trust the offer, act, and be measured). Each run produces a score plus findings with stable IDs, evidence, and machine-readable remediation.
+
+## Install
+
+```bash
+npm install -g @index365/cli
+# or run without installing:
+npx @index365/cli --help
+```
+
+## Quickstart
+
+```bash
+index365 login            # paste an i365_ key from the dashboard (Org settings -> API keys)
+index365 doctor           # verify auth, scopes, and API reachability
+index365 projects list    # find a projectId
+index365 runs start --project <id> --wait   # run an AI-readiness audit, wait for the score
+index365 marketing run --project <id> --wait # or run a Marketing Signal audit (separate command tree)
+index365 reports context <runId>            # compact, agent-ready report payload
+index365 findings list --run <runId>        # triage findings
+index365 findings get --run <runId> <findingId>   # full detail + remediation
+```
+
+Add `--json` to any command for machine-readable output. Keys live at `~/.config/index365/config.json` (mode 0600); `INDEX365_API_KEY` overrides the file.
+
+## Exit codes
+
+`0` ok · `1` error · `2` usage · `3` auth · `4` not found · `5` quota/conflict/rate
+
+## MCP
+
+```bash
+index365 mcp config   # prints ready-to-paste config for Claude Code, Codex, and Cursor
+```
+
+## Docs
+
+Full reference: https://index365.co/docs/developers/cli
+
+## License
+
+MIT

package/bin/index365.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.mjs";
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@index365/cli",
+	"version": "0.1.0",
+	"description": "index365 CLI - run AI-readiness and marketing-signal audits and read findings from your terminal, CI, or agents. Wraps the public /api/v1.",
+	"type": "module",
+	"license": "MIT",
+	"author": "index365",
+	"homepage": "https://index365.co/docs/developers/cli",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/index365usa/index365.git",
+		"directory": "packages/cli"
+	},
+	"bugs": {
+		"url": "https://github.com/index365usa/index365/issues"
+	},
+	"keywords": ["index365", "website-audit", "ai-readiness", "seo", "cli", "agent", "mcp"],
+	"publishConfig": {
+		"access": "public"
+	},
+	"bin": {
+		"index365": "./bin/index365.mjs"
+	},
+	"files": ["bin", "src"],
+	"engines": {
+		"node": ">=20.18.0"
+	},
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json",
+		"test": "vitest run",
+		"prepublishOnly": "npm run typecheck && npm run test"
+	},
+	"devDependencies": {
+		"@types/node": "^22.19.19",
+		"typescript": "^5.6.3",
+		"vitest": "^3.2.6"
+	}
+}

package/src/cli.mjs

@@ -0,0 +1,580 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { CliError, EXIT, apiRequest } from "./client.mjs";
+import {
+	configPath,
+	deleteConfigFile,
+	readConfigFile,
+	resolveSettings,
+	writeConfigFile,
+} from "./config.mjs";
+
+export const CLI_VERSION = "0.1.0";
+
+const HELP = `index365 - website audits from your terminal, CI, or agents
+
+USAGE
+  index365 <command> [options]
+
+COMMANDS
+  login              Save an API key (prompts; or --key / INDEX365_API_KEY)
+  logout             Remove the saved API key
+  doctor             Verify auth, scopes, API reachability, contract version
+  projects list      List projects in your organization
+  runs start         Start a paid AI-readiness audit (--project <id>, optional --wait)
+  runs get           Show one run (<runId>)
+  findings list      List findings for a run (--run <id>)
+  findings get       Show one finding (--run <id> <findingId>)
+  reports context    Compact agent report context for a run (<runId>)
+  reports download   Download the PDF report to .index365/ (<runId> [--output <file>])
+  marketing run      Start a Marketing Signal audit (--project <id>, optional --wait)
+  marketing report   Latest Marketing Signal report for a project (--project <id>)
+  marketing findings Marketing findings (--run <id> | --project <id>, optional --stage)
+  integrations list  Connected-signal providers + status (--project <id>)
+  mcp config         Print MCP server config for Claude Code / Codex / Cursor
+
+GLOBAL OPTIONS
+  --json           Machine-readable output (recommended for agents)
+  --api-url <url>  Override the API base URL (default https://index365.co)
+  --help, -h       Show help · --version, -V show version
+
+EXIT CODES
+  0 ok · 1 error · 2 usage · 3 auth · 4 not found · 5 quota/conflict/rate
+
+AUTH
+  Keys are created from an active Agency workspace in the dashboard
+  (Org settings -> API keys) and stored at ~/.config/index365/config.json
+  (0600). INDEX365_API_KEY overrides the file.
+`;
+
+function out(io, line) {
+	io.stdout(line);
+}
+
+function printJson(io, value) {
+	io.stdout(JSON.stringify(value, null, 2));
+}
+
+/** Parse argv for one command; throws CliError(USAGE) on unknown flags. */
+function parse(argv, extraOptions = {}) {
+	try {
+		return parseArgs({
+			args: argv,
+			allowPositionals: true,
+			options: {
+				json: { type: "boolean", default: false },
+				"api-url": { type: "string" },
+				help: { type: "boolean", short: "h", default: false },
+				...extraOptions,
+			},
+		});
+	} catch (err) {
+		throw new CliError(`${err.message}\nRun 'index365 --help' for usage.`, EXIT.USAGE);
+	}
+}
+
+function settingsFor(values, env) {
+	const settings = resolveSettings(env);
+	if (values["api-url"]) settings.apiUrl = String(values["api-url"]).replace(/\/+$/, "");
+	return settings;
+}
+
+async function promptForKey(io) {
+	if (!input.isTTY) {
+		throw new CliError(
+			"No TTY for the key prompt. Pass --key <key> or set INDEX365_API_KEY.",
+			EXIT.USAGE,
+		);
+	}
+	const rl = createInterface({ input, output });
+	try {
+		const answer = await rl.question("Paste your API key (i365_...): ");
+		return answer.trim();
+	} finally {
+		rl.close();
+	}
+}
+
+async function cmdLogin(argv, io, env) {
+	const { values } = parse(argv, { key: { type: "string" } });
+	const key = (values.key ?? env.INDEX365_API_KEY ?? "").trim() || (await promptForKey(io));
+	if (!key.startsWith("i365_")) {
+		throw new CliError("That does not look like an index365 API key (i365_...).", EXIT.USAGE);
+	}
+	const settings = settingsFor(values, env);
+	settings.apiKey = key;
+
+	const me = await apiRequest(settings, "GET", "/api/v1/me", { fetchImpl: io.fetch });
+	const config = readConfigFile(env);
+	config.apiKey = key;
+	if (values["api-url"]) config.apiUrl = settings.apiUrl;
+	const file = writeConfigFile(config, env);
+
+	if (values.json) {
+		printJson(io, { ok: true, configPath: file, ...me });
+	} else {
+		out(
+			io,
+			`Logged in as '${me.keyName}' (${me.keyPrefix}…) for org ${me.organizationSlug ?? me.organizationId}.`,
+		);
+		out(io, `Scopes: ${me.scopes.join(", ")}`);
+		out(io, `Saved to ${file} (0600).`);
+	}
+	return EXIT.OK;
+}
+
+async function cmdLogout(argv, io, env) {
+	const { values } = parse(argv);
+	const removed = deleteConfigFile(env);
+	if (values.json) printJson(io, { ok: true, removed });
+	else out(io, removed ? `Removed ${configPath(env)}.` : "No saved config to remove.");
+	return EXIT.OK;
+}
+
+async function cmdDoctor(argv, io, env) {
+	const { values } = parse(argv);
+	const settings = settingsFor(values, env);
+	const checks = {
+		apiUrl: settings.apiUrl,
+		keyConfigured: Boolean(settings.apiKey),
+		keySource: settings.source,
+		reachable: false,
+		keyPrefix: null,
+		organization: null,
+		scopes: [],
+		apiVersion: null,
+		contractVersion: null,
+	};
+	let ok = checks.keyConfigured;
+	if (settings.apiKey) {
+		try {
+			const me = await apiRequest(settings, "GET", "/api/v1/me", { fetchImpl: io.fetch });
+			checks.reachable = true;
+			checks.keyPrefix = me.keyPrefix;
+			checks.organization = me.organizationSlug ?? me.organizationId;
+			checks.scopes = me.scopes;
+			checks.apiVersion = me.apiVersion;
+			checks.contractVersion = me.contractVersion;
+		} catch (err) {
+			ok = false;
+			checks.error = err.message;
+		}
+	}
+	if (values.json) {
+		printJson(io, { ok, ...checks });
+	} else {
+		out(io, `API URL:    ${checks.apiUrl}`);
+		out(
+			io,
+			`Key:        ${checks.keyConfigured ? `configured (${checks.keySource})` : "MISSING - run 'index365 login'"}`,
+		);
+		if (checks.reachable) {
+			out(io, `Auth:       ok as ${checks.keyPrefix}… (org ${checks.organization})`);
+			out(io, `Scopes:     ${checks.scopes.join(", ")}`);
+			out(io, `API:        ${checks.apiVersion} · contract v${checks.contractVersion}`);
+		} else if (checks.error) {
+			out(io, `Auth:       FAILED - ${checks.error}`);
+		}
+		out(io, ok ? "All good." : "Doctor found problems.");
+	}
+	return ok ? EXIT.OK : EXIT.ERROR;
+}
+
+async function cmdProjects(argv, io, env) {
+	const [sub, ...rest] = argv;
+	if (sub !== "list") throw new CliError("Usage: index365 projects list", EXIT.USAGE);
+	const { values } = parse(rest, {
+		limit: { type: "string" },
+		cursor: { type: "string" },
+	});
+	const settings = settingsFor(values, env);
+	const data = await apiRequest(settings, "GET", "/api/v1/projects", {
+		query: { limit: values.limit, cursor: values.cursor },
+		fetchImpl: io.fetch,
+	});
+	if (values.json) {
+		printJson(io, data);
+	} else {
+		for (const project of data.projects) {
+			out(io, `${project.projectId}  ${project.domain}  (${project.name}, ${project.status})`);
+		}
+		if (data.projects.length === 0) out(io, "No projects.");
+		if (data.pagination.nextCursor) out(io, `More: --cursor ${data.pagination.nextCursor}`);
+	}
+	return EXIT.OK;
+}
+
+const WAIT_POLL_MS = 5_000;
+const WAIT_TIMEOUT_MS = 15 * 60_000;
+const TERMINAL_STATUSES = new Set(["completed", "failed", "failed_auto_credit", "refunded"]);
+
+async function cmdRuns(argv, io, env) {
+	const [sub, ...rest] = argv;
+	if (sub === "start") {
+		const { values } = parse(rest, {
+			project: { type: "string" },
+			"idempotency-key": { type: "string" },
+			wait: { type: "boolean", default: false },
+		});
+		if (!values.project) {
+			throw new CliError("Usage: index365 runs start --project <projectId> [--wait]", EXIT.USAGE);
+		}
+		return startRunAndMaybeWait(values, io, env, "paid_ai_readiness");
+	}
+	if (sub === "get") {
+		const { values, positionals } = parse(rest);
+		const runId = positionals[0];
+		if (!runId) throw new CliError("Usage: index365 runs get <runId>", EXIT.USAGE);
+		const settings = settingsFor(values, env);
+		const run = await apiRequest(settings, "GET", `/api/v1/runs/${runId}`, {
+			fetchImpl: io.fetch,
+		});
+		if (values.json) printJson(io, run);
+		else {
+			out(io, `${run.runId}  ${run.status}  ${run.progressPct}%  ${run.url}`);
+			if (run.score !== null) {
+				out(
+					io,
+					`Score ${run.score}/100 · findings ${run.findingsTotal} · ${JSON.stringify(run.severityCounts)}`,
+				);
+			}
+			out(io, `Human view: ${run.humanUrl}`);
+		}
+		return EXIT.OK;
+	}
+	throw new CliError("Usage: index365 runs <start|get>", EXIT.USAGE);
+}
+
+async function cmdFindings(argv, io, env) {
+	const [sub, ...rest] = argv;
+	if (sub === "list") {
+		const { values } = parse(rest, {
+			run: { type: "string" },
+			severity: { type: "string" },
+			category: { type: "string" },
+			limit: { type: "string" },
+			cursor: { type: "string" },
+		});
+		if (!values.run) throw new CliError("Usage: index365 findings list --run <runId>", EXIT.USAGE);
+		const settings = settingsFor(values, env);
+		const data = await apiRequest(settings, "GET", `/api/v1/runs/${values.run}/findings`, {
+			query: {
+				severity: values.severity,
+				category: values.category,
+				limit: values.limit,
+				cursor: values.cursor,
+			},
+			fetchImpl: io.fetch,
+		});
+		if (values.json) printJson(io, data);
+		else {
+			for (const finding of data.findings) {
+				out(
+					io,
+					`${finding.findingId}  [${finding.severity}/${finding.category}]  ${finding.title}`,
+				);
+			}
+			out(io, `${data.findings.length} of ${data.findingsTotal} findings.`);
+			if (data.pagination.nextCursor) out(io, `More: --cursor ${data.pagination.nextCursor}`);
+		}
+		return EXIT.OK;
+	}
+	if (sub === "get") {
+		const { values, positionals } = parse(rest, { run: { type: "string" } });
+		const findingId = positionals[0];
+		if (!values.run || !findingId) {
+			throw new CliError("Usage: index365 findings get --run <runId> <findingId>", EXIT.USAGE);
+		}
+		const settings = settingsFor(values, env);
+		const data = await apiRequest(
+			settings,
+			"GET",
+			`/api/v1/runs/${values.run}/findings/${findingId}`,
+			{ fetchImpl: io.fetch },
+		);
+		if (values.json) printJson(io, data);
+		else {
+			const f = data.finding;
+			out(io, `${f.findingId} [${f.severity}/${f.category}] ${f.title}`);
+			out(io, f.detail);
+			out(io, `Fix: ${f.remediation}`);
+			out(io, `Affected: ${f.affectedUrls.join(", ")}`);
+		}
+		return EXIT.OK;
+	}
+	throw new CliError("Usage: index365 findings <list|get>", EXIT.USAGE);
+}
+
+async function cmdReports(argv, io, env) {
+	const [sub, ...rest] = argv;
+	if (sub === "context") {
+		const { values, positionals } = parse(rest);
+		const runId = positionals[0];
+		if (!runId) throw new CliError("Usage: index365 reports context <runId>", EXIT.USAGE);
+		const settings = settingsFor(values, env);
+		const data = await apiRequest(settings, "GET", `/api/v1/runs/${runId}/report`, {
+			fetchImpl: io.fetch,
+		});
+		printJson(io, data);
+		return EXIT.OK;
+	}
+	if (sub === "download") {
+		const { values, positionals } = parse(rest, { output: { type: "string" } });
+		const runId = positionals[0];
+		if (!runId) {
+			throw new CliError("Usage: index365 reports download <runId> [--output <file>]", EXIT.USAGE);
+		}
+		const settings = settingsFor(values, env);
+		const link = await apiRequest(settings, "GET", `/api/v1/runs/${runId}/pdf`, {
+			fetchImpl: io.fetch,
+		});
+		const target = values.output ?? `.index365/index365-audit-${runId}.pdf`;
+		const res = await io.fetch(link.url);
+		if (!res.ok) throw new CliError(`PDF download failed (${res.status}).`, EXIT.ERROR);
+		const buffer = Buffer.from(await res.arrayBuffer());
+		mkdirSync(dirname(target), { recursive: true });
+		writeFileSync(target, buffer);
+		if (values.json) printJson(io, { ok: true, file: target, bytes: buffer.length });
+		else out(io, `Saved ${target} (${buffer.length} bytes).`);
+		return EXIT.OK;
+	}
+	throw new CliError("Usage: index365 reports <context|download>", EXIT.USAGE);
+}
+
+/** Shared run-start + optional poll loop (AI-readiness and Marketing Signal). */
+async function startRunAndMaybeWait(values, io, env, scanMode) {
+	const settings = settingsFor(values, env);
+	let run = await apiRequest(settings, "POST", "/api/v1/runs", {
+		body: { projectId: values.project, scanMode },
+		idempotencyKey: values["idempotency-key"],
+		fetchImpl: io.fetch,
+	});
+	if (!values.json) out(io, `Run ${run.runId} ${run.status} (${run.url}).`);
+
+	if (values.wait) {
+		const startedAt = io.now();
+		while (!TERMINAL_STATUSES.has(run.status)) {
+			if (io.now() - startedAt > WAIT_TIMEOUT_MS) {
+				throw new CliError(`Timed out waiting for run ${run.runId}.`, EXIT.ERROR);
+			}
+			await io.sleep(WAIT_POLL_MS);
+			run = await apiRequest(settings, "GET", `/api/v1/runs/${run.runId}`, {
+				fetchImpl: io.fetch,
+			});
+			if (!values.json) out(io, `  ${run.status} ${run.progressPct}% ${run.currentStep ?? ""}`);
+		}
+	}
+	if (values.json) printJson(io, run);
+	else if (values.wait) {
+		out(
+			io,
+			`Run ${run.runId} ${run.status}${run.score !== null ? ` - score ${run.score}/100` : ""}.`,
+		);
+	}
+	return run.status === "completed" || !values.wait ? EXIT.OK : EXIT.ERROR;
+}
+
+async function cmdMarketing(argv, io, env) {
+	const [sub, ...rest] = argv;
+	if (sub === "run") {
+		const { values } = parse(rest, {
+			project: { type: "string" },
+			"idempotency-key": { type: "string" },
+			wait: { type: "boolean", default: false },
+		});
+		if (!values.project) {
+			throw new CliError(
+				"Usage: index365 marketing run --project <projectId> [--wait]",
+				EXIT.USAGE,
+			);
+		}
+		return startRunAndMaybeWait(values, io, env, "paid_marketing_signal");
+	}
+	if (sub === "report") {
+		const { values } = parse(rest, { project: { type: "string" } });
+		if (!values.project) {
+			throw new CliError("Usage: index365 marketing report --project <projectId>", EXIT.USAGE);
+		}
+		const settings = settingsFor(values, env);
+		const data = await apiRequest(
+			settings,
+			"GET",
+			`/api/v1/projects/${values.project}/marketing/report`,
+			{ fetchImpl: io.fetch },
+		);
+		printJson(io, data);
+		return EXIT.OK;
+	}
+	if (sub === "findings") {
+		const { values } = parse(rest, {
+			run: { type: "string" },
+			project: { type: "string" },
+			severity: { type: "string" },
+			stage: { type: "string" },
+			limit: { type: "string" },
+			cursor: { type: "string" },
+		});
+		const settings = settingsFor(values, env);
+		let runId = values.run;
+		if (!runId && values.project) {
+			// Resolve the latest completed marketing run through the project report.
+			const report = await apiRequest(
+				settings,
+				"GET",
+				`/api/v1/projects/${values.project}/marketing/report`,
+				{ fetchImpl: io.fetch },
+			);
+			runId = report.runId;
+		}
+		if (!runId) {
+			throw new CliError(
+				"Usage: index365 marketing findings --run <runId> | --project <projectId>",
+				EXIT.USAGE,
+			);
+		}
+		const data = await apiRequest(settings, "GET", `/api/v1/runs/${runId}/findings`, {
+			query: {
+				severity: values.severity,
+				stage: values.stage,
+				limit: values.limit,
+				cursor: values.cursor,
+			},
+			fetchImpl: io.fetch,
+		});
+		if (values.json) printJson(io, data);
+		else {
+			for (const finding of data.findings) {
+				out(
+					io,
+					`${finding.findingId}  [${finding.severity}/${finding.stage ?? finding.category}]  ${finding.title}`,
+				);
+			}
+			out(io, `${data.findings.length} of ${data.findingsTotal} findings.`);
+			if (data.pagination.nextCursor) out(io, `More: --cursor ${data.pagination.nextCursor}`);
+		}
+		return EXIT.OK;
+	}
+	throw new CliError("Usage: index365 marketing <run|report|findings>", EXIT.USAGE);
+}
+
+async function cmdIntegrations(argv, io, env) {
+	const [sub, ...rest] = argv;
+	// `status` reads the same registry as `list` (per-provider phase + connection).
+	if (sub !== "list" && sub !== "status") {
+		throw new CliError(
+			"Usage: index365 integrations <list|status> --project <projectId>",
+			EXIT.USAGE,
+		);
+	}
+	const { values } = parse(rest, { project: { type: "string" } });
+	if (!values.project) {
+		throw new CliError(`Usage: index365 integrations ${sub} --project <projectId>`, EXIT.USAGE);
+	}
+	const settings = settingsFor(values, env);
+	const data = await apiRequest(
+		settings,
+		"GET",
+		`/api/v1/projects/${values.project}/integrations`,
+		{ fetchImpl: io.fetch },
+	);
+	if (values.json) printJson(io, data);
+	else {
+		for (const integration of data.integrations) {
+			out(
+				io,
+				`${integration.provider.padEnd(20)} ${integration.connected ? "connected" : integration.phase}  (${integration.access})`,
+			);
+		}
+		if (data.note) out(io, data.note);
+	}
+	return EXIT.OK;
+}
+
+async function cmdMcp(argv, io, env) {
+	const [sub, ...rest] = argv;
+	if (sub !== "config") throw new CliError("Usage: index365 mcp config [--json]", EXIT.USAGE);
+	const { values } = parse(rest);
+	const settings = settingsFor(values, env);
+	const serverConfig = {
+		command: "npx",
+		args: ["-y", "@index365/mcp"],
+		env: {
+			INDEX365_API_KEY: "<your i365_ key>",
+			INDEX365_API_URL: settings.apiUrl,
+		},
+	};
+	if (values.json) {
+		printJson(io, { mcpServers: { index365: serverConfig } });
+		return EXIT.OK;
+	}
+	out(io, "Claude Code:");
+	out(io, "  claude mcp add index365 -e INDEX365_API_KEY=<key> -- npx -y @index365/mcp");
+	out(io, "");
+	out(io, "Codex / Cursor / any MCP host (JSON):");
+	out(io, JSON.stringify({ mcpServers: { index365: serverConfig } }, null, 2));
+	out(io, "");
+	out(io, "The MCP server is read-only by default and calls the same /api/v1 as this CLI.");
+	return EXIT.OK;
+}
+
+/**
+ * Run the CLI. `io` carries every side effect (stdout/stderr/fetch/sleep/now)
+ * so tests can drive commands hermetically.
+ */
+export async function run(argv, io = defaultIo(), env = process.env) {
+	const [command, ...rest] = argv;
+	try {
+		if (!command || command === "--help" || command === "-h" || command === "help") {
+			out(io, HELP);
+			return EXIT.OK;
+		}
+		if (command === "--version" || command === "-V") {
+			out(io, CLI_VERSION);
+			return EXIT.OK;
+		}
+		switch (command) {
+			case "login":
+				return await cmdLogin(rest, io, env);
+			case "logout":
+				return await cmdLogout(rest, io, env);
+			case "doctor":
+				return await cmdDoctor(rest, io, env);
+			case "projects":
+				return await cmdProjects(rest, io, env);
+			case "runs":
+				return await cmdRuns(rest, io, env);
+			case "findings":
+				return await cmdFindings(rest, io, env);
+			case "reports":
+				return await cmdReports(rest, io, env);
+			case "marketing":
+				return await cmdMarketing(rest, io, env);
+			case "integrations":
+				return await cmdIntegrations(rest, io, env);
+			case "mcp":
+				return await cmdMcp(rest, io, env);
+			default:
+				throw new CliError(`Unknown command '${command}'. Run 'index365 --help'.`, EXIT.USAGE);
+		}
+	} catch (err) {
+		if (err instanceof CliError) {
+			io.stderr(err.message);
+			return err.exitCode;
+		}
+		io.stderr(`Unexpected error: ${err?.message ?? err}`);
+		return EXIT.ERROR;
+	}
+}
+
+export function defaultIo() {
+	return {
+		stdout: (line) => console.log(line),
+		stderr: (line) => console.error(line),
+		fetch: (...args) => fetch(...args),
+		sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+		now: () => Date.now(),
+	};
+}

package/src/client.mjs

@@ -0,0 +1,84 @@
+/**
+ * Thin HTTP client for /api/v1 — the CLI never talks to anything else.
+ * Stable exit-code mapping lives here so every command behaves identically:
+ *
+ *   0 success · 1 API/server error · 2 usage error · 3 auth (401/403)
+ *   4 not found · 5 quota/conflict/rate (402/409/429)
+ */
+
+export const EXIT = {
+	OK: 0,
+	ERROR: 1,
+	USAGE: 2,
+	AUTH: 3,
+	NOT_FOUND: 4,
+	QUOTA: 5,
+};
+
+export class CliError extends Error {
+	constructor(message, exitCode, detail = null) {
+		super(message);
+		this.exitCode = exitCode;
+		this.detail = detail;
+	}
+}
+
+export function exitCodeForStatus(status) {
+	if (status === 401 || status === 403) return EXIT.AUTH;
+	if (status === 404) return EXIT.NOT_FOUND;
+	if (status === 402 || status === 409 || status === 429) return EXIT.QUOTA;
+	return EXIT.ERROR;
+}
+
+/**
+ * Perform one API request. Returns the parsed JSON body on 2xx; throws
+ * CliError with a mapped exit code otherwise. `fetchImpl` is injectable for
+ * tests.
+ */
+export async function apiRequest(settings, method, apiPath, options = {}) {
+	const { query, body, idempotencyKey, fetchImpl = fetch } = options;
+	if (!settings.apiKey) {
+		throw new CliError(
+			"No API key configured. Run 'index365 login' or set INDEX365_API_KEY.",
+			EXIT.AUTH,
+		);
+	}
+	const url = new URL(`${settings.apiUrl}${apiPath}`);
+	for (const [key, value] of Object.entries(query ?? {})) {
+		if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, value);
+	}
+
+	const headers = {
+		authorization: `Bearer ${settings.apiKey}`,
+		"user-agent": "index365-cli/0.1.0",
+	};
+	if (body !== undefined) headers["content-type"] = "application/json";
+	if (idempotencyKey) headers["idempotency-key"] = idempotencyKey;
+
+	let response;
+	try {
+		response = await fetchImpl(url, {
+			method,
+			headers,
+			body: body !== undefined ? JSON.stringify(body) : undefined,
+		});
+	} catch (err) {
+		throw new CliError(`Could not reach ${settings.apiUrl}: ${err.message}`, EXIT.ERROR);
+	}
+
+	if (response.status === 204) return null;
+	const text = await response.text();
+	let parsed = null;
+	try {
+		parsed = text ? JSON.parse(text) : null;
+	} catch {
+		parsed = null;
+	}
+
+	if (!response.ok) {
+		const code = parsed?.error?.code ?? `http_${response.status}`;
+		const message = parsed?.error?.message ?? `Request failed with status ${response.status}.`;
+		throw new CliError(`${code}: ${message}`, exitCodeForStatus(response.status), parsed?.error);
+	}
+	return parsed;
+}

package/src/config.mjs

@@ -0,0 +1,65 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+/**
+ * CLI config: ~/.config/index365/config.json, written 0600.
+ *
+ * Resolution order (env beats file, so CI never needs a config file):
+ *   apiKey:  INDEX365_API_KEY  > config.apiKey
+ *   apiUrl:  INDEX365_API_URL  > config.apiUrl > https://index365.co
+ *
+ * The key is never logged by any command — `doctor` prints only the prefix
+ * returned by /api/v1/me.
+ */
+
+export const DEFAULT_API_URL = "https://index365.co";
+
+export function configDir(env = process.env) {
+	const xdg = env.XDG_CONFIG_HOME;
+	return path.join(xdg?.trim() ? xdg : path.join(homedir(), ".config"), "index365");
+}
+
+export function configPath(env = process.env) {
+	return path.join(configDir(env), "config.json");
+}
+
+export function readConfigFile(env = process.env) {
+	try {
+		const raw = readFileSync(configPath(env), "utf8");
+		const parsed = JSON.parse(raw);
+		return typeof parsed === "object" && parsed !== null ? parsed : {};
+	} catch {
+		return {};
+	}
+}
+
+export function writeConfigFile(config, env = process.env) {
+	const dir = configDir(env);
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+	const file = configPath(env);
+	writeFileSync(file, `${JSON.stringify(config, null, "\t")}\n`, { mode: 0o600 });
+	// mkdir/writeFile modes are ignored when the file pre-exists; enforce.
+	chmodSync(file, 0o600);
+	return file;
+}
+
+export function deleteConfigFile(env = process.env) {
+	try {
+		unlinkSync(configPath(env));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** Effective settings for a command run. */
+export function resolveSettings(env = process.env) {
+	const file = readConfigFile(env);
+	const apiKey = (env.INDEX365_API_KEY ?? "").trim() || (file.apiKey ?? null);
+	const apiUrl = ((env.INDEX365_API_URL ?? "").trim() || file.apiUrl || DEFAULT_API_URL).replace(
+		/\/+$/,
+		"",
+	);
+	return { apiKey, apiUrl, source: env.INDEX365_API_KEY ? "env" : file.apiKey ? "file" : "none" };
+}