syndai 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to the `syndai` npm package. Versions follow semver.
 
+## 0.5.0
+
+Environments and secrets from a terminal, Doppler-style.
+
+- `env ls` lists the workspace's environments (the current one marked); `env use <env>` picks
+  the one this directory uses, stored in its link outside the repo. `link [project] --env E`
+  sets both. Otherwise: `--env`, then `SYNDAI_ENV`, then the workspace default.
+- `secrets` lists names, scope (shared or project) and when each changed, never a value.
+  `secrets set KEY` reads the value from a hidden prompt or stdin, never the command line;
+  `secrets rm KEY` asks first (`--yes` off a terminal); `secrets import FILE|-` stores a
+  `.env` in one all-or-nothing request. `--project` writes at the project's scope.
+- `secrets get KEY` prints one value to a terminal (`--plain` for a pipe, exact bytes);
+  `secrets download [-o FILE]` writes a `.env` to a pipe, or to a 0600 file and warns when git
+  does not ignore it; `run [--env E] [--] <command>` hands the values to the child's environment
+  only and exits with its code. The values layer the way a run's do: the project's over the
+  shared ones, over Test.
+- Reading values needs `coding:secrets:reveal`, which only a browser approval grants: the
+  first secrets command asks once for read, write and reveal together. Production values also
+  need you to allow each command in the browser; another process holding the same key, `SYNDAI_API_KEY`
+  (CI) and an MCP key never read them (exit 3).
+
+Learn from a product.
+
+- `new "<text>"` starts a project from scratch. A product link in the text (not GitHub) builds
+  your own version of it: Syndai reads its public pages, then asks which features to build and
+  what to call it. `--no-learn` treats the link as context only.
+- `change "<text>" --learn URL` adds features from that product to an existing project: Syndai
+  reads its public pages and asks which features to add (3 pre-checked). A link inside the
+  change text is never treated as one.
+
+## 0.4.1
+
+- A running `watch`, `change` or MCP server no longer stops when `login` or a scope
+  approval in another terminal replaces its key. On a 401 the CLI reads the stored key
+  again once, and retries with it if it changed. `SYNDAI_API_KEY` is never re-read.
+
 ## 0.4.0
 
 Every published API operation, and a project's recurring runs.

package/README.md

