agentkey-ai 1.0.0 → 1.2.0

package/README.md

@@ -16,11 +16,24 @@ JavaScript / TypeScript (Node 18+, zero dependencies, ESM):
 npm install agentkey-ai
 ```
 
+### Next steps after install
+
+pip wheels run no code on install, so pip cannot print guidance for you. npm is different, and this section states its behavior precisely rather than assuming it: dependency install scripts still run by default on npm 11 and earlier; npm 11.16.0 and later print a warning whenever an install executes them; and npm 12 no longer executes preinstall, install, or postinstall scripts from dependencies "unless they are explicitly allowed in your project" (GitHub changelog, June 2026), with `npm approve-scripts` as the approval path. A postinstall banner in this package is therefore technically possible on npm 11 and earlier, but we do not ship one: it would be suppressed or gated on current npm, and a security tool should not run code at install time. The immediate next step:
+
+```bash
+agentkey init     # paste your API key (masked) and validate it against production
+agentkey doctor   # verify the full setup: SDK, credentials, API, key validity
+```
+
+After `npm install agentkey-ai`, invoke the same commands with npx: `npx agentkey init`, `npx agentkey doctor`.
+
+The CLI never prints your key. `agentkey init` saves a pasted key to a local config file (`~/.agentkey/config`, or `%APPDATA%\agentkey\config` on Windows; permissions 0600, the only file the key is ever written to). The `AGENTKEY_API_KEY` environment variable overrides it, and `agentkey logout` deletes it. See "Developer CLI" below.
+
 ## Get an API key
 
-1. Sign up at the AgentKey dashboard: https://agentkey.base44.app
+1. Sign up at the AgentKey dashboard: https://agentkey.us
 2. Open the Connect wizard (or Agents, then create an agent).
-3. Generate an API key. It is shown once; store it as an environment variable and do not hard-code it.
+3. Generate an API key. It is shown once. Run `agentkey init` to save it to the local config file, or export it as `AGENTKEY_API_KEY`. Never hard-code it.
 
 ## First authorization (Python)
 
@@ -131,9 +144,23 @@ If authorize denies, `guard` returns the denial and does not run the function.
 
 A parent agent can delegate a scoped subset of its permissions to a child agent. Scopes are `resource:action` strings, must be a subset of the parent's own permissions, and chains are depth-limited. See `delegate()` in the source docstrings.
 
+## Developer CLI
+
+Both packages ship the same commands (`init`, `doctor`, `logout`). They validate your setup against the production API and never change SDK authorization behavior. Every CLI network call has an explicit 10 second timeout, so a wrong URL, an offline machine, or firewalled egress fails closed with a next step instead of hanging.
+
+The API key is resolved, highest first, from: an explicit constructor argument (SDK), the `AGENTKEY_API_KEY` environment variable, then the config file (`~/.agentkey/config`, or `%APPDATA%\agentkey\config` on Windows). The environment variable always wins, so CI and anyone already exporting it are unaffected.
+
+`agentkey init` validates the configured key against the production API. With no key configured it prompts with masked input, validates the pasted key, and saves it to the config file (created with permissions 0600 inside a 0700 directory) so later commands and SDK clients resolve it automatically. The key is never printed or logged, and that file is the only place it is ever written.
+
+`agentkey doctor` runs a fast end-to-end check: SDK installed, credentials configured (reporting whether the key came from the environment or the config file), API reachable, credentials valid, authorization endpoint reachable. When the API is unreachable the network-dependent checks are skipped and reported as such. Each failed check states the practical next step. No stack traces.
+
+`agentkey logout` deletes the saved config file. The environment variable, if set, is untouched (the CLI cannot unset your shell).
+
+A successful `init` or `doctor` means the developer is authenticated and configured. It never means the agent's actions are automatically allowed; authorization decisions remain fail-closed exactly as before.
+
 ## Production API
 
-Base URL: `https://agentkey.base44.app` (the SDK default). Override it with `base_url` (Python) or `baseUrl` (JavaScript) if you self-host.
+Base URL: `https://agentkey.us` (the SDK default). Override it with `base_url` (Python) or `baseUrl` (JavaScript) if you self-host.
 
 All endpoints are POST with a Bearer API key, under `/api/functions/`:
 
