@andreprado/agentkit 0.1.0-alpha.10

package/src/cli/deploy-readiness.ts

@@ -0,0 +1,348 @@
+import { findAgentCapsuleRoot, loadAgentCapsule } from "../runtime/config";
+import { readLocalDeployStateIfExists } from "../runtime/core/deploy-state";
+import { loadDeployReadinessContext, stableCloudProjectId, type DeployReadinessContext } from "../runtime/deploy-readiness";
+import { loadCapsuleEnv } from "../runtime/env";
+import { isAgentKitError } from "../runtime/errors";
+import {
+  cloudApiRequest,
+  formatCloudAuthSource,
+  readCloudAuth,
+  type CloudCapabilitiesResponse,
+  type CloudLimitsResponse,
+  type CloudMeResponse,
+  type CloudSecretsResponse,
+} from "./cloud-client";
+
+type DeployReadinessStatus = "pass" | "fail" | "warn" | "info";
+
+type DeployReadinessCheck = {
+  status: DeployReadinessStatus;
+  title: string;
+  message: string;
+  action?: string;
+};
+
+type DeployReadinessReport = {
+  ok: boolean;
+  apiUrl: string;
+  context: DeployReadinessContext;
+  checks: DeployReadinessCheck[];
+};
+
+export async function checkDeployReadiness(options: {
+  apiUrl: string;
+  requireLogin: boolean;
+}): Promise<DeployReadinessReport> {
+  const context = await loadDeployReadinessContext(process.cwd(), process.env);
+  const auth = await readCloudAuth();
+  const checks: DeployReadinessCheck[] = [];
+  let cloudAuthUsable = false;
+
+  if (context.runtime !== "edge") {
+    checks.push({
+      status: "fail",
+      title: "Target runtime",
+      message: 'Cloudflare deploy requires runtime: "edge" in agentkit.config.ts.',
+      action: "set runtime: \"edge\" before deploying to AgentKit Cloud",
+    });
+  } else {
+    checks.push({
+      status: "pass",
+      title: "Target runtime",
+      message: "Capsule is configured for edge deploy.",
+    });
+  }
+
+  if (!auth?.token) {
+    checks.push({
+      status: options.requireLogin ? "fail" : "warn",
+      title: "Login",
+      message: options.requireLogin
+        ? "No AgentKit Cloud token was found for hosted production deploy."
+        : "No AgentKit Cloud token was found; deploy will request anonymous mode.",
+      action: "agentkit login --token <token>",
+    });
+  } else {
+    try {
+      const me = (await cloudApiRequest(options.apiUrl, "/v1/me", { method: "GET" })) as CloudMeResponse;
+      const email = me.account?.email;
+      checks.push({
+        status: "pass",
+        title: "Login",
+        message: email ? `Authenticated as ${email}.` : "AgentKit Cloud token is accepted.",
+      });
+      cloudAuthUsable = true;
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Login",
+        message: `AgentKit Cloud rejected the token from ${formatCloudAuthSource(auth)}. ${formatReadinessError(error)}`,
+        action: "agentkit login --token <token>",
+      });
+    }
+  }
+
+  if (cloudAuthUsable) {
+    try {
+      const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/capabilities", {
+        method: "GET",
+      })) as CloudCapabilitiesResponse;
+      const capabilities = payload.capabilities ?? [];
+      const hasCloudflareAlpha = capabilities.some(
+        (capability) => capability.name === "cloudflare_deploy_alpha" && capability.status === "active",
+      );
+
+      checks.push({
+        status: hasCloudflareAlpha ? "pass" : "fail",
+        title: "Deploy entitlement",
+        message: hasCloudflareAlpha
+          ? "cloudflare_deploy_alpha is active."
+          : "This account is missing the cloudflare_deploy_alpha entitlement.",
+        ...(hasCloudflareAlpha ? {} : { action: "log in with an invited AgentKit Cloud alpha token" }),
+      });
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Deploy entitlement",
+        message: `Could not verify AgentKit Cloud capabilities. ${formatReadinessError(error)}`,
+      });
+    }
+
+    try {
+      const payload = (await cloudApiRequest(options.apiUrl, "/v1/me/limits", {
+        method: "GET",
+      })) as CloudLimitsResponse;
+      const account = payload.online_agents?.account;
+      const global = payload.online_agents?.global;
+      const accountLimit = normalizeOptionalNumber(account?.limit);
+      const accountUsed = normalizeOptionalNumber(account?.used);
+      const globalLimit = normalizeOptionalNumber(global?.limit);
+      const globalUsed = normalizeOptionalNumber(global?.used);
+
+      if (accountLimit !== undefined && accountUsed !== undefined && accountUsed >= accountLimit) {
+        checks.push({
+          status: "fail",
+          title: "Online agent capacity",
+          message: `This account is already using ${accountUsed}/${accountLimit} online AgentKit deploys.`,
+          action: "agentkit deploy pause",
+        });
+      } else if (globalLimit !== undefined && globalUsed !== undefined && globalUsed >= globalLimit) {
+        checks.push({
+          status: "fail",
+          title: "Online agent capacity",
+          message: `AgentKit Cloud is already using ${globalUsed}/${globalLimit} global online deploy slots.`,
+          action: "agentkit deploy status",
+        });
+      } else if (accountLimit !== undefined && accountUsed !== undefined) {
+        checks.push({
+          status: "pass",
+          title: "Online agent capacity",
+          message: `Account has capacity: ${accountUsed}/${accountLimit} online deploys are in use.`,
+        });
+      } else if (globalLimit !== undefined && globalUsed !== undefined) {
+        checks.push({
+          status: "pass",
+          title: "Online agent capacity",
+          message: `Global capacity is available: ${globalUsed}/${globalLimit} online deploys are in use.`,
+        });
+      } else {
+        checks.push({
+          status: "info",
+          title: "Online agent capacity",
+          message: "No online deploy limit is configured for this account.",
+        });
+      }
+    } catch (error) {
+      checks.push({
+        status: "warn",
+        title: "Online agent capacity",
+        message: `Could not verify online deploy capacity. ${formatReadinessError(error)}`,
+      });
+    }
+  }
+
+  if (context.agentKitManagedSecrets.length > 0) {
+    checks.push({
+      status: "info",
+      title: "AgentKit-managed secrets",
+      message: `${context.agentKitManagedSecrets.join(", ")} ${
+        context.agentKitManagedSecrets.length === 1 ? "is" : "are"
+      } provisioned by AgentKit Cloud during deploy.`,
+    });
+  }
+
+  if (context.accessMode === "private") {
+    checks.push({
+      status: "info",
+      title: "Private access",
+      message: "AGENTKIT_PRIVATE_TOKEN is required at runtime; AgentKit Cloud generates it and saves it in .agentkit/deploy.json.",
+    });
+  }
+
+  if (context.knowledge.enabled) {
+    if (context.knowledge.databaseDriver !== "turso") {
+      checks.push({
+        status: "fail",
+        title: "Knowledge storage",
+        message: "Hosted Knowledge requires a Turso database so indexed chunks are available to the Cloudflare runtime.",
+        action: 'set storage.database.driver: "turso" in agentkit.config.ts before deploying Knowledge',
+      });
+    } else {
+      checks.push({
+        status: "pass",
+        title: "Knowledge storage",
+        message: `Knowledge is configured with ${context.knowledge.sourceCount} source${
+          context.knowledge.sourceCount === 1 ? "" : "s"
+        } and Turso storage.`,
+      });
+    }
+  }
+
+  if (context.userManagedSecrets.length === 0) {
+    checks.push({
+      status: "pass",
+      title: "Hosted secrets",
+      message: "No user-managed hosted secrets are required by this capsule.",
+    });
+  } else if (!cloudAuthUsable) {
+    checks.push({
+      status: options.requireLogin ? "fail" : "warn",
+      title: "Hosted secrets",
+      message: `Could not check hosted secrets without a valid AgentKit Cloud login. Required: ${context.userManagedSecrets.join(", ")}.`,
+      action: "agentkit secret list",
+    });
+  } else {
+    try {
+      const payload = (await cloudApiRequest(
+        options.apiUrl,
+        `/v1/projects/${encodeURIComponent(context.projectId)}/secrets`,
+        { method: "GET" },
+      )) as CloudSecretsResponse;
+      const hostedSecretNames = new Set((payload.secrets ?? []).map((secret) => secret.name).filter(isString));
+      const missing = context.userManagedSecrets.filter((name) => !hostedSecretNames.has(name));
+
+      if (missing.length === 0) {
+        checks.push({
+          status: "pass",
+          title: "Hosted secrets",
+          message: "All user-managed hosted secrets are set.",
+        });
+      } else {
+        for (const secret of missing) {
+          const localSource = context.localSecrets[secret];
+          checks.push({
+            status: "fail",
+            title: `Hosted secret ${secret}`,
+            message: localSource
+              ? `${secret} is present locally but has not been set in AgentKit Cloud.`
+              : `${secret} is required but missing from AgentKit Cloud.`,
+            action: secretSetCommand(secret, localSource),
+          });
+        }
+      }
+    } catch (error) {
+      checks.push({
+        status: "fail",
+        title: "Hosted secrets",
+        message: `Could not list hosted secrets for project ${context.projectId}. ${formatReadinessError(error)}`,
+        action: "agentkit secret list",
+      });
+    }
+  }
+
+  return {
+    ok: checks.every((check) => check.status !== "fail"),
+    apiUrl: options.apiUrl,
+    context,
+    checks,
+  };
+}
+
+export function printDeployReadinessReport(report: DeployReadinessReport): void {
+  console.log("AgentKit deploy readiness");
+  console.log(`Project: ${report.context.projectName}`);
+  console.log(`Project ID: ${report.context.projectId}`);
+  console.log(`Target: ${report.context.target}`);
+  console.log(`API: ${report.apiUrl}`);
+  console.log("");
+
+  for (const check of report.checks) {
+    console.log(`[${check.status}] ${check.title}: ${check.message}`);
+
+    if (check.action) {
+      console.log(`  Run: ${check.action}`);
+    }
+  }
+}
+
+export async function syncHostedSecretsFromLocal(options: { apiUrl: string; projectId: string }): Promise<void> {
+  const context = await loadDeployReadinessContext(process.cwd(), process.env);
+  const localEnv = await loadCapsuleEnv(context.root, {});
+  let synced = 0;
+  let skipped = 0;
+
+  for (const secret of context.userManagedSecrets) {
+    const value = localEnv[secret];
+
+    if (value === undefined) {
+      skipped += 1;
+      console.log(`${secret}\tskipped_missing_local`);
+      continue;
+    }
+
+    await cloudApiRequest(options.apiUrl, `/v1/projects/${encodeURIComponent(options.projectId)}/secrets/${encodeURIComponent(secret)}`, {
+      method: "PUT",
+      body: JSON.stringify({ value }),
+    });
+    synced += 1;
+    console.log(`${secret}\tsynced`);
+  }
+
+  if (context.userManagedSecrets.length === 0) {
+    console.log("No user-managed hosted secrets are declared by this capsule.");
+    return;
+  }
+
+  console.log("");
+  console.log(`${synced} synced, ${skipped} skipped`);
+}
+
+export function formatReadinessError(error: unknown): string {
+  if (isAgentKitError(error)) {
+    return `${error.code}: ${error.message}`;
+  }
+
+  return error instanceof Error ? error.message : String(error);
+}
+
+export async function resolveProjectIdForSecretCommand(cwd: string): Promise<string> {
+  const state = await readLocalDeployStateIfExists(cwd);
+
+  if (state?.project_id) {
+    return state.project_id;
+  }
+
+  const root = await findAgentCapsuleRoot(cwd);
+  const capsule = await loadAgentCapsule(root);
+  return stableCloudProjectId(capsule.config.name);
+}
+
+function secretSetCommand(secret: string, source: DeployReadinessContext["localSecrets"][string] | undefined): string {
+  if (source?.dotenv) {
+    return `agentkit secret set ${secret} --from-local-env`;
+  }
+
+  if (source?.environment) {
+    return `agentkit secret set ${secret} --from-env`;
+  }
+
+  return `agentkit secret set ${secret} --stdin`;
+}
+
+function normalizeOptionalNumber(value: number | null | undefined): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}