@@ -9,6 +9,18 @@ npx -y syndai@latest change "make the header blue"
 # Changing bakery.syndai.app · goes live when checks pass
 ```
 
+Secrets and environments, Doppler-style:
+
+```bash
+syndai link bakery --env development     # this directory: project + environment
+syndai secrets                           # names, scope, updated (never a value)
+printf %s "$TOKEN" | syndai secrets set API_TOKEN   # or type it at the hidden prompt
+syndai secrets import .env               # a whole .env, all or nothing
+syndai run npm run dev                   # the values reach npm's environment only
+syndai secrets download -o .env.local    # 0600, warns if git does not ignore it
+syndai run --env production ./deploy     # asks you to allow this one command
+```
+
 Node 22 or newer, zero dependencies, no telemetry. The customer guide is the docs
 site's **CLI** page, https://syndai.ai/docs/cli (`web/content/docs/cli.mdx`); this
 README is for whoever works on the package.
@@ -18,8 +30,13 @@ README is for whoever works on the package.
 | command | does |
 |---|---|
 | `login [--with-token] [--scope S]...`, `logout`, `whoami` | browser-approved key (device flow); `--scope` asks for access on top of the key's current scopes; `--with-token` reads a key from stdin. Re-login saves the new key, then revokes the old one |
-| `link [project]` | remember which project this directory changes (`$XDG_CONFIG_HOME/syndai/links.json`, never in the repo) |
-| `change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]` | start a change and follow it to the outcome |
+| `link [project] [--env E]` | remember which project (and environment) this directory uses (`$XDG_CONFIG_HOME/syndai/links.json`, never in the repo); a re-link keeps the environment |
+| `env ls`, `env use <env>` | the workspace's environments (current marked); `use` stores one in this directory's link (an environment-only link when there is none). Chosen: `--env`, `SYNDAI_ENV`, the link, the workspace default |
+| `secrets [ls]` | names, scope (shared/project) and updated for the environment and this project; never a value, in text or `--json` |
+| `secrets set KEY`, `rm KEY [--yes]`, `import FILE\|-` [`--project`] | write shared values (or the project's with `--project`); `set` reads the value from a hidden prompt (one line) or stdin (any value, multi-line too), and refuses one on the command line without echoing it |
+| `secrets get KEY [--plain]`, `download [-o FILE]` | read values back: `get` refuses a pipe without `--plain` (then the exact bytes) and `--json`; `download` writes a pipe, or a 0600 file (`-o`, required on a terminal) and warns when git does not ignore it |
+| `run [--env E] [--app A] [--] <command>...` | spawn the command (syndai's options end at its first word; `--` only for a dash-led command) with the values added to its environment only; prints `Injected N values from <env>`; its exit code (a signal: 128+n, not found: 127) is syndai's |
+| `change "<what>" [--app A] [--review] [--learn URL] [--image F]... [--no-wait] [--timeout D]` | start a change and follow it to the outcome; `--learn URL` reads that product's public pages and asks which of its features to add (3 pre-checked), then adds only those |
 | `new "<what>" [--no-learn] [--no-wait] [--timeout D]` | start a New project; a product URL in the text builds your own version of it (its feature pick is asked inline, Enter keeps the pre-checked core) |
 | `edit-text [--app A] [--page /] --from "..." --to "..."` / `--undo <sha>` | instant, free, undoable text swap on a live site |
 | `watch <run> [--timeout D] [--logs]` | follow any change; `--logs` tails its events |
@@ -40,6 +57,13 @@ README is for whoever works on the package.
 A 403 that names a missing scope asks, on a terminal with a stored login, to approve
 it in the browser and retries once. `SYNDAI_API_KEY` never steps up; off a terminal the
 error names `syndai login --scope <scope>`. Members, keys and unpublish are portal-only.
+A missing `coding:secrets:*` scope asks once for all three (read, write, reveal). Reveal
+(reading values) is granted only by that browser approval, never by `--with-token`, the
+portal's key page or `mcp install`. A production environment's values also need a
+`PRODUCTION_STEP_UP_REQUIRED` approval: on a terminal with a stored login the CLI opens
+`/cli` for a person to allow THIS command, then retries once with that approval's grant (held
+in memory only, so another process with the same key gets nothing); off a terminal or under
+`SYNDAI_API_KEY` it exits 3.
 
 Exit codes: 0 done, 1 failed/reverted/cancelled, 2 usage or no project, 3 needs you,
 4 live but unverified, 5 auth/scope/plan, 6 `--timeout` reached, 7 service
@@ -58,6 +82,8 @@ unavailable after retries, 130 interrupted (Ctrl-C detaches; it never cancels).
 - `src/openapi.js`: the live `/openapi.json` (cached 24h per host in `$XDG_CACHE_HOME/syndai`).
 - `src/api.js`: `syndai api` (operations by id, fields, `--paginate`).
 - `src/schedules.js`: `schedule` and `repeat` (the preset to cron mapping of `apps/portal-v2/src/lib/cadence.ts`).
+- `src/secrets.js`: `env`, `secrets` and `run` (environment choice, the production step-up retry).
+- `src/dotenv.js`: the `.env` reader (`import`) and writer (`download`); errors name lines, never values.
 - `src/changes.js`, `src/settings.js`, `src/mcp.js`: the other commands.
 
 ## Development
@@ -71,7 +97,8 @@ CI runs it in its own **CLI Checks** job (`pr-ci.yml`, `main-ci.yml`) whenever
 part of **PR Gate** and deploys nothing.
 
 The suite runs a fake API on 127.0.0.1 (serving `/openapi.json` from the snapshot) and
-drives the CLI in-process (plus two child-process tests for Ctrl-C and a clean exit).
+drives the CLI in-process (plus child-process tests for Ctrl-C, a clean exit and `run`'s
+real child). `test/secrets.test.js` searches every output and request for a sentinel value.
 `test/schedule.test.js` imports `apps/portal-v2/src/lib/cadence.ts` to prove the
 `--every` presets give the portal's cron; that needs a Node that strips TypeScript
 types (23.6+, as `.nvmrc`), and is skipped on Node 22. `test/contract.test.js` checks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syndai",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Syndai owner CLI: say what to change, and Syndai builds it, checks it and puts it live. Also installs the Syndai MCP server into Claude Code, Cursor and Codex.",
   "type": "module",
   "bin": {

package/src/auth.js

@@ -4,6 +4,10 @@
 // owner or admin approves the request in a browser session at app.syndai.ai/cli. The key is
 // stored per workspace in credentials.json (0600). `SYNDAI_API_KEY` wins over it (CI).
 // There is no --api-key flag, so a key never lands in shell history.
+//
+// Reading secret values needs `coding:secrets:reveal`, which only this browser approval
+// grants. Production values also need a person to allow THIS key in the browser, for 10
+// minutes (`productionStepUp`); a stored key alone, or SYNDAI_API_KEY, never reads them.
 
 import { hostname } from "node:os";
 import { ApiError, CliError, EXIT, explain, PORTAL_URL, steppable } from "./errors.js";
@@ -69,10 +73,22 @@ export function createContext(io, flags, { stepUp = true } = {}) {
     getKey: async () => credential().apiKey,
     io,
     onMissingScope: stepUp ? (scope) => stepUpScope(ctx, scope) : undefined,
+    onUnauthorized: async () => {
+      // A login or step-up in another process saves a new key, then revokes this one.
+      if (!cached || cached.source === "SYNDAI_API_KEY") return false;
+      const fresh = storedCredential(io, paths);
+      if (!fresh || fresh.apiKey === cached.apiKey) return false;
+      cached = fresh;
+      me = undefined;
+      return true;
+    },
   });
   return ctx;
 }
 
+/** One approval for every `syndai secrets` / `env` / `run` command, not one per scope. */
+export const SECRETS_SCOPES = ["coding:secrets:read", "coding:secrets:write", "coding:secrets:reveal"];
+
 /**
  * A 403 named the scope it needs. On a terminal, with the stored login (never
  * SYNDAI_API_KEY, which belongs to CI), ask once, approve a key with the current scopes plus
@@ -81,9 +97,11 @@ export function createContext(io, flags, { stepUp = true } = {}) {
 async function stepUpScope(ctx, scope) {
   const { io, ui } = ctx;
   if (!ui.interactive || !steppable(scope) || ctx.credential().source === "SYNDAI_API_KEY") return false;
-  const answer = await ask(io, `This needs the ${scope} scope. Approve it in your browser? [Y/n] `);
+  const secrets = SECRETS_SCOPES.includes(scope);
+  const what = secrets ? "access to this workspace's secrets" : `the ${scope} scope`;
+  const answer = await ask(io, `This needs ${what}. Approve it in your browser? [Y/n] `);
   if (/^n/i.test(answer)) return false;
-  const token = await deviceApproval(ctx, "CLI", await scopesWith(ctx, [scope]));
+  const token = await deviceApproval(ctx, "CLI", await scopesWith(ctx, secrets ? SECRETS_SCOPES : [scope]));
   await storeKey(ctx, token);
   return true;
 }
@@ -127,14 +145,53 @@ async function storeKey(ctx, token) {
  * Ask for a key and wait until an owner approves it in the browser. Returns the token
  * response `{api_key, customer_id, key_id, expires_at}`.
  */
-export async function deviceApproval(ctx, clientName, scopes) {
-  const { client, ui, io } = ctx;
-  const start = await client.call("deviceStart", {
+export function deviceApproval(ctx, clientName, scopes) {
+  return browserApproval(ctx, {
+    start: "deviceStart",
+    token: "deviceToken",
     // No `scopes` means the owner preset (owner_door); a list asks for those on top of it.
     body: { client_name: clientName, host: hostname(), ...(scopes ? { scopes } : {}) },
     auth: false,
-    retry: true,
+    again: "syndai login",
+  });
+}
+
+/**
+ * A production value was refused (403 PRODUCTION_STEP_UP_REQUIRED). On a terminal with the
+ * stored login (never SYNDAI_API_KEY), ask once, wait for a person to allow THIS key in the
+ * browser, and answer true so the caller retries once. Off a terminal: false (exit 3).
+ */
+export async function productionStepUp(ctx) {
+  const { io, ui } = ctx;
+  if (!ui.interactive || ctx.credential().source === "SYNDAI_API_KEY") return false;
+  const answer = await ask(io, "Production values need your approval in the browser for this command. Open it? [Y/n] ");
+  if (/^n/i.test(answer)) return false;
+  let grant;
+  const allowed = await browserApproval(ctx, {
+    start: "startProductionAccess",
+    token: "redeemProductionAccess",
+    body: { client_name: "CLI", host: hostname() },
+    auth: true,
+    again: "run the command again",
+    onStart: (start) => {
+      grant = start.device_code;
+    },
   });
+  const until = new Date(allowed.allowed_until).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  ui.progress(`Production values allowed for this command (until ${until}).`);
+  // The grant lives in this process only: another process with the same stored key has none.
+  return grant;
+}
+
+/**
+ * The RFC 8628 loop both approvals share: start, show the code and open the page, poll the
+ * token route until a person decides. `auth` sends the stored key (the production step-up
+ * is for the key that asks); `again` is the command a denied or expired code points to.
+ */
+async function browserApproval(ctx, { start: startRoute, token: tokenRoute, body, auth, again, onStart }) {
+  const { client, ui, io } = ctx;
+  const start = await client.call(startRoute, { body, auth, retry: true });
+  onStart?.(start);
   const url = start.verification_uri_complete ?? start.verification_uri;
   ui.progress(`Your one-time code: ${ui.bold(start.user_code)}`);
   ui.progress(`Approve it in your browser: ${url}`);
@@ -150,9 +207,9 @@ export async function deviceApproval(ctx, clientName, scopes) {
       if (io.signal.aborted) throw interrupted();
       throw err;
     }
-    const res = await client.call("deviceToken", {
+    const res = await client.call(tokenRoute, {
       body: { device_code: start.device_code },
-      auth: false,
+      auth,
       retry: true,
       raw: true,
     });
@@ -164,14 +221,10 @@ export async function deviceApproval(ctx, clientName, scopes) {
       continue;
     }
     if (error === "access_denied") {
-      throw new CliError(EXIT.AUTH, "The request was denied in the browser.", {
-        next: "syndai login",
-      });
+      throw new CliError(EXIT.AUTH, "The request was denied in the browser.", { next: again });
     }
     if (error === "expired_token" || error === "authorization_pending") {
-      throw new CliError(EXIT.AUTH, "The code expired before it was approved.", {
-        next: "syndai login",
-      });
+      throw new CliError(EXIT.AUTH, "The code expired before it was approved.", { next: again });
     }
     throw new ApiError(res.status, res.body, res.headers);
   }

package/src/changes.js

@@ -32,9 +32,14 @@ export async function change(ctx, words) {
   const text = words.join(" ").trim();
   if (!text) throw new CliError(EXIT.USAGE, 'Say what to change: syndai change "make the header blue"');
   const timeoutMs = timeoutOf(flags);
+  // --learn is explicit (L10): change prompts carry docs links and the owner's own site.
+  const reference = flags.learn === undefined ? null : productUrlFromText(flags.learn);
+  if (flags.learn !== undefined && !reference)
+    throw new CliError(EXIT.USAGE, `--learn takes a public product URL, like https://cal.com, not ${flags.learn}.`);
   const project = await resolveProject(ctx, { app: flags.app });
   const outcome = flags.review ? "opens a pull request for your review" : "goes live when checks pass";
   ui.progress(`Changing ${projectHost(project)} · ${outcome}`);
