@kryd/cli 0.17.0 → 0.18.0

package/README.md

@@ -26,6 +26,8 @@ kryd logs <project> --worker  # tail the workflow worker's stdout/stderr
 
 Once you've run `kryd init` in a directory, the commands below work **arg-less** there — the folder is linked via `.kryd/project.json` (git-ignored, no secret).
 
+`kryd init` and `kryd workflow init` also write a short **Kryd block into `AGENTS.md`** — the file Codex, Cursor, Copilot and Claude Code read — so a coding agent knows the rules before it breaks one: listen on `$PORT`, which env vars Kryd injects, keep the AI gateway token on the server, make workflow tasks safe to run twice, and the CLI's commands (generated from the CLI itself). It sits between `<!-- kryd:begin … -->` and `<!-- kryd:end -->`; a later run replaces only what is between those markers and leaves the rest of your file alone. After updating the CLI, `kryd init --agents` refreshes the block in a linked project (no login needed) — also the way to add it to a project linked before the block existed. If the folder has a `CLAUDE.md`, one `@AGENTS.md` line is added to it so Claude Code reads the block too.
+
 ## Commands
 
 | Command | What it does |
@@ -33,6 +35,7 @@ Once you've run `kryd init` in a directory, the commands below work **arg-less**
 | `kryd login` / `logout` / `whoami` | Authenticate the CLI (browser flow); the token is stored in `~/.kryd`. `whoami` shows the account commands run in, your role there, and your other accounts. |
 | `kryd account list \| use <slug>` | You can belong to several accounts (your own, a customer's as a member). `list` shows them with your role in each, `*` marking the current one; `use` makes every following command run in that account. |
 | `kryd init` | Link the current repo to a Kryd project + register the deploy webhook + add a `kryd` git remote. Not logged in and at a terminal? It asks, then runs the same browser login as `kryd login`; without a terminal it refuses (a deploy token, `KRYD_TOKEN`, cannot create a project). |
+| `kryd init --agents` | Only write or refresh the Kryd block in `AGENTS.md` of the linked project (walks up to the link), plus the `@AGENTS.md` line in a `CLAUDE.md`. No login, no API call. In a linked folder a plain `kryd init` refuses and names this. |
 | `kryd push [branch]` | Push to the `kryd` remote and follow the deploy it triggers (defaults to the current branch). Shows which step the deploy is on, how long it has taken and a progress bar; `--logs` streams the full build log instead. |
 | `kryd deploy [project]` | Re-deploy the production-branch HEAD already on the forge — no new commit. |
 | `kryd logs [target]` | Follow a deploy's build/deploy log **in full** — this is where the build output lives (`--runtime` tails the live container instead; `--worker` tails the project's workflow worker, also when it has a web app). |
@@ -53,6 +56,22 @@ kryd support new --type bug --subject "Deploy hangs on build" --message "Every d
 kryd support show T-1042 --json
 ```
 
+**`--json` on the read commands.** `kryd project list`, `whoami`, `db status`, `storage status`, `ai status`, `workflow status`, `domain status [host]` and `env list` take `--json` too, with the same contract: exactly one JSON document on stdout; an error is text on stderr with exit 1 and an empty stdout. "Nothing attached" is an answer, not an error (exit 0). The shapes:
+
+| Command | `--json` prints |
+|---|---|
+| `kryd project list` | `{ items }`: each project as the API lists it (`id`, `name`, `subdomain`, `framework`, `repoUrl`, `productionBranch`, `previewsPublic`, `status`, `createdAt`, `updatedAt`, …) plus `linked` — `true` for the project this folder is linked to |
+| `kryd whoami` | the `GET /me` answer as is: you, the account commands run in, your role and your `memberships` |
+| `kryd db status` | `{ production, preview }`, each `{ attached, status, failureReason }`. When production is not attached the preview is not read, and is reported as not attached |
+| `kryd storage status` | `{ attached, status, failureReason }` |
+| `kryd ai status` | `{ enabled, url }` |
+| `kryd workflow status` | `{ enabled, tokenExpiresAt, tokenExpiresInDays }` — both `null` without an expiry; the days are negative once the token has expired |
+| `kryd domain status` | `{ projectHost, domains }`; each domain is `{ id, host, app?, redirectTo?, status, detail, checkedAt, createdAt, records }`, with `status` the raw value (`pending`, `verified`, `active`, `failed`), not the text-mode wording |
+| `kryd domain status <host>` | that one domain, the same fields, its DNS `records` included |
+| `kryd env list` | `{ items }`, each `{ key, source, scope, updatedAt, environments? }` — names and origin, never values |
+
+`kryd token list --json` and `kryd account list --json` print a bare array.
+
 In CI, no `kryd login` and no config file: set a deploy token as the secret `KRYD_TOKEN` and every command uses it (it wins over a stored login).
 
 ```sh

package/dist/index.js