@@ -147,7 +174,7 @@ All endpoints are POST with a Bearer API key, under `/api/functions/`:
 Raw HTTP:
 
 ```bash
-curl -X POST https://agentkey.base44.app/api/functions/authorize \
+curl -X POST https://agentkey.us/api/functions/authorize \
   -H "Authorization: Bearer agent_live_xxxxx" \
   -H "Content-Type: application/json" \
   -d '{"action":"send_email","resource":"gmail","arguments":{"to":"x@company.com"}}'
@@ -155,7 +182,12 @@ curl -X POST https://agentkey.base44.app/api/functions/authorize \
 
 ## Dashboard
 
-Sessions, evidence events, approvals, findings and permission settings: https://agentkey.base44.app
+Sessions, evidence events, approvals, findings and permission settings: https://agentkey.us
+
+## Troubleshooting
+
+- "Request blocked by edge WAF (Cloudflare error 1010). This is not an authentication failure." The production API sits behind a WAF that blocks some client signatures. The SDK sends an identifying User-Agent on every request (`agentkey-sdk-js/<version>` in the JavaScript SDK, `agentkey-python-sdk` in the Python SDK). If you see this error, something between your code and the API (a proxy, a modified SDK, or a non-SDK integration) is stripping or replacing that header. Restore it, then retry. This error never means a bad key.
+- Both SDKs detect the Cloudflare 1010 HTML page and raise the explicit error above; it never surfaces as a generic parse error, an unreachable API, or an authentication failure.
 
 ## Security limitations (current, accurate)
 

package/agentkey.d.ts

@@ -47,12 +47,26 @@ export interface WrapOptions {
 }
 
 export interface ClientOptions {
-  apiKey: string;
+  /** Optional: the key resolves, highest first, from this argument, then the
+   * AGENTKEY_API_KEY environment variable, then the config file written by
+   * `agentkey init` (~/.agentkey/config). */
+  apiKey?: string;
   baseUrl?: string;
 }
 
+/** The config file location: ~/.agentkey/config (or %APPDATA%\agentkey\config
+ *  on Windows), or null when no home directory can be determined. */
+export function configFilePath(): string | null;
+export function readConfigKey(): Promise<string | null>;
+export function saveConfigKey(apiKey: string): Promise<string>;
+export function deleteConfigKey(): Promise<boolean>;
+
 export class AgentKeyClient {
-  constructor(options: ClientOptions);
+  constructor(options?: ClientOptions);
+
+  /** "constructor argument", "environment variable", "config file", or null
+   *  (the config file is resolved lazily on first use). */
+  keySource: string | null;
 
   checkPermission(args: {
     action: string;
@@ -82,6 +96,8 @@ export class AgentKeyClient {
 
   endSession(args: { sessionId: string; status?: string }): Promise<Record<string, unknown>>;
 
+  verifySession(args: { sessionId: string }): Promise<Record<string, unknown>>;
+
   recordAction(args: {
     sessionId?: string;
     authorizationId?: string;

package/agentkey.js

@@ -20,11 +20,92 @@ const TIMEOUT_MS = 5000;
 
 // Production API. Override with baseUrl only if you self-host.
 export const DEFAULT_BASE_URL = "https://agentkey.base44.app";
-const USER_AGENT = "agentkey-js-sdk/1.0.0";
+export const VERSION = "1.2.0";
+const USER_AGENT = `agentkey-sdk-js/${VERSION}`;
 
 // Process-wide flag so the first-run info block prints once per process.
 let _wrapFirstRunPrinted = false;
 
+// --- Credential config file (Node only; browsers have no filesystem) --------
+//
+// Resolution order, highest first: an explicit constructor argument, the
+// AGENTKEY_API_KEY environment variable, then the config file written by
+// `agentkey init` (~/.agentkey/config, or %APPDATA%\agentkey\config on
+// Windows). The environment variable always wins, so CI and anyone already
+// exporting it are unaffected. Zero dependencies, like gh/stripe/aws: no
+// keyring, no native modules. The file is created 0600 inside a 0700
+// directory, and it is the only place the key is ever written.
+
+export function configFilePath() {
+  if (typeof process === "undefined" || !process.env) return null;
+  if (process.platform === "win32") {
+    return process.env.APPDATA ? `${process.env.APPDATA}\\agentkey\\config` : null;
+  }
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  return home ? `${home}/.agentkey/config` : null;
+}
+
+let _fsModulePromise = null;
+async function _fs() {
+  if (typeof process === "undefined" || !process.versions || !process.versions.node) return null;
+  if (!_fsModulePromise) {
+    _fsModulePromise = import("node:fs").catch(() => null);
+  }
+  return _fsModulePromise;
+}
+
+export async function readConfigKey() {
+  const fs = await _fs();
+  const p = configFilePath();
+  if (!fs || !p) return null;
+  try {
+    const text = fs.readFileSync(p, "utf8");
+    for (const line of text.split("\n")) {
+      if (line.startsWith("api_key=")) {
+        const value = line.slice("api_key=".length).trim();
+        if (value) return value;
+      }
+    }
+  } catch (e) {}
+  return null;
+}
+
+export async function saveConfigKey(apiKey) {
+  const fs = await _fs();
+  const p = configFilePath();
+  if (!fs || !p) {
+    throw new Error("AgentKey: no home directory found; use the AGENTKEY_API_KEY environment variable instead");
+  }
+  const dir = p.replace(/[\\/][^\\/]+$/, "");
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(p, `api_key=${apiKey}\n`, { mode: 0o600 });
+  fs.chmodSync(dir, 0o700);
+  fs.chmodSync(p, 0o600);
+  return p;
+}
+
+export async function deleteConfigKey() {
+  const fs = await _fs();
+  const p = configFilePath();
+  if (!fs || !p) return false;
+  try { fs.unlinkSync(p); return true; } catch (e) { return false; }
+}
+
+// Cloudflare blocks some client signatures with error 1010, returning an HTML
+// body and no useful signal. Detect that exact case so it surfaces as what it
+// is: an edge block, never a rejected key or a broken server. The User-Agent
+// above is set on every request, but a future WAF rule change could still
+// block a client; this keeps the failure explainable.
+function _wafBlockedError(body) {
+  if (typeof body !== "string") return null;
+  if (body.includes("error code: 1010") || (body.includes("Attention Required") && body.includes("Cloudflare"))) {
+    const err = new Error("Request blocked by edge WAF (Cloudflare error 1010). This is not an authentication failure.");
+    err.agentkeyWaf = true;
+    return err;
+  }
+  return null;
+}
+
 export class AgentKeyDenied extends Error {
   constructor(reason, result) {
     super(reason || "denied by AgentKey policy");
@@ -34,12 +115,33 @@ export class AgentKeyDenied extends Error {
 }
 
 export class AgentKeyClient {
-  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL }) {
-    if (!apiKey) throw new Error("AgentKey: apiKey is required");
-    this.apiKey = apiKey;
+  // The key resolves, highest first, from an explicit apiKey argument, then
+  // the AGENTKEY_API_KEY environment variable, then (lazily, on first use)
+  // the config file written by `agentkey init`. In a browser neither the
+  // environment nor the file exists, so an explicit apiKey is required.
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL } = {}) {
+    const explicit = String(apiKey || "").trim();
+    const fromEnv = (typeof process !== "undefined" && process.env
+      ? String(process.env.AGENTKEY_API_KEY || "") : "").trim();
+    this.apiKey = explicit || fromEnv || null;
+    this.keySource = explicit ? "constructor argument" : (fromEnv ? "environment variable" : null);
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
   }
 
+  async _ensureKey() {
+    if (!this.apiKey) {
+      const fromFile = await readConfigKey();
+      if (fromFile) {
+        this.apiKey = fromFile;
+        this.keySource = "config file";
+      }
+    }
+    if (!this.apiKey) {
+      throw new Error("AgentKey: no API key configured. Pass apiKey to the constructor, set AGENTKEY_API_KEY, or run: agentkey init");
+    }
+    return this.apiKey;
+  }
+
   async _post(path, body, extraHeaders = {}) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
@@ -51,9 +153,14 @@ export class AgentKeyClient {
         signal: controller.signal,
       });
       const data = await res.json().catch(() => null);
+      if (!data) {
+        const waf = _wafBlockedError(await res.text().catch(() => ""));
+        if (waf) throw waf;
+      }
       if (!data || typeof data.allowed !== "boolean") return { ...FAIL_CLOSED };
       return data;
     } catch (e) {
+      if (e && e.agentkeyWaf) throw e;
       return { ...FAIL_CLOSED };
     } finally {
       clearTimeout(timeout);
@@ -71,8 +178,13 @@ export class AgentKeyClient {
         signal: controller.signal,
       });
       const data = await res.json().catch(() => null);
+      if (!data) {
+        const waf = _wafBlockedError(await res.text().catch(() => ""));
+        if (waf) throw waf;
+      }
       return data || { error: "agentkey_unreachable" };
     } catch (e) {
+      if (e && e.agentkeyWaf) throw e;
       return { error: "agentkey_unreachable" };
     } finally {
       clearTimeout(timeout);
@@ -85,6 +197,7 @@ export class AgentKeyClient {
    *  hash chain. Fails closed (allowed: false) on any error or timeout. */
   async checkPermission({ action, resource, tool, metadata = {}, arguments: args, sessionId, parentEventId, parentAgentId, source, scanId, delegationId }) {
     if (!action || !resource) throw new Error("AgentKey: action and resource are required");
+    await this._ensureKey();
     return this._post(
       "/api/functions/authorize",
       { action, resource, tool, metadata, arguments: args, session_id: sessionId, parent_event_id: parentEventId, parent_agent_id: parentAgentId, source, input_scan_id: scanId, delegation_id: delegationId },
@@ -105,6 +218,7 @@ export class AgentKeyClient {
     if (!childAgentId || !Array.isArray(scopes) || scopes.length === 0) {
       throw new Error("AgentKey: childAgentId and a non-empty scopes array are required");
     }
+    await this._ensureKey();
     return this._postJson(
       "/api/functions/delegate",
       {
@@ -120,19 +234,25 @@ export class AgentKeyClient {
 
   /** Validate the key is active. Returns { valid, message, agent_id, agent_name }. */
   async validate() {
+    await this._ensureKey();
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
     try {
       const res = await fetch(`${this.baseUrl}/api/functions/validate_api_key`, {
-        headers: { Authorization: `Bearer ${this.apiKey}` },
+        headers: { Authorization: `Bearer ${this.apiKey}`, "User-Agent": USER_AGENT },
         signal: controller.signal,
       });
       const data = await res.json().catch(() => null);
+      if (!data) {
+        const waf = _wafBlockedError(await res.text().catch(() => ""));
+        if (waf) throw waf;
+      }
       if (!data || typeof data.valid !== "boolean") {
         return { valid: false, reason: "agentkey_unreachable", fail_closed: true };
       }
       return data;
     } catch (e) {
+      if (e && e.agentkeyWaf) throw e;
       return { valid: false, reason: "agentkey_unreachable", fail_closed: true };
     } finally {
       clearTimeout(timeout);
@@ -146,15 +266,31 @@ export class AgentKeyClient {
    *  decision in the session unless overridden per call. Returns { session_id,
    *  agent_id, started_at, preceding_scan_id }. */
   async startSession({ metadata, scanId } = {}) {
+    await this._ensureKey();
     return this._postJson("/api/functions/start_session", { metadata, scan_id: scanId }, { Authorization: `Bearer ${this.apiKey}` });
   }
 
   /** End an evidence session. Returns { session_id, status, event_count }.
    *  Pass status: "failed" to mark a failed session. */
   async endSession({ sessionId, status } = {}) {
+    await this._ensureKey();
     return this._postJson("/api/functions/end_session", { session_id: sessionId, status }, { Authorization: `Bearer ${this.apiKey}` });
   }
 
+  /** Verify a session's evidence chain server-side: the hash chain is
+   *  recomputed from the stored events, the HMAC-SHA256 attestation is
+   *  checked, and the Ed25519 signature is checked when one is present
+   *  (an optional asymmetric layer — sessions closed without it verify as
+   *  before). The response's `signature` object distinguishes the two:
+   *  signature_status is the HMAC result, ed25519_status the asymmetric
+   *  one, each with its own key_id. Authentication is your agent API key.
+   *  Fails closed: an unreachable API returns
+   *  { error: "agentkey_unreachable" } and is never treated as verified. */
+  async verifySession({ sessionId } = {}) {
+    await this._ensureKey();
+    return this._postJson("/api/functions/verify_session", { session_id: sessionId }, { Authorization: `Bearer ${this.apiKey}` });
+  }
+
   /** Record what an agent ACTUALLY did, as an execution event on the same hash
    *  chain as the decision that permitted it. Pass the `event_id` returned by
    *  checkPermission as authorizationId to link the execution to its decision.
@@ -163,6 +299,7 @@ export class AgentKeyClient {
    *  reported. `metadata` is sanitized to primitives before storage (used by
    *  wrap() to mark would_block in observe mode). */
   async recordAction({ sessionId, authorizationId, attemptId, tool, action, resource, arguments: args, resultStatus, resultHash, durationMs, errorMessage, metadata, scanId }) {
+    await this._ensureKey();
     return this._postJson("/api/functions/record_action", {
       session_id: sessionId, authorization_id: authorizationId, attempt_id: attemptId, tool, action, resource, arguments: args,
       result_status: resultStatus, result_hash: resultHash, duration_ms: durationMs, error_message: errorMessage,
@@ -313,6 +450,7 @@ function _wrapTarget(client, target, { sessionId, mode = "observe", scanId } = {
       try {
         auth = await client.checkPermission({ action: "invoke", resource: name, arguments: argumentsObj, sessionId: sid });
       } catch (e) {
+        if (e && e.agentkeyWaf) throw e; // an edge block must surface, not mask as a denial
         auth = { allowed: false, reason: "agentkey_unreachable", fail_closed: true };
       }
       const allowed = !!auth && auth.allowed === true;

package/cli.mjs

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+// agentkey-ai CLI: agentkey init / agentkey doctor / agentkey logout
+//
+// Zero dependencies (Node 18+). The API key is resolved, highest first, from
+// the AGENTKEY_API_KEY environment variable, then the config file written by
+// init (~/.agentkey/config, or %APPDATA%\agentkey\config on Windows; created
+// 0600 inside a 0700 directory, the only file the key is ever written to).
+// The environment variable always wins, so CI and anyone already exporting it
+// are unaffected. The CLI never prints the key. Every network call has an
+// explicit 10 second timeout, so a wrong URL, an offline machine, or firewalled
+// egress fails closed with a next step instead of hanging. A successful init
+// means the developer is authenticated and configured — it never means the
+// agent's actions are automatically allowed. Authorization stays fail-closed
+// in the SDK.
+
+import {
+  DEFAULT_BASE_URL,
+  VERSION,
+  configFilePath,
+  readConfigKey,
+  saveConfigKey,
+  deleteConfigKey,
+} from "./agentkey.js";
+
+const TIMEOUT_MS = 10000;
+const RULE = "─".repeat(41);
+const DASHBOARD_URL = "https://agentkey.us";
+const QUICKSTART_URL = "https://agentkey.us/quickstart";
+const UA = `agentkey-cli-js/${VERSION}`;
+
+function step(ok, label, detail, nextStep) {
+  console.log(` ${ok ? "✓" : "✗"} ${label}${detail ? ` - ${detail}` : ""}`);
+  if (!ok && nextStep) console.log(`   → ${nextStep}`);
+  return ok;
+}
+
+// Any HTTP response (including 401/400) proves the endpoint is reachable.
+// Only a network-level failure (DNS, timeout, refused) means unreachable.
+async function apiReachable(baseUrl, path, method = "POST") {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(baseUrl + path, {
+      method,
+      headers: { "Content-Type": "application/json", "User-Agent": UA },
+      body: method === "POST" ? "{}" : undefined,
+      signal: controller.signal,
+    });
+    return [true, res.status];
+  } catch {
+    return [false, null];
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// GET validate_api_key and read the body, so a rejected key is distinguishable
+// from an unreachable API (the SDK's validate() fails closed on any error and
+// cannot tell the two apart).
+async function validateRaw(baseUrl, key) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const res = await fetch(`${baseUrl}/api/functions/validate_api_key`, {
+      headers: { Authorization: `Bearer ${key}`, "User-Agent": UA },
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    try {
+      const data = JSON.parse(text);
+      if (data && typeof data.valid === "boolean") return data;
+    } catch {}
+    if (text.includes("error code: 1010") || (text.includes("Attention Required") && text.includes("Cloudflare"))) {
+      return { valid: false, error: "request blocked by the edge WAF (Cloudflare error 1010) - not an authentication failure" };
+    }
+    return { valid: false, error: `API returned HTTP ${res.status}` };
+  } catch (e) {
+    if (process.env.AGENTKEY_CLI_DEBUG) console.error("debug: validate_api_key failed:", String((e && e.cause) || e));
+    return { valid: false, error: "could not reach the API (fail-closed)" };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// Masked prompt: raw-mode stdin, one █ echoed per keystroke, never the key
+// itself. Returns null when there is no interactive terminal or nothing was
+// pasted, so init falls back to the configuration instructions.
+function promptKey() {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) { resolve(null); return; }
+    process.stdout.write("API key: ");
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const chunks = [];
+    const finish = (value) => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", onData);
+      process.stdout.write("\n");
+      resolve(value);
+    };
+    const onData = (buf) => {
+      for (const byte of buf) {
+        if (byte === 13 || byte === 10) { finish(Buffer.concat(chunks).toString("utf8").trim() || null); return; }
+        if (byte === 3) { finish(null); process.exit(130); return; }
+        if (byte === 127 || byte === 8) { if (chunks.length) { chunks.pop(); process.stdout.write("\h \b"); } continue; }
+        chunks.push(Buffer.from([byte]));
+        process.stdout.write("█");
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+// Resolve the key: environment first, then the config file. The CLI takes no
+// key argument on purpose (command-line arguments leak into shell history and
+// process listings); the masked prompt is the only interactive input.
+async function resolveKey() {
+  const env = (process.env.AGENTKEY_API_KEY || "").trim();
+  if (env) return { key: env, source: "environment" };
+  const fromFile = await readConfigKey();
+  if (fromFile) return { key: fromFile, source: "config" };
+  return { key: null, source: null };
+}
+
+async function cmdInit() {
+  const baseUrl = (process.env.AGENTKEY_BASE_URL || "").trim() || DEFAULT_BASE_URL;
+  console.log("AgentKey");
+  console.log(RULE);
+  console.log("Let's get your agent protected.");
+  console.log();
+  console.log("Checking existing configuration…");
+  console.log();
+  const resolved = await resolveKey();
+  let key = resolved.key;
+  let pasted = false;
+  if (key) {
+    step(true, "API key found", resolved.source === "environment"
+      ? "environment: AGENTKEY_API_KEY"
+      : `config file: ${configFilePath()}`);
+  } else {
+    console.log("AgentKey needs an API key to connect to your account.");
+    console.log();
+    console.log(`Get your key from: ${DASHBOARD_URL}`);
+    console.log("  (Connect wizard, pick an agent, Create API key. It is shown once.)");
+    console.log();
+    const entered = await promptKey();
+    if (!entered) {
+      console.log("AgentKey needs an API key and this session has no interactive");
+      console.log("terminal to ask for one. Run `agentkey init` in a terminal to");
+      console.log("enter and save it, or set the environment variable:");
+      console.log();
+      console.log('  export AGENTKEY_API_KEY="agent_live_…"');
+      console.log();
+      console.log("Then run: agentkey init");
+      return 1;
+    }
+    key = entered;
+    pasted = true;
+    step(true, "API key received");
+  }
+  const v = await validateRaw(baseUrl, key);
+  if (v.valid === true) {
+    const who = v.agent_name || v.agent_id || "your agent";
+    step(true, "API key validated", `agent: ${who}`);
+    step(true, `Connected to ${baseUrl}`);
+    let savedAt = null;
+    if (pasted) {
+      try {
+        savedAt = await saveConfigKey(key);
+        step(true, "API key saved", `${savedAt} (permissions 0600)`);
+      } catch (e) {
+        if (process.env.AGENTKEY_CLI_DEBUG) console.error("debug: could not save config:", String(e));
+        step(false, "API key saved", "could not write the config file");
+        console.log();
+        console.log("FAILED: the key validated but could not be saved. Use the");
+        console.log("environment variable instead:");
+        console.log('  export AGENTKEY_API_KEY="agent_live_…"');
+        return 1;
+      }
+    }
+    console.log();
+    console.log("AgentKey is ready.");
+    console.log();
+    if (savedAt) {
+      console.log("The key is saved at the config file above. The AGENTKEY_API_KEY");
+      console.log("environment variable overrides it; unset yours to use the saved");
+      console.log("key. Remove it any time: agentkey logout");
+    }
+    console.log("Next:");
+    console.log("  1. agentkey doctor");
+    console.log(`  2. Make your first authorization. Quickstart: ${QUICKSTART_URL}`);
+    return 0;
+  }
+  const detail = String(v.error || v.message || v.reason || "rejected by the API");
+  step(false, "API key validated", detail);
+  console.log();
+  if (detail.includes("WAF") || detail.includes("1010")) {
+    console.log("FAILED: the request was blocked by the edge WAF. This is not an");
+    console.log("authentication failure; a proxy or modified client is likely");
+    console.log("stripping the SDK's User-Agent header. Restore it, then run:");
+    console.log("  agentkey init");
+  } else if (detail.includes("could not reach")) {
+    console.log("FAILED: the API did not answer within the timeout. Authorization");
+    console.log("checks fail closed (allowed=false) until it does. Check the URL");
+    console.log("(AGENTKEY_BASE_URL overrides it) and retry: agentkey init");
+  } else {
+    console.log("FAILED: your AgentKey API key could not be authenticated.");
+    console.log("Run: agentkey init");
+    console.log(`Create a fresh key at ${DASHBOARD_URL}/connect if you need one.`);
+  }
+  return 1;
+}
+
+async function cmdDoctor() {
+  const baseUrl = (process.env.AGENTKEY_BASE_URL || "").trim() || DEFAULT_BASE_URL;
+  console.log("AgentKey doctor");
+  console.log(RULE);
+  console.log();
+  let ok = true;
+  ok = step(true, "SDK installed", `agentkey-ai ${VERSION}`) && ok;
+  const { key, source } = await resolveKey();
+  const [reach, status] = await apiReachable(baseUrl, "/api/functions/validate_api_key", "GET");
+  ok = step(reach, "API reachable", `${baseUrl}${reach ? ` (HTTP ${status})` : " - unreachable"}`,
+    "check the URL (AGENTKEY_BASE_URL overrides it) and your network") && ok;
+  if (!key) {
+    ok = step(false, "Credentials configured", "no API key configured", "run: agentkey init") && ok;
+    if (reach) {
+      ok = step(false, "Credentials valid", "skipped, no key", "run: agentkey init") && ok;
+      const [areach, astatus] = await apiReachable(baseUrl, "/api/functions/authorize");
+      ok = step(areach, "Authorization endpoint reachable", areach ? `HTTP ${astatus}` : "unreachable",
+        "authorization checks fail closed until this is reachable") && ok;
+    } else {
+      // Same host, same fate: no point making more doomed requests.
+      ok = step(false, "Credentials valid", "skipped, the API is unreachable",
+        "check the URL (AGENTKEY_BASE_URL overrides it) and your network") && ok;
+      ok = step(false, "Authorization endpoint reachable", "skipped, same host as the API",
+        "authorization checks fail closed until the API is reachable") && ok;
+    }
+  } else {
+    const where = source === "environment"
+      ? "environment: AGENTKEY_API_KEY"
+      : `config file: ${configFilePath()}`;
+    ok = step(true, "Credentials configured", where) && ok;
+    if (!reach) {
+      ok = step(false, "Credentials valid", "skipped, the API is unreachable",
+        "check the URL (AGENTKEY_BASE_URL overrides it) and your network") && ok;
+      ok = step(false, "Authorization endpoint reachable", "skipped, same host as the API",
+        "authorization checks fail closed until the API is reachable") && ok;
+    } else {
+      const v = await validateRaw(baseUrl, key);
+      const valid = v.valid === true;
+      const detail = valid ? "" : String(v.error || v.message || v.reason || "rejected by the API");
+      ok = step(valid, "Credentials valid", detail,
+        `run: agentkey init, or create a fresh key at ${DASHBOARD_URL}/connect`) && ok;
+      const [areach, astatus] = await apiReachable(baseUrl, "/api/functions/authorize");
+      ok = step(areach, "Authorization endpoint reachable", areach ? `HTTP ${astatus}` : "unreachable",
+        "authorization checks fail closed until this is reachable") && ok;
+    }
+  }
+  console.log();
+  if (ok) {
+    console.log("Ready.");
+    console.log();
+    console.log("Next: follow the Quickstart to perform your first authorization.");
+    console.log(`  ${QUICKSTART_URL}`);
+    return 0;
+  }
+  console.log("FAILED. See the ✗ checks above. Start with: agentkey init");
+  return 1;
+}
+
+async function cmdLogout() {
+  const removed = await deleteConfigKey();
+  if (removed) {
+    console.log(`Removed the saved API key from ${configFilePath()}`);
+  } else {
+    console.log("No saved API key found (nothing to remove).");
+  }
+  if ((process.env.AGENTKEY_API_KEY || "").trim()) {
+    console.log("AGENTKEY_API_KEY is also set in your environment; unset it too:");
+    console.log("  unset AGENTKEY_API_KEY");
+  }
+  return 0;
+}
+
+function printUsage() {
+  console.log("Usage: agentkey <command>");
+  console.log();
+  console.log("Commands:");
+  console.log("  init     set up your API key: prompt (masked), validate against the production API, save to the config file");
+  console.log("  doctor   check the full setup: SDK, credentials, API reachability, key validity");
+  console.log("  logout   delete the API key saved by init (the environment variable is unaffected)");
+}
+
+function onboarding() {
+  console.log("AgentKey - authorization and evidence for AI agents");
+  console.log(RULE);
+  console.log();
+  console.log("New here? The fastest path to your first authorization:");
+  console.log();
+  console.log("  1. agentkey init    - paste your API key, validate against production");
+  console.log("  2. agentkey doctor  - verify the full setup");
+  console.log("  3. Quickstart - your first authorization in about 5 minutes:");
+  console.log(`     ${QUICKSTART_URL}`);
+  console.log();
+  console.log(`Get an API key at ${DASHBOARD_URL} (Connect wizard).`);
+  console.log("agentkey logout deletes the key saved by init.");
+  return 0;
+}
+
+async function run() {
+  const cmd = process.argv[2];
+  if (cmd === "init") return cmdInit();
+  if (cmd === "doctor") return cmdDoctor();
+  if (cmd === "logout") return cmdLogout();
+  if (cmd === "--help" || cmd === "-h" || cmd === "help") { printUsage(); return 0; }
+  if (cmd === undefined) return onboarding();
+  printUsage();
+  return 1;
+}
+
+run().then((code) => { process.exitCode = code; });

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "agentkey-ai",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Authorization and evidence SDK for AI agents: check permissions before every action, record what agents actually did.",
   "type": "module",
+  "bin": {
+    "agentkey": "cli.mjs"
+  },
   "main": "./agentkey.js",
   "types": "./agentkey.d.ts",
   "exports": {
@@ -15,6 +18,7 @@
   "files": [
     "agentkey.js",
     "agentkey.d.ts",
+    "cli.mjs",
     "README.md",
     "LICENSE"
   ],
@@ -33,4 +37,4 @@
   ],
   "license": "MIT",
   "homepage": "https://agentkey.base44.app"
-}
+}