+  if (reference) ui.progress(`Learning from ${hostOf(reference)}`);
 
   const imageRefs = [];
   for (const file of flags.image ?? []) imageRefs.push(await uploadImage(ctx, file));
@@ -54,6 +59,7 @@ export async function change(ctx, words) {
       coding_repository_id: project.id,
       external_request_id: pending.request_id,
       ...(imageRefs.length ? { image_refs: imageRefs } : {}),
+      ...referenceField(reference),
       ...(flags.review ? { policy_config: { autonomy: "auto" } } : {}),
     },
   });
@@ -80,6 +86,11 @@ export function productUrlFromText(text) {
   return null;
 }
 
+const hostOf = (url) => new URL(url).hostname.replace(/^www\./, "");
+// The typed top-level create-run field (learn-from-a-product L1); `metadata.reference_product` is
+// server-owned and 400s.
+const referenceField = (url) => (url ? { reference_product: { kind: "url", value: url } } : {});
+
 /** Build-home parity: start a New project. A product URL in the text makes it "your own version
  * of X" (SPEC-build-your-own D5) unless --no-learn; its feature-pick question is asked inline. */
 export async function newProject(ctx, words) {
@@ -90,7 +101,7 @@ export async function newProject(ctx, words) {
   const reference = flags["no-learn"] ? null : productUrlFromText(text);
   ui.progress(
     reference
-      ? `New project · your own version of ${new URL(reference).hostname.replace(/^www\./, "")}`
+      ? `New project · your own version of ${hostOf(reference)}`
       : "New project",
   );
   const pending = findPending(paths, { app: "new", text }) ?? {
@@ -105,7 +116,7 @@ export async function newProject(ctx, words) {
       prompt: text,
       new_repository: { scaffold: "syndai-web" },
       external_request_id: pending.request_id,
-      ...(reference ? { metadata: { reference_product: { kind: "url", value: reference } } } : {}),
+      ...referenceField(reference),
     },
   });
   clearPending(paths, pending.request_id);

package/src/dotenv.js

@@ -0,0 +1,80 @@
+// `.env` text <-> values, for `syndai secrets import` and `syndai secrets download`.
+//
+// Read: KEY=VALUE lines, an optional `export ` prefix, blank lines and `#` comments, an
+// unquoted value's ` # comment`, 'single quotes' (literal) and "double quotes" (\n \r \t \"
+// \\ escapes); either quote may span lines. A later KEY wins. Errors name the line, never a
+// value or a name: a malformed line may be a pasted secret.
+// Write: one KEY=value per name, sorted, quoted only when the value needs it.
+
+import { CliError, EXIT } from "./errors.js";
+
+/** The server's secret-name grammar (`ENV_NAME_PATTERN`). */
+export const NAME = /^[A-Z][A-Z0-9_]{0,127}$/;
+
+const ESCAPES = { n: "\n", r: "\r", t: "\t", '"': '"', "\\": "\\" };
+
+function bad(lineNo, why) {
+  return new CliError(EXIT.USAGE, `.env line ${lineNo}: ${why}.`);
+}
+
+/** `.env` text -> `[{key_name, value}]` in file order (a repeated name keeps its last value). */
+export function parseDotenv(text) {
+  const lines = String(text).replace(/^/, "").split(/\r?\n/);
+  const values = new Map();
+  for (let i = 0; i < lines.length; i++) {
+    const lineNo = i + 1;
+    // Only the start is trimmed: a quoted value keeps its trailing spaces.
+    const line = lines[i].trimStart();
+    if (!line.trim() || line.startsWith("#")) continue;
+    const match = /^(?:export\s+)?([^=\s]+)\s*=\s*(.*)$/.exec(line);
+    if (!match) throw bad(lineNo, "expected KEY=VALUE");
+    const [, name, rest] = match;
+    if (!NAME.test(name)) throw bad(lineNo, "a name is uppercase letters, digits and _ (like API_TOKEN)");
+    const quote = rest[0];
+    if (quote !== '"' && quote !== "'") {
+      values.delete(name);
+      values.set(name, rest.replace(/\s+#.*$/, "").trim());
+      continue;
+    }
+    // A quoted value: read on (across lines) to the closing quote.
+    let value = "";
+    let chunk = rest.slice(1);
+    let closed = false;
+    for (;;) {
+      for (let j = 0; j < chunk.length; j++) {
+        const ch = chunk[j];
+        if (quote === '"' && ch === "\\" && j + 1 < chunk.length) {
+          const next = chunk[++j];
+          value += ESCAPES[next] ?? `\\${next}`;
+        } else if (ch === quote) {
+          if (!/^\s*(#.*)?$/.test(chunk.slice(j + 1))) throw bad(i + 1, "text after the closing quote");
+          closed = true;
+          break;
+        } else {
+          value += ch;
+        }
+      }
+      if (closed) break;
+      if (++i >= lines.length) throw bad(lineNo, "a quote is never closed");
+      value += "\n";
+      chunk = lines[i];
+    }
+    values.delete(name);
+    values.set(name, value);
+  }
+  return [...values].map(([key_name, value]) => ({ key_name, value }));
+}
+
+/** `{NAME: value}` -> `.env` text that `parseDotenv` (and dotenv, docker) read back exactly. */
+export function serializeDotenv(values) {
+  return Object.keys(values)
+    .sort()
+    .map((name) => `${name}=${quoted(values[name])}\n`)
+    .join("");
+}
+
+function quoted(value) {
+  if (/^[\w./:@%+,=-]*$/.test(value)) return value;
+  if (!/['\n\r]/.test(value)) return `'${value}'`;
+  return `"${value.replace(/[\\"\n\r\t]/g, (ch) => ({ "\\": "\\\\", '"': '\\"', "\n": "\\n", "\r": "\\r", "\t": "\\t" })[ch])}"`;
+}

package/src/errors.js

@@ -82,6 +82,11 @@ const KNOWN = {
     null,
   ],
   CLI_UPGRADE_REQUIRED: [EXIT.FAILED, "This version of syndai is too old.", "npx -y syndai@latest"],
+  PRODUCTION_STEP_UP_REQUIRED: [
+    EXIT.NEEDS_YOU,
+    "Production values need you to allow this command in your browser; a key alone never reads them.",
+    "run it again in a terminal logged in with syndai login",
+  ],
   RUN_CONCURRENCY_LIMIT: [EXIT.FAILED, "Too many changes are running at once.", "syndai status"],
   REPO_NOT_BOUND: [EXIT.USAGE, "That project is not available to this workspace.", "syndai link"],
   INSTALLATION_INCOMPLETE: [
@@ -102,6 +107,16 @@ const KNOWN = {
     "A change is in flight on this site; edit text once it lands.",
     (p) => (p.run_id ? `syndai watch ${p.run_id}` : "syndai status"),
   ],
+  REFERENCE_PRODUCT_INVALID: [
+    EXIT.USAGE,
+    "That is not a product link to learn from; use its full address, like https://cal.com.",
+    null,
+  ],
+  REFERENCE_PRODUCT_NEEDS_SCAFFOLD: [
+    EXIT.USAGE,
+    "Learning from a product needs a Syndai site project.",
+    null,
+  ],
   NOT_FOUND: [EXIT.FAILED, "Not found.", "syndai status"],
   RATE_LIMITED: [EXIT.UNAVAILABLE, "Syndai is rate-limiting this workspace.", null],
 };

package/src/http.js

@@ -39,11 +39,13 @@ export function interrupted() {
 /**
  * `onMissingScope(scope)` is asked once per request when a 403 names the scope it needs
  * (`required_scope`); when it answers true (a new key was approved), the request is sent
- * again with the new key.
+ * again with the new key. `onUnauthorized()` is asked once per request on a 401; when it
+ * answers true (another `syndai` process rotated the stored key), the request is sent again
+ * with the new key, so a long watch or MCP server outlives a login elsewhere.
  *
- * @param {{baseUrl: string, getKey: () => Promise<string>, io: object, onMissingScope?: (scope: string) => Promise<boolean>}} options
+ * @param {{baseUrl: string, getKey: () => Promise<string>, io: object, onMissingScope?: (scope: string) => Promise<boolean>, onUnauthorized?: () => Promise<boolean>}} options
  */
-export function createClient({ baseUrl, getKey, io, onMissingScope }) {
+export function createClient({ baseUrl, getKey, io, onMissingScope, onUnauthorized }) {
   /** Call a named route from `routes.js`. */
   function call(name, { params, ...opts } = {}) {
     const [method, path] = route(name, params);
@@ -66,6 +68,7 @@ export function createClient({ baseUrl, getKey, io, onMissingScope }) {
     const payload = body === undefined ? undefined : JSON.stringify(body);
 
     let steppedUp = false;
+    let reloaded = false;
     for (let attempt = 1; ; attempt++) {
       let res;
       let parsed;
@@ -95,6 +98,14 @@ export function createClient({ baseUrl, getKey, io, onMissingScope }) {
           continue;
         }
       }
+      if (res.status === 401 && auth && onUnauthorized && !reloaded) {
+        reloaded = true;
+        if (await onUnauthorized()) {
+          headers.authorization = `Bearer ${await getKey()}`;
+          attempt = 0;
+          continue;
+        }
+      }
       const transient =
         problem !== null &&
         (res.status >= 500 ||

package/src/main.js

@@ -1,6 +1,7 @@
 // Command table, argument parsing and the one error report. `main(argv, io)` takes all
 // process I/O as `io`, so tests drive it in-process with a fake server and fake clocks.
 
+import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 import { parseArgs } from "node:util";
 import { createContext, login, logout, whoami } from "./auth.js";
@@ -11,6 +12,7 @@ import { mcp } from "./mcp.js";
 import { link } from "./projects.js";
 import { api } from "./api.js";
 import { repeat, schedule } from "./schedules.js";
+import { env, run, secrets } from "./secrets.js";
 import { settings } from "./settings.js";
 import { closeInput, openBrowser, page } from "./ui.js";
 
@@ -20,10 +22,12 @@ const COMMON = { json: bool, "no-input": bool, help: { type: "boolean", short: "
 
 const COMMANDS = {
   change: {
-    usage: 'change "<what>" [--app A] [--review] [--image F]... [--no-wait] [--timeout D]',
-    summary: "Make a change; it goes live when its checks pass (--review: open a PR instead).",
+    usage: 'change "<what>" [--app A] [--review] [--learn URL] [--image F]... [--no-wait] [--timeout D]',
+    summary:
+      "Make a change; it goes live when its checks pass (--review: open a PR instead; --learn: pick features to add from a product's public pages).",
     options: {
       app: str,
+      learn: str,
       review: bool,
       image: { type: "string", multiple: true },
       "no-wait": bool,
@@ -110,11 +114,33 @@ const COMMANDS = {
     run: (ctx) => whoami(ctx),
   },
   link: {
-    usage: "link [project]",
-    summary: "Remember which project this directory changes (stored outside the repo).",
-    options: { app: str },
+    usage: "link [project] [--env E]",
+    summary: "Remember which project (and environment) this directory uses (stored outside the repo).",
+    options: { app: str, env: str },
     run: (ctx, [ref]) => link(ctx, ref),
   },
+  env: {
+    usage: "env ls | use <env>",
+    summary: "List the workspace's environments, or pick the one this directory uses.",
+    options: {},
+    run: (ctx, args) => env(ctx, args),
+  },
+  secrets: {
+    usage:
+      "secrets [ls] | set KEY | rm KEY [--yes] | import FILE|- | get KEY [--plain] | download [-o FILE]\n" +
+      "               [--env E] [--app A] [--project]",
+    summary:
+      "An environment's secrets: names only in lists and JSON; set reads the value from a hidden prompt or stdin; get and download need a browser-approved login (production: a fresh approval).",
+    options: { env: str, app: str, project: bool, plain: bool, output: { type: "string", short: "o" }, yes: bool },
+    run: (ctx, args) => secrets(ctx, args),
+  },
+  run: {
+    usage: "run [--env E] [--app A] [--] <command> [args...]",
+    summary: "Run a local command with the environment's values in its environment only; its exit code is syndai's.",
+    options: { env: str, app: str },
+    passthrough: true,
+    run: (ctx, command) => run(ctx, command),
+  },
   settings: {
     usage: "settings [--app A] [get | set key=value...]",
     summary: "autonomy, feature_requests, bug_scan, protected_paths (a key can only tighten them).",
@@ -167,7 +193,8 @@ export function helpText() {
     "",
     "Every command: --json (machine output; also when stdout is not a terminal),",
     "--no-input (never prompt), -h/--help.",
-    "Environment: SYNDAI_API_KEY (wins over `syndai login`), SYNDAI_APP, SYNDAI_API_URL, NO_COLOR.",
+    "Environment: SYNDAI_API_KEY (wins over `syndai login`; never reads production values),",
+    "SYNDAI_APP, SYNDAI_ENV, SYNDAI_API_URL, NO_COLOR.",
     "Exit codes: 0 done, 1 failed, 2 usage or no project, 3 needs you, 4 live but unverified,",
     "5 auth/scope/plan, 6 --timeout reached, 7 service unavailable, 130 interrupted.",
     "",
@@ -187,6 +214,33 @@ export function processIo(signal) {
     sleep: (ms, abortSignal) => sleep(ms, undefined, { signal: abortSignal }),
     openUrl: openBrowser,
     page: (text) => page(process, text),
+    /**
+     * `syndai run`: the child shares the terminal; resolves `{code, signal}` (ENOENT rejects).
+     * While it runs the parent never exits first (that would orphan a child holding the
+     * secrets): Ctrl-C reaches the child through the terminal, and SIGTERM/SIGHUP are passed on.
+     */
+    exec: (file, args, childEnv) =>
+      new Promise((resolve, reject) => {
+        const child = spawn(file, args, { stdio: "inherit", env: childEnv });
+        const saved = process.listeners("SIGINT");
+        process.removeAllListeners("SIGINT");
+        const forward = (sig) => child.kill(sig);
+        process.on("SIGINT", () => {});
+        for (const sig of ["SIGTERM", "SIGHUP"]) process.on(sig, forward);
+        const restore = () => {
+          process.removeAllListeners("SIGINT");
+          for (const listener of saved) process.on("SIGINT", listener);
+          for (const sig of ["SIGTERM", "SIGHUP"]) process.off(sig, forward);
+        };
+        child.once("error", (err) => {
+          restore();
+          reject(err);
+        });
+        child.once("exit", (code, exitSignal) => {
+          restore();
+          resolve({ code, signal: exitSignal });
+        });
+      }),
   };
 }
 
@@ -205,9 +259,11 @@ export async function main(argv, io) {
     io.stderr.write(`error: unknown command "${command}"\n\n${helpText()}`);
     return EXIT.USAGE;
   }
+  const options = { ...COMMON, ...spec.options };
+  const [own, child] = spec.passthrough ? splitCommand(rest, options) : [rest, null];
   let parsed;
   try {
-    parsed = parseArgs({ args: rest, options: { ...COMMON, ...spec.options }, allowPositionals: true });
+    parsed = parseArgs({ args: own, options, allowPositionals: true });
   } catch (err) {
     io.stderr.write(`error: ${err.message}\n  usage: syndai ${spec.usage}\n`);
     return EXIT.USAGE;
@@ -218,7 +274,7 @@ export async function main(argv, io) {
   }
   const ctx = createContext(io, parsed.values, { stepUp: spec.stepUp !== false });
   try {
-    return await spec.run(ctx, parsed.positionals);
+    return await spec.run(ctx, child ?? parsed.positionals);
   } catch (err) {
     return report(ctx, err);
   } finally {
@@ -226,6 +282,22 @@ export async function main(argv, io) {
   }
 }
 
+/**
+ * A passthrough command's own options end at `--` or at the child command's first word
+ * (`syndai run npm test --watch`): everything after belongs to the child, unparsed.
+ */
+function splitCommand(args, options) {
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--") return [args.slice(0, i), args.slice(i + 1)];
+    if (!arg.startsWith("-")) return [args.slice(0, i), args.slice(i)];
+    const name = arg.replace(/^--?/, "").split("=")[0];
+    const option = options[name] ?? Object.values(options).find((o) => o.short === name);
+    if (option?.type === "string" && !arg.includes("=")) i += 1; // its value is the next word
+  }
+  return [args, []];
+}
+
 /** One error line (plus the next command) on stderr; a JSON error on stdout for machines. */
 function report(ctx, err) {
   const { ui, io } = ctx;

package/src/projects.js

@@ -3,6 +3,9 @@
 // connected repo, the only project, a picker on a terminal. Otherwise exit 2 with the list.
 //
 // A project is a connected repository, joined with its app (live URL, slug) when it has one.
+// A link may also name an environment (`syndai env use`, `link --env`): one without a project
+// only picks the environment, so the project falls through to the next rule. The workspace's
+// environments are looked up here too, so `link --env` and `syndai env` share one check.
 
 import { execFileSync } from "node:child_process";
 import path from "node:path";
@@ -74,7 +77,7 @@ export async function resolveProject(ctx, { app, required = true, picker = true,
   if (io.env.SYNDAI_APP) return pick(io.env.SYNDAI_APP, "SYNDAI_APP");
   if (useLink) {
     const link = findLink(paths, io.cwd);
-    if (link) {
+    if (link?.project_id) {
       const linked = projects.find((p) => p.id === link.project_id);
       if (linked) return linked;
       throw noProject(projects, `The project linked to ${link.dir} is no longer in this workspace.`);
@@ -156,13 +159,41 @@ export function normalizeRemote(url) {
   return normal.replace(/\.git$/, "").replace(/\/+$/, "");
 }
 
+export async function listEnvironments(ctx) {
+  return (await ctx.client.call("listEnvironments")).environments;
+}
+
+/** The workspace environment named `slug` (exit 2 with the list when there is none). */
+export async function environmentBySlug(ctx, slug, environments) {
+  const envs = environments ?? (await listEnvironments(ctx));
+  const hit = envs.find((env) => env.slug === slug);
+  if (hit) return hit;
+  throw new CliError(EXIT.USAGE, `This workspace has no "${slug}" environment.`, {
+    next: "syndai env ls",
+    result: { data: { environments: envs.map((env) => env.slug) }, human: `Environments: ${envs.map((env) => env.slug).join(", ")}` },
+  });
+}
+
+/** `syndai link [project] [--env E]`: the project (and environment) this directory uses. */
 export async function link(ctx, ref) {
   const project = await resolveProject(ctx, { app: ref ?? ctx.flags.app, useLink: false });
   const dir = path.resolve(ctx.io.cwd);
-  saveLink(ctx.paths, dir, { project_id: project.id, name: project.name, customer_id: project.customer_id });
+  const here = findLink(ctx.paths, dir);
+  // A re-link keeps the environment this directory already chose, unless --env names one.
+  const environment = ctx.flags.env
+    ? (await environmentBySlug(ctx, ctx.flags.env)).slug
+    : here?.dir === dir
+      ? here.environment
+      : undefined;
+  saveLink(ctx.paths, dir, {
+    project_id: project.id,
+    name: project.name,
+    customer_id: project.customer_id,
+    ...(environment ? { environment } : {}),
+  });
   ctx.ui.result(
-    { dir, project_id: project.id, name: project.name },
-    `Linked ${dir} to ${projectLabel(project)}.`,
+    { dir, project_id: project.id, name: project.name, environment: environment ?? null },
+    `Linked ${dir} to ${projectLabel(project)}${environment ? ` (${environment})` : ""}.`,
   );
   return EXIT.OK;
 }

package/src/routes.js

@@ -45,6 +45,14 @@ export const ROUTES = Object.freeze({
   pauseSchedule: ["POST", `${EXT}/schedules/{schedule_id}/pause`],
   resumeSchedule: ["POST", `${EXT}/schedules/{schedule_id}/resume`],
   runScheduleNow: ["POST", `${EXT}/schedules/{schedule_id}/run-now`],
+  listEnvironments: ["GET", `${EXT}/environments`],
+  listSecrets: ["GET", `${EXT}/secrets`],
+  putSecret: ["PUT", `${EXT}/secrets/{key_name}`],
+  deleteSecret: ["DELETE", `${EXT}/secrets/{key_name}`],
+  importSecrets: ["POST", `${EXT}/secrets/import`],
+  resolveSecrets: ["POST", `${EXT}/secrets/resolve`],
+  startProductionAccess: ["POST", `${EXT}/cli/production-access`],
+  redeemProductionAccess: ["POST", `${EXT}/cli/production-access/token`],
 });
 
 /** The MCP endpoint `syndai mcp install` points clients at (JSON-RPC, not REST). */

package/src/secrets.js

@@ -0,0 +1,317 @@
+// `syndai env`, `syndai secrets` and `syndai run`: a workspace's environments and secrets from
+// a terminal, Doppler-style (docs: syndai.ai/docs/cli, "Secrets and environments").
+//
+// The environment: --env, else SYNDAI_ENV, else the directory's link (`syndai env use`,
+// `syndai link --env`), else the workspace default (where runs go). The project: the usual
+// resolver (--app, SYNDAI_APP, the link, the git remote, the only project), never a picker;
+// its values layer over the shared ones, as in a run. `set`, `rm` and `import` write shared
+// values unless --project.
+//
+// A value never travels through argv, JSON output, an error or a log line: `set` reads it from
+// a hidden prompt or stdin, `get` prints it only to a terminal (or with --plain), `download`
+// writes a 0600 file (or a pipe), and `run` hands values to the child's environment only.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import { constants } from "node:os";
+import path from "node:path";
+import { productionStepUp } from "./auth.js";
+import { NAME, parseDotenv, serializeDotenv } from "./dotenv.js";
+import { ApiError, CliError, EXIT } from "./errors.js";
+import { environmentBySlug, listEnvironments, projectLabel, resolveProject } from "./projects.js";
+import { findLink, saveLink, writeFileAtomic } from "./store.js";
+import { ask, askSecret, readAll } from "./ui.js";
+
+/** The slug the flags, SYNDAI_ENV or the link name; null means the workspace default. */
+function chosenSlug(ctx) {
+  return ctx.flags.env || ctx.io.env.SYNDAI_ENV || findLink(ctx.paths, ctx.io.cwd)?.environment || null;
+}
+
+/** The chosen environment, or the default one (both validated against the workspace). */
+async function chosenEnvironment(ctx, environments) {
+  const envs = environments ?? (await listEnvironments(ctx));
+  const slug = chosenSlug(ctx);
+  if (slug) return environmentBySlug(ctx, slug, envs);
+  const fallback = envs.find((env) => env.default) ?? envs[0];
+  if (!fallback) throw new CliError(EXIT.FAILED, "This workspace has no environments.", { next: "https://app.syndai.ai" });
+  return fallback;
+}
+
+/** The project whose values layer over the shared ones, or null (shared only). */
+function layeredProject(ctx) {
+  return resolveProject(ctx, { app: ctx.flags.app, required: false, picker: false });
+}
+
+/** The project a write targets: shared (null) unless --project. */
+async function writeTarget(ctx) {
+  if (!ctx.flags.project) return null;
+  return resolveProject(ctx, { app: ctx.flags.app, picker: false });
+}
+
+const scopeOf = (project) => (project ? `project ${projectLabel(project)}` : "shared");
+
+// --- syndai env --------------------------------------------------------------------------
+
+export async function env(ctx, [action = "ls", slug, ...extra]) {
+  if (action === "ls" && !slug) return envList(ctx);
+  if (action === "use" && slug && !extra.length) return envUse(ctx, slug);
+  throw new CliError(EXIT.USAGE, "Usage: syndai env ls | syndai env use <env>");
+}
+
+async function envList(ctx) {
+  const envs = await listEnvironments(ctx);
+  const current = (await chosenEnvironment(ctx, envs)).slug;
+  const rows = envs.map((e) => ({ ...e, current: e.slug === current }));
+  const width = Math.max(...rows.map((e) => e.slug.length), 4);
+  ctx.ui.result(
+    { environments: rows, current },
+    rows
+      .map((e) => `${e.current ? "*" : " "} ${e.slug.padEnd(width)}  ${e.name}  (${e.role}${e.default ? ", default" : ""})`)
+      .join("\n"),
+  );
+  return EXIT.OK;
+}
+
+async function envUse(ctx, slug) {
+  const environment = await environmentBySlug(ctx, slug);
+  const { paths, io } = ctx;
+  const here = findLink(paths, io.cwd);
+  // The nearest link keeps its project; with none, this directory gets an environment-only one.
+  const dir = here?.dir ?? path.resolve(io.cwd);
+  const { dir: _dir, ...kept } = here ?? { customer_id: await ctx.customerId() };
+  saveLink(paths, dir, { ...kept, environment: environment.slug });
+  ctx.ui.result({ dir, environment: environment.slug }, `${dir} now uses ${environment.slug}.`);
+  return EXIT.OK;
+}
+
+// --- syndai secrets ----------------------------------------------------------------------
+
+export async function secrets(ctx, [action = "ls", ...args]) {
+  const handler = SECRET_ACTIONS[action];
+  if (!handler) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai secrets [ls | set KEY | rm KEY | import FILE|- | get KEY | download]");
+  }
+  return handler(ctx, args);
+}
+
+/** One positional secret name; never echoes what was typed (it may be a pasted value). */
+function secretName(args, verb) {
+  if (args.length !== 1 || args[0].includes("=")) {
+    throw new CliError(EXIT.USAGE, `syndai secrets ${verb} takes one name; a value never goes on the command line.`, {
+      next: verb === "set" ? "syndai secrets set KEY   (then type the value, or pipe it on stdin)" : null,
+    });
+  }
+  if (!NAME.test(args[0])) {
+    throw new CliError(EXIT.USAGE, "A secret name is uppercase letters, digits and _ (like API_TOKEN).");
+  }
+  return args[0];
+}
+
+const SECRET_ACTIONS = {
+  async ls(ctx, args) {
+    if (args.length) throw new CliError(EXIT.USAGE, "Usage: syndai secrets [ls]");
+    const environment = await chosenEnvironment(ctx);
+    const project = await layeredProject(ctx);
+    const { secrets: rows } = await ctx.client.call("listSecrets");
+    const shown = rows
+      .filter((s) => s.environment === environment.slug && (!s.repository_id || s.repository_id === project?.id))
+      .map((s) => ({
+        key_name: s.key_name,
+        environment: s.environment,
+        scope: s.repository_id ? "project" : "shared",
+        repository_id: s.repository_id,
+        updated_at: s.updated_at,
+      }));
+    const width = Math.max(...shown.map((s) => s.key_name.length), 4);
+    const human = shown.length
+      ? [
+          `${"NAME".padEnd(width)}  SCOPE    UPDATED`,
+          ...shown.map((s) => `${s.key_name.padEnd(width)}  ${s.scope.padEnd(7)}  ${s.updated_at.slice(0, 10)}`),
+        ].join("\n")
+      : `No secrets in ${environment.slug} yet. Add one: syndai secrets set KEY`;
+    ctx.ui.result({ environment: environment.slug, project_id: project?.id ?? null, secrets: shown }, human);
+    return EXIT.OK;
+  },
+
+  async set(ctx, args) {
+    const { io, ui } = ctx;
+    const name = secretName(args, "set");
+    let value;
+    if (io.stdin.isTTY) {
+      if (!ui.interactive) {
+        throw new CliError(EXIT.USAGE, "Nobody can type the value here; pipe it on stdin.", {
+          next: `printf %s "$VALUE" | syndai secrets set ${name}`,
+        });
+      }
+      value = await askSecret(io, `Value for ${name} (hidden): `);
+    } else {
+      value = (await readAll(io.stdin)).replace(/\r?\n$/, "");
+    }
+    if (!value) throw new CliError(EXIT.USAGE, `No value for ${name}: type it at the prompt or pipe it on stdin.`);
+    const environment = await chosenEnvironment(ctx);
+    const project = await writeTarget(ctx);
+    const { secret } = await ctx.client.call("putSecret", {
+      params: { key_name: name },
+      body: { value, environment: environment.slug, ...(project ? { repository_id: project.id } : {}) },
+    });
+    ui.result(
+      { key_name: name, environment: environment.slug, scope: project ? "project" : "shared", repository_id: project?.id ?? null, updated_at: secret.updated_at },
+      `Set ${name} in ${environment.slug} (${scopeOf(project)}).`,
+    );
+    return EXIT.OK;
+  },
+
+  async rm(ctx, args) {
+    const { flags, io, ui } = ctx;
+    const name = secretName(args, "rm");
+    const environment = await chosenEnvironment(ctx);
+    const project = await writeTarget(ctx);
+    const where = `${environment.slug} (${scopeOf(project)})`;
+    if (!flags.yes) {
+      if (!ui.interactive) {
+        throw new CliError(EXIT.USAGE, "Removing a secret needs --yes when nobody can confirm it.", {
+          next: `syndai secrets rm ${name} --yes`,
+        });
+      }
+      const answer = await ask(io, `Remove ${name} from ${where}? [y/N] `);
+      if (!/^y/i.test(answer)) {
+        ui.result({ key_name: name, removed: false }, "Kept.");
+        return EXIT.OK;
+      }
+    }
+    await ctx.client.call("deleteSecret", {
+      params: { key_name: name },
+      query: { environment: environment.slug, repository_id: project?.id },
+    });
+    ui.result({ key_name: name, environment: environment.slug, removed: true }, `Removed ${name} from ${where}.`);
+    return EXIT.OK;
+  },
+
+  async import(ctx, args) {
+    const { io, ui } = ctx;
+    if (args.length !== 1) throw new CliError(EXIT.USAGE, "Usage: syndai secrets import FILE|-");
+    const [source] = args;
+    let text;
+    try {
+      text = source === "-" ? await readAll(io.stdin) : fs.readFileSync(path.resolve(io.cwd, source), "utf8");
+    } catch (err) {
+      throw new CliError(EXIT.USAGE, `Cannot read ${source} (${err.code ?? "unreadable"}).`);
+    }
+    const items = parseDotenv(text);
+    if (!items.length) throw new CliError(EXIT.USAGE, `${source} has no KEY=VALUE lines.`);
+    const environment = await chosenEnvironment(ctx);
+    const project = await writeTarget(ctx);
+    await ctx.client.call("importSecrets", {
+      body: { items, environment: environment.slug, ...(project ? { repository_id: project.id } : {}) },
+    });
+    const names = items.map((item) => item.key_name);
+    ui.result(
+      { environment: environment.slug, scope: project ? "project" : "shared", imported: names.length, names },
+      `Imported ${names.length} value${names.length === 1 ? "" : "s"} into ${environment.slug} (${scopeOf(project)}): ${names.join(", ")}.`,
+    );
+    return EXIT.OK;
+  },
+
+  async get(ctx, args) {
+    const { io, flags } = ctx;
+    const name = secretName(args, "get");
+    if (flags.json) throw new CliError(EXIT.USAGE, "JSON never carries a secret value; use --plain.");
+    if (!io.stdout.isTTY && !flags.plain) {
+      throw new CliError(EXIT.USAGE, "Not printing a secret value into a pipe or a file without --plain.", {
+        next: `syndai secrets get ${name} --plain`,
+      });
+    }
+    const { environment, values } = await resolveValues(ctx, [name]);
+    if (!(name in values)) throw new CliError(EXIT.FAILED, `${name} is not set in ${environment}.`, { next: "syndai secrets" });
+    // --plain: the exact bytes, for $(...) and pipes; a terminal gets a newline.
+    io.stdout.write(flags.plain ? values[name] : `${values[name]}\n`);
+    return EXIT.OK;
+  },
+
+  async download(ctx, args) {
+    const { io, flags, ui } = ctx;
+    if (args.length) throw new CliError(EXIT.USAGE, "Usage: syndai secrets download [-o FILE]");
+    if (!flags.output && (io.stdout.isTTY || flags.json)) {
+      throw new CliError(EXIT.USAGE, "Pass -o FILE: a terminal (or --json) never gets the values.", {
+        next: "syndai secrets download -o .env",
+      });
+    }
+    const { environment, values } = await resolveValues(ctx);
+    const text = serializeDotenv(values);
+    const names = Object.keys(values).sort();
+    if (!flags.output) {
+      io.stdout.write(text);
+      return EXIT.OK;
+    }
+    const file = path.resolve(io.cwd, flags.output);
+    writeFileAtomic(file, text, 0o600);
+    if (notIgnored(file)) {
+      ui.progress(ui.yellow(`Warning: ${flags.output} is not ignored by git; add it to .gitignore so it is never committed.`));
+    }
+    ui.result(
+      { file, environment, count: names.length, names },
+      `Wrote ${names.length} value${names.length === 1 ? "" : "s"} from ${environment} to ${file} (mode 600).`,
+    );
+    return EXIT.OK;
+  },
+};
+
+/** True only inside a git checkout that does not ignore `file` (outside one: false). */
+function notIgnored(file) {
+  try {
+    execFileSync("git", ["check-ignore", "-q", path.basename(file)], {
+      cwd: path.dirname(file),
+      stdio: "ignore",
+      timeout: 3000,
+    });
+    return false; // exit 0: ignored
+  } catch (err) {
+    return err.status === 1; // 1: not ignored; 128 (no repo) or no git: nothing to warn about
+  }
+}
+
+/**
+ * The chosen environment's merged values (`names` narrows them). A production environment
+ * the server refuses (no approved step-up) gets one browser step-up on a terminal, whose grant
+ * rides only this command's retry.
+ */
+async function resolveValues(ctx, names) {
+  const slug = chosenSlug(ctx);
+  const project = await layeredProject(ctx);
+  const body = {
+    ...(slug ? { environment: slug } : {}),
+    ...(project ? { repository_id: project.id } : {}),
+    ...(names ? { names } : {}),
+  };
+  try {
+    return await ctx.client.call("resolveSecrets", { body });
+  } catch (err) {
+    if (!(err instanceof ApiError && err.code === "PRODUCTION_STEP_UP_REQUIRED")) throw err;
+    const grant = await productionStepUp(ctx);
+    if (!grant) throw err;
+    return ctx.client.call("resolveSecrets", { body: { ...body, production_grant: grant } });
+  }
+}
+
+// --- syndai run --------------------------------------------------------------------------
+
+/** `syndai run [--env E] [--] <command>...`: the child alone gets the values; its exit code is ours. */
+export async function run(ctx, command) {
+  const { io, ui } = ctx;
+  if (!command.length) throw new CliError(EXIT.USAGE, "Usage: syndai run [--env E] [--] <command> [args...]");
+  const { environment, values } = await resolveValues(ctx);
+  const count = Object.keys(values).length;
+  ui.progress(ui.dim(`Injected ${count} value${count === 1 ? "" : "s"} from ${environment}`));
+  let exit;
+  try {
+    exit = await io.exec(command[0], command.slice(1), { ...io.env, ...values });
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      ui.progress(`${ui.red("error:")} command not found: ${command[0]}`);
+      return 127;
+    }
+    throw err;
+  }
+  if (exit.signal) return 128 + (constants.signals[exit.signal] ?? 0);
+  return exit.code ?? EXIT.FAILED;
+}

package/src/ui.js

@@ -59,6 +59,56 @@ export async function ask(io, question) {
   }
 }
 
+/**
+ * Ask for a secret without echoing it, in raw mode: Enter ends it, Ctrl-C interrupts, Backspace
+ * edits, an escape sequence (an arrow key) is dropped. A terminal that cannot hide typing is
+ * refused rather than echoing, and so is a pasted multi-line value (it would be cut at its
+ * first line): both go through stdin instead.
+ */
+export async function askSecret(io, question) {
+  const { stdin } = io;
+  if (typeof stdin.setRawMode !== "function") {
+    throw new CliError(EXIT.USAGE, "This terminal can't hide what you type; pipe the value on stdin instead.");
+  }
+  if (io.signal.aborted) throw interrupted();
+  io.stderr.write(question);
+  stdin.setRawMode(true);
+  stdin.setEncoding("utf8");
+  stdin.resume();
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const finish = (err) => {
+      stdin.removeListener("data", onData);
+      io.signal.removeEventListener("abort", onAbort);
+      stdin.setRawMode(false);
+      stdin.pause();
+      io.stderr.write("\n");
+      if (err) reject(err);
+      else resolve(value);
+    };
+    const onAbort = () => finish(interrupted());
+    const onData = (chunk) => {
+      // An escape sequence (ESC [ ... final byte) is a key like an arrow, never part of a value.
+      const keys = chunk.replace(/\u001b\[[0-9;?]*[@-~]|\u001b./g, "");
+      for (let i = 0; i < keys.length; i++) {
+        const ch = keys[i];
+        if (ch === "\r" || ch === "\n") {
+          if (keys.slice(i + 1).replace(/^[\r\n]+/, "")) {
+            return finish(new CliError(EXIT.USAGE, "That value has more than one line; pipe it on stdin instead."));
+          }
+          return finish();
+        }
+        if (ch === "\u0003") return finish(interrupted());
+        if (ch === "\u0004") return finish(value ? null : new CliError(EXIT.NEEDS_YOU, "No answer: input closed."));
+        if (ch === "\u007f" || ch === "\b") value = Array.from(value).slice(0, -1).join("");
+        else value += ch;
+      }
+    };
+    stdin.on("data", onData);
+    io.signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
 /** Release stdin so the process can exit (called once a command is done). */
 export function closeInput(io) {
   readers.get(io.stdin)?.rl.close();