@@ -14989,14 +14989,14 @@ function isTerminalResourceStatus(status) {
 
 // src/index.ts
 import {
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   mkdirSync as mkdirSync2,
-  readFileSync as readFileSync3,
-  realpathSync,
+  readFileSync as readFileSync4,
+  realpathSync as realpathSync2,
   rmSync as rmSync2,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "node:fs";
-import { basename as basename2, dirname as dirname2, isAbsolute, join as join3, relative, resolve as resolve2 } from "node:path";
+import { basename as basename2, dirname as dirname2, isAbsolute, join as join4, relative, resolve as resolve2 } from "node:path";
 import { pathToFileURL } from "node:url";
 
 // src/config.ts
@@ -16796,9 +16796,125 @@ function parseCredentialInput(raw) {
   return out;
 }
 
+// src/agents-md.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+var AGENTS_FILE = "AGENTS.md";
+var CLAUDE_FILE = "CLAUDE.md";
+var BEGIN_MARKER = "<!-- kryd:begin \u2014 written by the kryd CLI; edits inside are replaced on the next run -->";
+var END_MARKER = "<!-- kryd:end -->";
+var BEGIN_LINE = /^<!-- kryd:begin/gm;
+var END_LINE = /^<!-- kryd:end/gm;
+var AGENTS_PROSE = `## Deploying on Kryd
+
+This project deploys to Kryd, a European cloud platform. Use what it already provides instead of adding another service:
+
+- **Git is the deploy.** The repository lives on Kryd's own git server in the EU (remote \`kryd\`). \`git push kryd <branch>\` or \`kryd push\` builds and deploys; every other branch gets its own preview URL. Don't add CI deploy pipelines, hosting Dockerfiles or another platform's config.
+- **Database:** managed Postgres \u2014 \`kryd db add\`, then use \`DATABASE_URL\`. Preview deploys can get a database of their own: \`kryd db add --preview\`. Don't add a database container or SQLite for production data.
+- **File storage:** S3-compatible object storage \u2014 \`kryd storage add\`.
+- **AI:** an EU-hosted, OpenAI-compatible gateway with several models \u2014 \`kryd ai add\`. Don't add provider API keys.
+- **Long-running or background work** \u2014 jobs, retries, schedules \u2014 belongs in a workflow (\`kryd workflow init\`), not in a request handler, a timer loop or a separate queue.
+- **Incoming webhooks** (Stripe, GitHub, \u2026) go to a workflow webhook, created in the Kryd dashboard under Workflows, so every delivery is stored and retried instead of handled inside a web request.
+- **Your own domain:** \`kryd domain add <host>\` prints the DNS records to create; the HTTPS certificate is automatic.
+- Everything runs in the EU; keep data and model calls there.
+
+### Rules
+
+- **Listen on \`$PORT\`.** The platform sets it; never hardcode a port. An app that listens anywhere else fails the health check, and its deploy never goes live.
+- **The project link** is \`.kryd/project.json\` (per developer, gitignored). Commands find it by walking up to the git root, so they need no project id inside this repository.
+- **Injected env vars \u2014 never set these yourself:** \`DATABASE_URL\`; \`AI_GATEWAY_URL\` (already ends in \`/v1\`) and \`AI_GATEWAY_TOKEN\`; \`HATCHET_CLIENT_TOKEN\`; and for storage \`AWS_ACCESS_KEY_ID\`, \`AWS_SECRET_ACCESS_KEY\`, \`AWS_REGION\`, \`AWS_ENDPOINT_URL_S3\`, \`BUCKET_NAME\`. Kryd injects each one once its resource is added (\`kryd db add\`, \`kryd ai add\`, \`kryd workflow add\`, \`kryd storage add\`).
+- **Call the AI gateway from server code only.** \`AI_GATEWAY_TOKEN\` must never reach a browser.
+- **Workflows:** \`kryd workflow init --language typescript|python|go\` scaffolds a worker, declared in \`kryd.json\` (\`"web": false\` = the project is a worker only). Make every task safe to run twice: a worker stops within seconds on SIGTERM, and the engine re-runs the task.
+- **Login:** without a terminal there is no login \u2014 ask the user to run \`kryd init\` or \`kryd login\`. A deploy token (\`KRYD_TOKEN\`) can deploy but cannot create a project.
+- **Destructive commands** ask for confirmation; without a terminal they need \`--yes\`.
+- **Read commands take \`--json\`** for one JSON document on stdout \u2014 \`kryd project list --json\`, \`kryd whoami --json\`, \`kryd db status --json\`, \`kryd storage status --json\`, \`kryd ai status --json\`, \`kryd workflow status --json\`, \`kryd domain status --json\`, \`kryd env list --json\`. "Nothing attached" is an answer (exit 0); an error is text on stderr with exit 1 and an empty stdout.
+`;
+var AGENTS_FOOTER = "Run `kryd <command> --help` for details. After updating the CLI, refresh this block with `kryd init --agents`.\n";
+function isHidden(cmd) {
+  return cmd._hidden === true;
+}
+function leafCommands(program2) {
+  const out = [];
+  const walk = (cmd, prefix) => {
+    if (isHidden(cmd)) return;
+    const path = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
+    if (cmd.commands.length > 0) {
+      for (const child of cmd.commands) walk(child, path);
+      return;
+    }
+    const args = cmd.registeredArguments.map((a) => {
+      const inner = `${a.name()}${a.variadic ? "..." : ""}`;
+      return a.required ? `<${inner}>` : `[${inner}]`;
+    });
+    out.push({ path, usage: [path, ...args].join(" "), description: cmd.description() });
+  };
+  for (const child of program2.commands) walk(child, "");
+  return out;
+}
+function renderAgentsBlock(program2) {
+  const commands = leafCommands(program2).map((c) => `- \`kryd ${c.usage}\` \u2014 ${c.description}
+`).join("");
+  return `${BEGIN_MARKER}
+` + AGENTS_PROSE + "\n### Commands\n\n" + commands + "\n" + AGENTS_FOOTER + `${END_MARKER}
+`;
+}
+function lineStartsMatching(text, re) {
+  return [...text.matchAll(re)].map((m) => m.index);
+}
+function writeAgentsBlock(dir, block) {
+  const path = join2(dir, AGENTS_FILE);
+  if (!existsSync2(path)) {
+    writeFileSync2(path, block);
+    return "created";
+  }
+  const text = readFileSync2(path, "utf8");
+  const begins = lineStartsMatching(text, BEGIN_LINE);
+  const ends = lineStartsMatching(text, END_LINE);
+  let next;
+  if (begins.length === 0 && ends.length === 0) {
+    let base = text;
+    if (base.length > 0) {
+      if (!base.endsWith("\n")) base += "\n";
+      if (!base.endsWith("\n\n")) base += "\n";
+    }
+    next = base + block;
+  } else {
+    const [begin] = begins;
+    const [end] = ends;
+    if (begins.length !== 1 || ends.length !== 1 || begin === void 0 || end === void 0 || end < begin || // An end marker that is not exactly ours (say `<!-- kryd:end` without its `-->`) would make
+    // the slice run on into the customer's text.
+    !text.startsWith(END_MARKER, end)) {
+      throw new Error(
+        `${AGENTS_FILE} has broken kryd markers (a begin without an end, or one of them twice) \u2014 left it untouched; fix or remove the markers and run this again`
+      );
+    }
+    const endOfMarker = end + END_MARKER.length;
+    next = text.slice(0, begin) + block.replace(/\n$/, "") + text.slice(endOfMarker);
+  }
+  if (next === text) return "unchanged";
+  writeFileSync2(path, next);
+  return "updated";
+}
+function ensureClaudeImport(dir) {
+  const path = join2(dir, CLAUDE_FILE);
+  if (!existsSync2(path)) return false;
+  const agents = join2(dir, AGENTS_FILE);
+  if (existsSync2(agents) && realpathSync(path) === realpathSync(agents)) return false;
+  const text = readFileSync2(path, "utf8");
+  if (/^[ \t]*@(\.\/)?AGENTS\.md[ \t]*\r?$/m.test(text)) return false;
+  let base = text;
+  if (base.length > 0) {
+    if (!base.endsWith("\n")) base += "\n";
+    if (!base.endsWith("\n\n")) base += "\n";
+  }
+  writeFileSync2(path, `${base}@AGENTS.md
+`);
+  return true;
+}
+
 // src/framework.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { basename, join as join2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { basename, join as join3 } from "node:path";
 var FRAMEWORKS = [
   "react-router",
   "nextjs",
@@ -16853,7 +16969,7 @@ function startScriptLooksLikePlainNode(start) {
 }
 function readPackageJson(cwd) {
   try {
-    return JSON.parse(readFileSync2(join2(cwd, "package.json"), "utf8"));
+    return JSON.parse(readFileSync3(join3(cwd, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -16861,7 +16977,7 @@ function readPackageJson(cwd) {
 function readDeclaration(cwd) {
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync2(join2(cwd, DECLARATION_FILE), "utf8"));
+    parsed = JSON.parse(readFileSync3(join3(cwd, DECLARATION_FILE), "utf8"));
   } catch {
     return null;
   }
@@ -16881,7 +16997,7 @@ function frameworkFrom(pkg, cwd) {
   const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
   const has = (name) => name in deps;
   if (has("next")) return "nextjs";
-  if (has("@react-router/dev") || existsSync2(join2(cwd, "react-router.config.ts")) || existsSync2(join2(cwd, "react-router.config.js"))) {
+  if (has("@react-router/dev") || existsSync3(join3(cwd, "react-router.config.ts")) || existsSync3(join3(cwd, "react-router.config.js"))) {
     return "react-router";
   }
   if (VITE_META_FRAMEWORKS.some(has)) return null;
@@ -18032,6 +18148,10 @@ function reportNotLinked(example) {
   );
   process.exitCode = 1;
 }
+function printJson2(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
 async function runLogin(opts) {
   const apiUrl = resolveApiUrl(opts.apiUrl);
   const pastedToken = opts.token ?? process.env.KRYD_TOKEN;
@@ -18055,6 +18175,10 @@ async function runWhoami(opts = {}) {
   const token = resolveToken() ?? "";
   try {
     const me = await whoami(apiUrl, token);
+    if (opts.json) {
+      printJson2(me);
+      return;
+    }
     const current = me.memberships?.find((m) => m.accountId === me.accountId);
     const label = current?.slug ?? me.accountSlug ?? me.accountId ?? "?";
     process.stdout.write(`${me.email} (account ${label}, role ${current?.role ?? me.role ?? "?"})
@@ -18082,48 +18206,110 @@ function runLogout() {
   process.stdout.write("Logged out.\n");
   warnIfEnvTokenOverrides();
 }
-async function runInit(opts) {
-  let apiUrl = resolveApiUrl(opts.apiUrl);
-  const cwd = opts.cwd ?? process.cwd();
-  let token = resolveToken();
-  if (!token) {
-    const refusal = "Not logged in \u2014 run `kryd login` first.\n";
-    const io = opts.io ?? defaultPromptIO();
-    if (opts.offerLogin === false) {
-      process.stderr.write(refusal);
-      process.exitCode = 1;
-      return;
-    }
-    if (!isInteractive(io)) {
-      process.stderr.write(
-        refusal + // KRYD-385 iteration 1: no KRYD_TOKEN advice — `POST /repos` refuses a deploy token (KRYD-578).
-        "No terminal to log in from: ask the user to run `kryd init` (or `kryd login`) in their own terminal. A deploy token (KRYD_TOKEN) cannot create a project.\n"
-      );
-      process.exitCode = 1;
-      return;
+function installAgentsBlock(dir) {
+  let note = "";
+  const changed = [];
+  let result;
+  try {
+    result = writeAgentsBlock(dir, renderAgentsBlock(program));
+    if (result !== "unchanged") changed.push(AGENTS_FILE);
+    if (result === "created") {
+      note += "Wrote AGENTS.md \u2014 what coding agents need to know to deploy this project on Kryd.\n";
+    } else if (result === "updated") {
+      note += "Updated the Kryd block in AGENTS.md.\n";
     }
-    io.output.write("You are not logged in to Kryd; `kryd init` can log you in through your browser first.\n");
-    if (!await promptConfirm("Log in now in your browser?", io)) {
-      process.stderr.write(refusal);
-      process.exitCode = 1;
-      return;
+  } catch (err) {
+    process.stderr.write(
+      `warning: could not write the Kryd block to AGENTS.md (${err instanceof Error ? err.message : String(err)}) \u2014 everything else worked; coding agents just will not see it.
+`
+    );
+    return { note, block: "failed", changed };
+  }
+  try {
+    if (ensureClaudeImport(dir)) {
+      changed.push(CLAUDE_FILE);
+      note += "Added `@AGENTS.md` to CLAUDE.md, so Claude Code reads that block too.\n";
     }
-    try {
-      await browserLoginAndSave(apiUrl);
-    } catch (err) {
-      process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+  } catch (err) {
+    process.stderr.write(
+      `warning: could not add \`@AGENTS.md\` to CLAUDE.md (${err instanceof Error ? err.message : String(err)}) \u2014 add that line yourself so Claude Code reads AGENTS.md.
+`
+    );
+  }
+  return { note, block: result, changed };
+}
+async function settleLogin(opts) {
+  let token = resolveToken();
+  if (token) return { token, apiUrl: opts.apiUrl };
+  const refusal = "Not logged in \u2014 run `kryd login` first.\n";
+  const io = opts.io ?? defaultPromptIO();
+  if (!opts.offerLogin) {
+    process.stderr.write(refusal);
+    process.exitCode = 1;
+    return null;
+  }
+  if (!isInteractive(io)) {
+    process.stderr.write(
+      refusal + // KRYD-385 iteration 1: no KRYD_TOKEN advice — `POST /repos` refuses a deploy token (KRYD-578).
+      `No terminal to log in from: ask the user to run \`${opts.command}\` (or \`kryd login\`) in their own terminal. A deploy token (KRYD_TOKEN) cannot create a project.
+`
+    );
+    process.exitCode = 1;
+    return null;
+  }
+  io.output.write(`You are not logged in to Kryd; \`${opts.command}\` can log you in through your browser first.
 `);
-      process.exitCode = 1;
-      return;
-    }
-    token = resolveToken();
-    if (!token) {
-      process.stderr.write(refusal);
-      process.exitCode = 1;
-      return;
-    }
-    if (!opts.apiUrl) apiUrl = resolveApiUrl();
+  if (!await promptConfirm("Log in now in your browser?", io)) {
+    process.stderr.write(refusal);
+    process.exitCode = 1;
+    return null;
   }
+  try {
+    await browserLoginAndSave(opts.apiUrl);
+  } catch (err) {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}
+`);
+    process.exitCode = 1;
+    return null;
+  }
+  token = resolveToken();
+  if (!token) {
+    process.stderr.write(refusal);
+    process.exitCode = 1;
+    return null;
+  }
+  return { token, apiUrl: opts.apiUrlFlag ? opts.apiUrl : resolveApiUrl() };
+}
+function runInitAgents(cwd) {
+  const dir = findProjectLinkDir(cwd);
+  if (!dir) {
+    process.stderr.write(
+      "This folder is not linked to a Kryd project (no .kryd/project.json up to the git root), so there is no block to refresh.\nRun `kryd init` to link it \u2014 that writes the Kryd block into AGENTS.md as well.\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const { note, block } = installAgentsBlock(dir);
+  process.stdout.write(block === "unchanged" ? `${note}The Kryd block in AGENTS.md is up to date.
+` : note);
+}
+async function runInit(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  if (opts.agents) {
+    runInitAgents(cwd);
+    return;
+  }
+  let apiUrl = resolveApiUrl(opts.apiUrl);
+  const session = await settleLogin({
+    apiUrl,
+    ...opts.apiUrl ? { apiUrlFlag: opts.apiUrl } : {},
+    ...opts.io ? { io: opts.io } : {},
+    offerLogin: opts.offerLogin !== false,
+    command: "kryd init"
+  });
+  if (!session) return;
+  const { token } = session;
+  apiUrl = session.apiUrl;
   const existingLink = directoryIsLinked(cwd);
   if (existingLink) {
     const remote = hasRemote(cwd, "kryd");
@@ -18133,6 +18319,7 @@ async function runInit(opts) {
         `This folder is already linked to ${existingLink.projectId} (.kryd/project.json).
 Running \`kryd init\` again would create a SECOND project and leave that one orphaned.
 To deploy it: \`kryd push\`. To start over: \`kryd project rm\` first, or delete .kryd/project.json to unlink this folder.
+To write or refresh the Kryd block in AGENTS.md: \`kryd init --agents\`.
 `
       );
       process.exitCode = 1;
@@ -18182,10 +18369,10 @@ To deploy it: \`kryd push\`. To start over: \`kryd project rm\` first, or delete
     try {
       saveProjectLink(cwd, { projectId: project2.id });
       try {
-        const session = await whoami(apiUrl, token);
+        const session2 = await whoami(apiUrl, token);
         rememberLinkAccount(cwd, {
-          accountId: session.accountId,
-          accountSlug: session.accountSlug
+          accountId: session2.accountId,
+          accountSlug: session2.accountSlug
         });
       } catch {
       }
@@ -18244,9 +18431,10 @@ Scheduled and triggered work runs on your production deploy; preview branches bu
 Preview branches deploy to https://<branch>-<hash>-${project2.subdomain}.${PREVIEW_TLD}
 ` + (declaration?.workflowsPath ? `Workflows in ${declaration.workflowsPath}/ run as a worker beside it on production deploys; previews run the web app only.
 ` : "");
+    const agentsNote = installAgentsBlock(cwd).note;
     process.stdout.write(
       `Linked "${name}" (${project2.framework}) \u2192 ${repo.htmlUrl}
-` + routing + `${linkNote}
+` + routing + `${linkNote}` + agentsNote + `
 ${nextStep}`
     );
   } catch (err) {
@@ -19265,26 +19453,34 @@ AI_GATEWAY_URL and AI_GATEWAY_TOKEN stop being injected from your next deploy (k
     await reportError(err);
   }
 }
-async function reportResourceStatus(opts) {
+async function readResourceStatus(opts) {
   try {
-    const result = await opts.read();
-    if (result.status === "failed") {
-      process.stdout.write(
-        `${opts.project}: ${opts.noun} failed \u2014 ${result.failureReason ?? "unknown error"}.
-Remove it before attaching another.
-`
-      );
-      return;
-    }
-    process.stdout.write(`${opts.project}: ${opts.noun} ${result.status}.
-`);
+    return toResourceState(await opts.read());
   } catch (err) {
     if (err instanceof ApiError && err.status === 404 && await projectIsVisible(opts.token, opts.project) === true) {
-      process.stdout.write(`${opts.project}: no ${opts.noun} attached.
-`);
-      return;
+      return NOT_ATTACHED;
     }
     await reportError(err);
+    return null;
+  }
+}
+var NOT_ATTACHED = { attached: false, status: null, failureReason: null };
+function toResourceState(row) {
+  return { attached: true, status: row.status, failureReason: row.failureReason ?? null };
+}
+function printResourceStatus(state, noun, project2) {
+  if (!state.attached) {
+    process.stdout.write(`${project2}: no ${noun} attached.
+`);
+  } else if (state.status === "failed") {
+    process.stdout.write(
+      `${project2}: ${noun} failed \u2014 ${state.failureReason ?? "unknown error"}.
+Remove it before attaching another.
+`
+    );
+  } else {
+    process.stdout.write(`${project2}: ${noun} ${state.status}.
+`);
   }
 }
 async function runDbStatus(opts) {
@@ -19300,21 +19496,22 @@ async function runDbStatus(opts) {
     reportNotLinked("kryd db status <projectId>");
     return;
   }
-  let productionAttached = false;
-  await reportResourceStatus({
-    read: async () => {
-      const row = await getDatabaseStatus(apiUrl, token, project2);
-      productionAttached = true;
-      return row;
-    },
-    noun: "database",
+  const production = await readResourceStatus({
+    read: () => getDatabaseStatus(apiUrl, token, project2),
     project: project2,
     token
   });
-  if (!productionAttached) return;
+  if (!production) return;
+  if (!opts.json) printResourceStatus(production, "database", project2);
+  if (!production.attached) {
+    if (opts.json) printJson2({ production, preview: NOT_ATTACHED });
+    return;
+  }
   try {
     const preview = await readPreviewDatabase(apiUrl, token, project2);
-    if (!preview) {
+    if (opts.json) {
+      printJson2({ production, preview: preview ? toResourceState(preview) : NOT_ATTACHED });
+    } else if (!preview) {
       process.stdout.write(
         `${project2}: no preview database \u2014 preview deploys use the production database.
 `
@@ -19353,12 +19550,14 @@ async function runStorageStatus(opts) {
     reportNotLinked("kryd storage status <projectId>");
     return;
   }
-  await reportResourceStatus({
+  const state = await readResourceStatus({
     read: () => getStorageStatus(apiUrl, token, project2),
-    noun: "object storage",
     project: project2,
     token
   });
+  if (!state) return;
+  if (opts.json) printJson2(state);
+  else printResourceStatus(state, "object storage", project2);
 }
 async function runAiStatus(opts) {
   const apiUrl = resolveApiUrl(opts.apiUrl);
@@ -19375,6 +19574,10 @@ async function runAiStatus(opts) {
   }
   try {
     const status = await getAiStatus(apiUrl, token, project2);
+    if (opts.json) {
+      printJson2(status);
+      return;
+    }
     if (!status.enabled) {
       process.stdout.write(`${project2}: no AI endpoint.
 `);
@@ -19489,6 +19692,14 @@ async function runWorkflowStatus(opts) {
   }
   try {
     const status = await getWorkflowStatus(apiUrl, token, project2);
+    if (opts.json) {
+      printJson2({
+        enabled: status.enabled,
+        tokenExpiresAt: status.tokenExpiresAt,
+        tokenExpiresInDays: status.tokenExpiresAt ? daysUntil(status.tokenExpiresAt) : null
+      });
+      return;
+    }
     if (!status.enabled) {
       process.stdout.write(`${project2}: no workflows.
 `);
@@ -19644,6 +19855,10 @@ async function runDomainStatus(opts) {
     const own = list.projectHost ? `${ctx.project} is always served at ${list.projectHost}.
 ` : "";
     if (!opts.host) {
+      if (opts.json) {
+        printJson2(list);
+        return;
+      }
       if (list.domains.length === 0) {
         process.stdout.write(`${ctx.project}: no custom domains.
 ${own}`);
@@ -19668,6 +19883,10 @@ ${own}`);
       process.exitCode = 1;
       return;
     }
+    if (opts.json) {
+      printJson2(d);
+      return;
+    }
     let out = `${d.host}: ${DOMAIN_STATUS_TEXT[d.status]}.
 `;
     if (d.redirectTo) out += `  \u2192 redirects to ${d.redirectTo}
@@ -19722,7 +19941,7 @@ async function runWorkflowInit(opts) {
   }
   const workerName = workerNameFrom(opts.name ?? basename2(target));
   const files = scaffoldFiles(language, workerName);
-  const clashes = files.map((f) => f.path).filter((p) => existsSync3(join3(target, p)));
+  const clashes = files.map((f) => f.path).filter((p) => existsSync4(join4(target, p)));
   if (clashes.length > 0) {
     process.stderr.write(
       `Refusing to overwrite: ${clashes.join(", ")}.
@@ -19732,12 +19951,22 @@ Nothing was written. Run this in an empty directory, or pass --dir <path>.
     process.exitCode = 1;
     return;
   }
+  if (opts.link !== false) {
+    const session = await settleLogin({
+      apiUrl: resolveApiUrl(opts.apiUrl),
+      ...opts.apiUrl ? { apiUrlFlag: opts.apiUrl } : {},
+      ...opts.io ? { io: opts.io } : {},
+      offerLogin: true,
+      command: "kryd workflow init"
+    });
+    if (!session) return;
+  }
   const written = [];
   try {
     for (const file2 of files) {
-      const full = join3(target, file2.path);
+      const full = join4(target, file2.path);
       mkdirSync2(dirname2(full), { recursive: true });
-      writeFileSync2(full, file2.contents);
+      writeFileSync3(full, file2.contents);
       written.push(full);
     }
   } catch (err) {
@@ -19774,6 +20003,7 @@ To add a worker to the app in that repository instead, run \`kryd workflow init\
     process.exitCode = 1;
     return;
   }
+  process.stdout.write(installAgentsBlock(target).note);
   const next = [];
   if (opts.dir) next.push(`cd ${opts.dir}`);
   const first = firstCommand(language);
@@ -19823,7 +20053,7 @@ function scaffoldContainedWorker(opts) {
       "This directory is not linked to a Kryd project, so there is no app to add a worker to.\nLink your app first (`kryd init`), then run this again \u2014 or pass --only for a project that runs nothing but a worker.\n"
     );
     process.exitCode = 1;
-    return;
+    return false;
   }
   const raw = (opts.path ?? DEFAULT_WORKFLOWS_PATH).trim();
   const segments = raw.split("/").filter((seg) => seg !== "" && seg !== ".");
@@ -19833,14 +20063,14 @@ function scaffoldContainedWorker(opts) {
 `
     );
     process.exitCode = 1;
-    return;
+    return false;
   }
   const folder = segments.join("/");
-  const declarationPath = join3(target, DECLARATION_FILE);
+  const declarationPath = join4(target, DECLARATION_FILE);
   let existing = {};
   let existingText = null;
-  if (existsSync3(declarationPath)) {
-    existingText = readFileSync3(declarationPath, "utf8");
+  if (existsSync4(declarationPath)) {
+    existingText = readFileSync4(declarationPath, "utf8");
     let parsed;
     try {
       parsed = JSON.parse(existingText);
@@ -19853,7 +20083,7 @@ function scaffoldContainedWorker(opts) {
 `
       );
       process.exitCode = 1;
-      return;
+      return false;
     }
     existing = parsed;
     if ("kind" in existing) {
@@ -19862,7 +20092,7 @@ function scaffoldContainedWorker(opts) {
 `
       );
       process.exitCode = 1;
-      return;
+      return false;
     }
     if ("workflows" in existing || existing["web"] === false) {
       process.stderr.write(
@@ -19870,7 +20100,7 @@ function scaffoldContainedWorker(opts) {
 `
       );
       process.exitCode = 1;
-      return;
+      return false;
     }
   }
   const workerName = workerNameFrom(opts.name ?? basename2(target));
@@ -19878,7 +20108,7 @@ function scaffoldContainedWorker(opts) {
     path: `${folder}/${f.path}`,
     contents: f.contents
   }));
-  const clashes = files.map((f) => f.path).filter((p) => existsSync3(join3(target, p)));
+  const clashes = files.map((f) => f.path).filter((p) => existsSync4(join4(target, p)));
   if (clashes.length > 0) {
     process.stderr.write(
       `Refusing to overwrite: ${clashes.join(", ")}.
@@ -19886,18 +20116,18 @@ Nothing was written. Pick another folder with --path <folder>.
 `
     );
     process.exitCode = 1;
-    return;
+    return false;
   }
   const declaration = { ...existing, workflows: { path: folder } };
   const written = [];
   try {
     for (const file2 of files) {
-      const full = join3(target, file2.path);
+      const full = join4(target, file2.path);
       mkdirSync2(dirname2(full), { recursive: true });
-      writeFileSync2(full, file2.contents);
+      writeFileSync3(full, file2.contents);
       written.push(full);
     }
-    writeFileSync2(declarationPath, `${JSON.stringify(declaration, null, 2)}
+    writeFileSync3(declarationPath, `${JSON.stringify(declaration, null, 2)}
 `);
   } catch (err) {
     for (const path of written.reverse()) {
@@ -19908,7 +20138,7 @@ Nothing was written. Pick another folder with --path <folder>.
     }
     try {
       if (existingText === null) rmSync2(declarationPath, { force: true });
-      else writeFileSync2(declarationPath, existingText);
+      else writeFileSync3(declarationPath, existingText);
     } catch {
     }
     process.stderr.write(
@@ -19917,14 +20147,15 @@ Nothing was left behind.
 `
     );
     process.exitCode = 1;
-    return;
+    return false;
   }
+  const agents = installAgentsBlock(target);
   const next = [];
   const first = firstCommand(language);
   if (first) next.push(`(cd ${folder} && ${first})`);
   next.push(
     "kryd workflow add",
-    `git add ${DECLARATION_FILE} ${folder} && git commit -m "add workflows"`,
+    `git add ${[DECLARATION_FILE, folder, ...agents.changed].join(" ")} && git commit -m "add workflows"`,
     "kryd push"
   );
   process.stdout.write(
@@ -19937,9 +20168,10 @@ Next: ${next.map((c) => `\`${c}\``).join(", then ")}.
 HATCHET_CLIENT_TOKEN is injected into your app and your worker on production deploys (previews get none) \u2014 your app triggers tasks with it; it is never available locally.
 ` + // The app is still built (and type-checked) from the root, so a tsconfig that includes every
     // file would compile the worker too — against an SDK the app does not depend on.
-    (existsSync3(join3(target, "tsconfig.json")) ? `Add "${folder}" to the "exclude" of your tsconfig.json, so your app's build does not type-check the worker.
-` : "")
+    (existsSync4(join4(target, "tsconfig.json")) ? `Add "${folder}" to the "exclude" of your tsconfig.json, so your app's build does not type-check the worker.
+` : "") + agents.note
   );
+  return true;
 }
 async function runStorageRemove(opts) {
   const apiUrl = resolveApiUrl(opts.apiUrl);
@@ -20019,6 +20251,11 @@ async function runProjectList(opts) {
     await reportError(err);
     return;
   }
+  if (opts.json) {
+    const linked = resolveProjectId(void 0, opts.cwd);
+    printJson2({ items: projects.map((p) => ({ ...p, linked: p.id === linked })) });
+    return;
+  }
   if (projects.length === 0) {
     process.stdout.write("No projects yet \u2014 run `kryd init` in a project directory.\n");
     return;
@@ -20070,6 +20307,10 @@ async function runEnvList(opts) {
   }
   try {
     const vars = await listEnvVars(apiUrl, token, project2);
+    if (opts.json) {
+      printJson2({ items: vars });
+      return;
+    }
     if (vars.length === 0) {
       process.stdout.write(
         `No environment variables for ${project2} yet.
@@ -20155,7 +20396,7 @@ async function runEnvPull(opts) {
   const root = findProjectLinkDir(cwd) ?? cwd;
   const outRel = opts.out ?? ".env.kryd";
   const outPath = resolve2(root, outRel);
-  if (opts.out !== void 0 && existsSync3(outPath) && !opts.force) {
+  if (opts.out !== void 0 && existsSync4(outPath) && !opts.force) {
     process.stderr.write(
       `Refusing to overwrite ${outRel} \u2014 pass --force to replace it (or omit --out to write .env.kryd).
 `
@@ -20429,7 +20670,7 @@ Run \`kryd env list\` to see what is set. (If you meant the runtime variable of
     await reportError(err);
   }
 }
-var CLI_VERSION = true ? "0.17.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.18.0" : "0.0.0-dev";
 var program = new Command();
 program.name("kryd").description("Kryd CLI").version(CLI_VERSION);
 program.hook("postAction", async () => {
@@ -20439,7 +20680,7 @@ program.command("login").description("Sign in via the browser (default) and stor
   "--token <token>",
   "supply a token instead of the browser flow (prefer $KRYD_TOKEN \u2014 flags are visible in `ps`)"
 ).option("--api-url <url>", "control-plane API base URL").option("--dashboard-url <url>", "dashboard base URL for the browser approve page (default app.kryd.eu)").action((opts) => runLogin(opts));
-program.command("whoami").description("Show the current account").option("--api-url <url>", "control-plane API base URL").action((opts) => runWhoami(opts));
+program.command("whoami").description("Show the current account").option("--json", "print the user and their accounts as JSON on stdout").option("--api-url <url>", "control-plane API base URL").action((opts) => runWhoami(opts));
 var accountCommand = program.command("account").description("The accounts you belong to, and which one commands run in");
 accountCommand.command("list").description("List your accounts and your role in each; * marks the one commands run in").option("--json", "print the accounts as JSON on stdout").option("--api-url <url>", "control-plane API base URL").action((opts) => runAccountList(opts));
 accountCommand.command("use <slug>").description("Run every following command in this account").option("--api-url <url>", "control-plane API base URL").action((slug, opts) => runAccountUse(slug, opts));
@@ -20467,7 +20708,10 @@ program.command("init").description(
   "--public",
   // KRYD-184a. Chosen at creation; there is no command to flip it afterwards yet (KRYD-341).
   "create the repository PUBLIC \u2014 readable by anyone signed in to the forge (default: private). Set at creation only"
-).option("--api-url <url>", "control-plane API base URL").action((opts) => runInit(opts));
+).option("--api-url <url>", "control-plane API base URL").option(
+  "--agents",
+  "only write or refresh the Kryd block in AGENTS.md of the linked project (no login, no API call) \u2014 e.g. after updating the CLI"
+).action((opts) => runInit(opts));
 program.command("logs [target]").description(
   "Follow logs. Default: a deploy's build/deploy logs ([target]=deployment id, latest if omitted). With --runtime: a container's stdout/stderr \u2014 [target]=a project id tails its live app, a deployment id (dpl_\u2026) tails THAT deploy's container (incl. a failed one, to see why it crashed). With --worker: a project's workflow worker, also when the project has a web app."
 ).option(
@@ -20504,7 +20748,7 @@ program.command("redeploy [project]").description(
   "Redeploy the current live commit (no rebuild) to apply config/env changes, and follow it live"
 ).option("--app <name>", "a project with several web apps: which app to redeploy").option("--logs", LOGS_FLAG_HELP).option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runRedeploy({ ...opts, project: project2 }));
 var project = program.command("project").description("Manage your projects");
-project.command("list").description("List your projects \u2014 name, subdomain, status and id").option("--api-url <url>", "control-plane API base URL").action((opts) => runProjectList(opts));
+project.command("list").description("List your projects \u2014 name, subdomain, status and id").option("--json", "print { items } as JSON on stdout, each with `linked`").option("--api-url <url>", "control-plane API base URL").action((opts) => runProjectList(opts));
 project.command("rm [project]").description(
   "Permanently delete a project and everything Kryd created for it (by name or id; asks you to type its name)"
 ).option("--yes", "skip the confirmation (for non-interactive use)").option("--api-url <url>", "control-plane API base URL").action((projectArg, opts) => runProjectRemove({ ...opts, project: projectArg }));
@@ -20521,13 +20765,13 @@ db.command("add [project]").description("Attach a shared or bring-your-own Postg
 ).option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runDbAdd({ ...opts, project: project2 }));
 db.command("remove [project]").description("Tear down the project's database and everything in it (asks for confirmation)").option("--preview", "remove the preview database; production is not touched").option("--yes", "skip the confirmation prompt").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runDbRemove({ ...opts, project: project2 }));
 db.command("reset [project]").description("Empty the preview database: every table dropped, credentials kept (asks for confirmation)").option("--preview", "required \u2014 only the preview database can be reset").option("--yes", "skip the confirmation prompt").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runDbReset({ ...opts, project: project2 }));
-db.command("status [project]").description("Show the project's database and preview database, and what state they are in").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runDbStatus({ ...opts, project: project2 }));
+db.command("status [project]").description("Show the project's database and preview database, and what state they are in").option("--json", "print { production, preview } as JSON on stdout").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runDbStatus({ ...opts, project: project2 }));
 var storage = program.command("storage").description("Manage project object storage");
 storage.command("add [project]").description("Create an S3-compatible object-storage bucket for a project").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runStorageAdd({ ...opts, project: project2 }));
 storage.command("remove [project]").description("Tear down the project's bucket and every object in it (asks for confirmation)").option("--yes", "skip the confirmation prompt").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runStorageRemove({ ...opts, project: project2 }));
-storage.command("status [project]").description("Show whether the project has object storage, and what state it is in").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runStorageStatus({ ...opts, project: project2 }));
+storage.command("status [project]").description("Show whether the project has object storage, and what state it is in").option("--json", "print { attached, status, failureReason } as JSON on stdout").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runStorageStatus({ ...opts, project: project2 }));
 var env = program.command("env").description("Manage your app's environment variables");
-env.command("list [project]").description("List the project's environment variables (names and origin \u2014 never values)").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runEnvList({ ...opts, project: project2 }));
+env.command("list [project]").description("List the project's environment variables (names and origin \u2014 never values)").option("--json", "print { items } as JSON on stdout (never values)").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runEnvList({ ...opts, project: project2 }));
 env.command("set <key> [project]").description(
   "Set one of your environment variables \u2014 `KEY=VALUE`, or `KEY` with --stdin / a prompt"
 ).option(
@@ -20559,11 +20803,11 @@ env.command("pull [project]").description(
 var ai = program.command("ai").description("Manage the app's EU AI gateway");
 ai.command("add [project]").description("Give the project an authenticated EU AI endpoint (injects on next deploy)").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runAiAdd({ ...opts, project: project2 }));
 ai.command("remove [project]").description("Stop injecting the project's AI endpoint (asks for confirmation)").option("--yes", "skip the confirmation prompt").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runAiRemove({ ...opts, project: project2 }));
-ai.command("status [project]").description("Show whether the project has an AI endpoint, and what it is").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runAiStatus({ ...opts, project: project2 }));
+ai.command("status [project]").description("Show whether the project has an AI endpoint, and what it is").option("--json", "print { enabled, url } as JSON on stdout").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runAiStatus({ ...opts, project: project2 }));
 var workflow = program.command("workflow").description("Manage the project's durable workflows (its own workflow tenant)");
 workflow.command("add [project]").description("Give the project a workflow tenant and inject HATCHET_CLIENT_TOKEN on next deploy").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runWorkflowAdd({ ...opts, project: project2 }));
 workflow.command("remove [project]").description("Revoke the project's workflow token and stop injecting it (asks for confirmation)").option("--yes", "skip the confirmation prompt").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runWorkflowRemove({ ...opts, project: project2 }));
-workflow.command("status [project]").description("Show whether the project has workflows, and when its token expires").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runWorkflowStatus({ ...opts, project: project2 }));
+workflow.command("status [project]").description("Show whether the project has workflows, and when its token expires").option("--json", "print { enabled, tokenExpiresAt, tokenExpiresInDays } as JSON on stdout").option("--api-url <url>", "control-plane API base URL").action((project2, opts) => runWorkflowStatus({ ...opts, project: project2 }));
 workflow.command("init").description(
   "Add a workflow worker to the linked app here (in ./workflows, declared in kryd.json); --only scaffolds a worker-only project instead and links it"
 ).requiredOption(
@@ -20576,7 +20820,7 @@ domain2.command("add <host>").description("Add a custom domain and print the DNS
   "redirect instead of serving: every request answers 301 to https://<host>, path and query kept"
 ).option("--api-url <url>", "control-plane API base URL").action((host, opts) => runDomainAdd({ ...opts, host }));
 domain2.command("remove <host>").description("Remove a custom domain \u2014 its route and certificate go (asks for confirmation)").option("--project <projectId>", "the project (default: the one linked here)").option("--yes", "skip the confirmation prompt").option("--api-url <url>", "control-plane API base URL").action((host, opts) => runDomainRemove({ ...opts, host }));
-domain2.command("status [host]").description("Show the project's custom domains, or one in detail with what is missing").option("--project <projectId>", "the project (default: the one linked here)").option("--api-url <url>", "control-plane API base URL").action((host, opts) => runDomainStatus({ ...opts, host }));
+domain2.command("status [host]").description("Show the project's custom domains, or one in detail with what is missing").option("--project <projectId>", "the project (default: the one linked here)").option("--json", "print the domain list, or the one domain, as JSON on stdout").option("--api-url <url>", "control-plane API base URL").action((host, opts) => runDomainStatus({ ...opts, host }));
 var support = program.command("support").description(
   "Ask Kryd support a question, report a bug or a wish, and read the answer \u2014 non-interactive, with --json for agents"
 );
@@ -20594,7 +20838,7 @@ function invokedDirectly() {
   const entry = process.argv[1];
   if (!entry) return false;
   try {
-    return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    return import.meta.url === pathToFileURL(realpathSync2(entry)).href;
   } catch {
     return false;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kryd/cli",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Kryd CLI — git push → live on the European cloud for your AI: SSL, managed Postgres & object storage, and an EU-hosted AI gateway. Your code and model calls stay in the EU. Beta: sign up at https://kryd.eu/beta",
   "keywords": [
     "kryd",