package/src/cli/flags.ts

@@ -0,0 +1,162 @@
+import { listTargetsWithCapability } from "../runtime/core/targets";
+import { loadCapsuleEnv } from "../runtime/env";
+import { AgentKitError } from "../runtime/errors";
+import { defaultAgentKitCloudApiUrl } from "./constants";
+
+export function parsePort(value: string | boolean | undefined, usage = "agentkit dev --port <number>"): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== "string") {
+    throw new Error(`Missing port. Usage: ${usage}`);
+  }
+
+  const port = Number(value);
+
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`Invalid port. Usage: ${usage}`);
+  }
+
+  return port;
+}
+
+export function parseTargetFlag(value: string | boolean | undefined, capability: "build" | "deploy"): string {
+  if (value === undefined) {
+    return "cloudflare";
+  }
+
+  if (typeof value !== "string") {
+    throw new Error(
+      `Missing target. Usage: agentkit ${capability} --target ${listTargetsWithCapability(capability).join("|")}`,
+    );
+  }
+
+  return value;
+}
+
+export function parseCloudApiUrl(value: string | boolean | undefined): string {
+  if (value === undefined) {
+    return process.env.AGENTKIT_CLOUD_API_URL ?? defaultAgentKitCloudApiUrl;
+  }
+
+  if (typeof value !== "string") {
+    throw new Error("Missing API URL. Usage: agentkit deploy --api <url>");
+  }
+
+  return value;
+}
+
+export function parseRequiredStringFlag(value: string | boolean | undefined, name: string, usage: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Missing ${name}. Usage: ${usage}`);
+  }
+
+  return value.trim();
+}
+
+export function parseOptionalStringFlag(value: string | boolean | undefined, name: string, usage: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Missing ${name}. Usage: ${usage}`);
+  }
+
+  return value.trim();
+}
+
+export async function resolveSecretInputValue(options: {
+  name: string | undefined;
+  valueParts: string[];
+  stdinFlag: string | boolean | undefined;
+  fromEnvFlag: string | boolean | undefined;
+  fromLocalEnvFlag: string | boolean | undefined;
+  localEnvRoot?: string;
+  usage: string;
+  inlineSensitiveHelp?: string;
+}): Promise<string> {
+  const { name, valueParts, stdinFlag, fromEnvFlag, fromLocalEnvFlag, localEnvRoot, usage, inlineSensitiveHelp } = options;
+
+  if (!name) {
+    throw new Error(`Missing name. Usage: ${usage}`);
+  }
+
+  const hasInlineValue = valueParts.length > 0;
+  const hasStdin = stdinFlag !== undefined;
+  const hasFromEnv = fromEnvFlag !== undefined;
+  const hasFromLocalEnv = fromLocalEnvFlag !== undefined;
+  const inputModes = [hasInlineValue, hasStdin, hasFromEnv, hasFromLocalEnv].filter(Boolean).length;
+
+  if (inputModes !== 1) {
+    throw new Error(`Provide exactly one value source. Usage: ${usage}`);
+  }
+
+  let value: string;
+
+  if (hasInlineValue) {
+    value = valueParts.join(" ");
+    if (looksLikeSecretName(name)) {
+      console.error(
+        `Warning: ${name} looks sensitive. ${inlineSensitiveHelp ?? "Prefer --stdin or --from-env so the value does not enter shell history."}`,
+      );
+    }
+  } else if (hasStdin) {
+    if (stdinFlag !== true) {
+      throw new Error(`--stdin does not take a value. Usage: ${usage}`);
+    }
+
+    value = stripOneTrailingNewline(await readStdinText());
+  } else if (hasFromEnv) {
+    const envName = fromEnvFlag === true ? name : parseRequiredStringFlag(fromEnvFlag, "env name", usage);
+    const envValue = process.env[envName];
+
+    if (envValue === undefined) {
+      throw new AgentKitError("secret_not_found", `Environment variable ${envName} is not set.`);
+    }
+
+    value = envValue;
+  } else {
+    if (fromLocalEnvFlag !== true) {
+      throw new Error(`--from-local-env does not take a value. Usage: ${usage}`);
+    }
+
+    if (!localEnvRoot) {
+      throw new Error(`--from-local-env is not available for this command. Usage: ${usage}`);
+    }
+
+    const localEnv = await loadCapsuleEnv(localEnvRoot, {});
+    const localValue = localEnv[name];
+
+    if (localValue === undefined) {
+      throw new AgentKitError("secret_not_found", `Local .env does not contain ${name}.`);
+    }
+
+    value = localValue;
+  }
+
+  if (value.length === 0) {
+    throw new Error(`Secret value cannot be empty. Usage: ${usage}`);
+  }
+
+  return value;
+}
+
+function looksLikeSecretName(name: string): boolean {
+  return /(?:SECRET|TOKEN|KEY|PASSWORD|CREDENTIAL|PRIVATE)/i.test(name);
+}
+
+async function readStdinText(): Promise<string> {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function stripOneTrailingNewline(value: string): string {
+  return value.replace(/\r?\n$/, "");
+}

package/src/cli/help.ts

@@ -0,0 +1,184 @@
+export function renderHelp(): string {
+  return `AgentKit
+
+Create, run, inspect, and deploy Agent Capsules.
+
+Quick start:
+  agentkit new support-agent --template support
+  cd support-agent
+  npm run dev
+  npm run chat -- --message "hello"
+
+Usage:
+  agentkit <command> [options]
+
+Start:
+  agentkit new <name> [--template blank|support|dentista] [--no-install]
+  agentkit dev
+  agentkit open
+  agentkit chat-ui --deploy
+  agentkit chat --message <text> [--conversation-id <id>]
+  agentkit inspect
+
+Build:
+  agentkit knowledge add <path>
+  agentkit knowledge search <query>
+  agentkit spec init --brief <text>
+  agentkit sync run
+  agentkit tool <name> [--input <path-or-json>]
+  agentkit db migrate
+  agentkit eval run
+  agentkit eval from-conversation <id>
+  agentkit conversations list
+
+Deploy:
+  agentkit login --token <token>
+  agentkit deploy doctor
+  agentkit secret set <NAME> --stdin
+  agentkit secret sync --from-local
+  agentkit deploy --smoke "hello"
+  agentkit deploy status
+
+More:
+  agentkit channels ...
+  agentkit access token ...
+  agentkit env ...
+  agentkit docs full
+  agentkit help commands
+`;
+}
+
+export function renderCommandReference(): string {
+  return `AgentKit Command Reference
+
+Usage:
+  agentkit new <name> [--template blank|support|dentista] [--no-install]
+  agentkit dev [--port <number>]
+  agentkit open
+  agentkit chat-ui --deploy [--port <number>] [--token-file <path>]
+  agentkit chat --message <text> [--conversation-id <id>]
+  agentkit tool <name> [--input <path-or-json>]
+  agentkit knowledge add <path-or-url>
+  agentkit knowledge sync
+  agentkit knowledge inspect
+  agentkit knowledge search <query> [--top-k <number>]
+  agentkit spec init --brief <text> [--out <path>] [--force]
+  agentkit spec check [--file <path>]
+  agentkit sync init [--force]
+  agentkit sync run [--file <path>]
+  agentkit db migrate
+  agentkit db reset --yes
+  agentkit db shell
+  agentkit db seed [--file <path>]
+  agentkit eval run
+  agentkit eval from-conversation <conversation-id> [--out <path>] [--force]
+  agentkit conversations list
+  agentkit conversations show <conversation-id>
+  agentkit conversations trace <conversation-id>
+  agentkit channels list
+  agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
+  agentkit channels connect <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
+  agentkit channels setup <name> [--apply] [--api <url>]
+  agentkit channels status <name> [--api <url>]
+  agentkit channels doctor <name> [--api <url>]
+  agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
+  agentkit channels deliveries list <name> [--api <url>]
+  agentkit channels deliveries show <delivery-id> [--api <url>]
+  agentkit inspect
+  agentkit build [--target cloudflare|container]
+  agentkit login --token <token> [--api <url>]
+  agentkit logout
+  agentkit deploy [--target cloudflare|vps] [--host <host>] [--api <url>] [--dry-run] [--anonymous] [--local-wrangler] [--smoke <message>]
+  agentkit deploy doctor [--api <url>] [--anonymous]
+  agentkit deploy smoke [--message <text>] [--api <url>]
+  agentkit deploy status [--api <url>]
+  agentkit deploy pause [--api <url>]
+  agentkit deploy resume [--api <url>]
+  agentkit secret set <NAME> <VALUE> [--api <url>]
+  agentkit secret set <NAME> --stdin [--api <url>]
+  agentkit secret set <NAME> --from-env [ENV_NAME] [--api <url>]
+  agentkit secret set <NAME> --from-local-env [--api <url>]
+  agentkit secret sync --from-local [--api <url>]
+  agentkit secret list [--api <url>]
+  agentkit secret unset <NAME> [--api <url>]
+  agentkit access token create <name> [--api <url>] [--out <path>]
+  agentkit access token list [--api <url>]
+  agentkit access token revoke <token-id> [--api <url>]
+  agentkit env set <NAME> <VALUE>
+  agentkit env set <NAME> --stdin
+  agentkit env set <NAME> --from-env [ENV_NAME]
+  agentkit env list
+  agentkit env unset <NAME>
+  agentkit docs path
+  agentkit docs llms
+  agentkit docs full
+  agentkit handoff codex [goal]
+  agentkit help commands
+  agentkit --help
+
+Commands:
+  new             Create a new Agent Capsule
+  dev             Run the Agent Capsule locally
+  open            Open the local Agent Capsule UI if it is already running
+  chat-ui         Run a local chat UI, optionally pointed at a hosted deploy
+  chat            Send one message to the local Agent Capsule
+  tool            Run one registered tool directly
+  knowledge       Add, sync, inspect, and search local Knowledge sources
+  spec            Create or check the agent implementation contract from the owner brief
+  sync            Run or scaffold catalog/data synchronization
+  db              Manage the local SQLite database
+  eval            Run local eval files or create one from a conversation
+  conversations   List, inspect, and trace stored local conversations
+  channels        Manage hosted channel resources
+  inspect         Print machine-readable Agent Capsule state
+  build           Build a hosted deploy artifact
+  login           Store an AgentKit Cloud alpha token outside the capsule
+  logout          Remove the stored AgentKit Cloud alpha token
+  deploy          Build and send a hosted artifact to AgentKit Cloud
+  secret          Manage hosted AgentKit Cloud secrets without readback
+  access          Manage hosted deploy access tokens
+  env             Manage local .env values without opening code
+  docs            Print AgentKit docs locations
+  handoff         Print a ready-to-paste prompt for another coding agent
+  help            Print focused help or the full command reference
+
+Examples:
+  agentkit new support-agent --template support
+  cd support-agent
+  agentkit dev
+  agentkit open
+  agentkit tool lookup_order --input '{"orderId":"A100"}'
+  agentkit eval run
+
+  agentkit new clara-dentista --template dentista
+`;
+}
+
+export function renderCommandHelp(command: string): string {
+  const usage: Record<string, string> = {
+    new: "agentkit new <name> [--template blank|support|dentista] [--no-install]",
+    dev: "agentkit dev [--port <number>]",
+    open: "agentkit open",
+    "chat-ui": "agentkit chat-ui --deploy [--port <number>] [--token-file <path>]",
+    chat: 'agentkit chat --message "hello" [--conversation-id <id>]',
+    tool: "agentkit tool <name> [--input <path-or-json>]",
+    knowledge: "agentkit knowledge add <path-or-url> | sync | inspect | search <query> [--top-k <number>]",
+    spec: 'agentkit spec init --brief "owner request" | agentkit spec check',
+    sync: "agentkit sync init [--force] | agentkit sync run [--file <path>]",
+    eval: "agentkit eval run | agentkit eval from-conversation <conversation-id> [--out <path>] [--force]",
+    conversations:
+      "agentkit conversations list | agentkit conversations show <conversation-id> | agentkit conversations trace <conversation-id>",
+    deploy:
+      'agentkit deploy [--smoke "hello"] | agentkit deploy smoke [--message "hello"] | agentkit deploy doctor | status | pause | resume',
+    secret:
+      "agentkit secret set <NAME> --stdin | --from-env [ENV_NAME] | --from-local-env | agentkit secret sync --from-local | list | unset <NAME>",
+    access: "agentkit access token create <name> [--out <path>] | list | revoke <token-id>",
+    env: "agentkit env set <NAME> --stdin | --from-env [ENV_NAME] | list | unset <NAME>",
+    docs: "agentkit docs path | llms | full",
+    handoff: "agentkit handoff codex [goal] | agentkit handoff claude [goal]",
+  };
+
+  return `Usage: ${usage[command] ?? "agentkit <command> [options]"}
+
+Run \`agentkit help commands\` for the full command reference.`;
+}