@ricsam/r5dctl 0.0.20 → 0.0.22

package/README.md

@@ -49,6 +49,9 @@ r5dctl delete project <namespace/name|id>
 
 r5dctl -p <project> get branches
 r5dctl -p <project> describe branch <branch>
+r5dctl -p <project> -b <branch> get envs
+r5dctl -p <project> -b <branch> set envs --from-env-file ~/.env --only-missing
+r5dctl -p <project> -b <branch> set envs -e backend/API_KEY=value --description "API credential"
 r5dctl -p <project> get sessions --branch <branch>
 r5dctl -p <project> create session -b <branch> --name "Spec session"
 r5dctl describe session <session-id>
@@ -66,6 +69,8 @@ r5dctl -s <session-id> apply-required-envs -e backend/KEY=value -e frontend/KEY=
 
 ```
 
+`get envs` reports names and whether values are set, but never prints the values. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Dotenv imports target backend envs by default; use `--target frontend` when needed. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
+
 Conversation output is human-readable by default and excludes both the system prompt and tool definitions. `--raw` keeps the transcript layout but renders structured message and tool parts as JSON, `--tools` includes the provider-shaped tool definitions, and `--system` includes system prompt messages. The global `--json` flag remains separate and prints the complete API response envelope.
 
 When available, conversation rendering uses the newest complete persisted model-request snapshot on the active conversation branch, so its mode, tier, model, thinking mode, tools, and messages reflect the request that actually ran. Legacy or empty sessions without snapshots fall back to reconstruction from the latest conversation context.

package/dist/cjs/cli.cjs

@@ -36,9 +36,12 @@ __export(cli_exports, {
   parseEnvFlags: () => parseEnvFlags,
   parseGlobalArgs: () => parseGlobalArgs,
   parsePromptArgs: () => parsePromptArgs,
+  parseSetEnvArgs: () => parseSetEnvArgs,
+  readDotenvFile: () => readDotenvFile,
   renderConversationResponse: () => renderConversationResponse,
   resolveCommandExecution: () => resolveCommandExecution,
-  runR5dctlCli: () => runR5dctlCli
+  runR5dctlCli: () => runR5dctlCli,
+  summarizeEnvData: () => summarizeEnvData
 });
 module.exports = __toCommonJS(cli_exports);
 var import_node_fs = __toESM(require("node:fs"), 1);
@@ -46,6 +49,7 @@ var import_node_os = __toESM(require("node:os"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_node_child_process = require("node:child_process");
 var import_promises = require("node:timers/promises");
+var import_dotenv = require("dotenv");
 var import_r5d_api = require("@ricsam/r5d-api");
 const CHAT_MODES = /* @__PURE__ */ new Set([
   "ask",
@@ -103,6 +107,21 @@ const SHARED_HELP_ENTRIES = [
   { section: "projects", usage: "delete project <namespace/name|id>", description: "Delete a project." },
   { section: "branches", usage: "-p <project> get branches", description: "List branches for a project." },
   { section: "branches", usage: "-p <project> describe branch <branch>", description: "Show branch URLs and sessions." },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> get envs",
+    description: "List declared envs and whether each has a value, without revealing values."
+  },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--target <backend|frontend>] [--only-missing]",
+    description: "Securely import branch envs from a dotenv file without putting values in command arguments."
+  },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> set envs -e backend/KEY=value [--description <text>] [--only-missing]",
+    description: "Set one or more branch envs directly."
+  },
   {
     section: "sessions",
     usage: "-p <project> get sessions [--branch <branch>]",
@@ -151,11 +170,12 @@ const SHARED_HELP_ENTRIES = [
   { section: "merges", usage: "-p <project> continue-merge <target-branch>", description: "Commit a resolved merge." },
   { section: "merges", usage: "-p <project> abort-merge <target-branch>", description: "Abort an in-progress merge." }
 ];
-const HELP_SECTION_ORDER = ["auth", "projects", "branches", "sessions", "agents", "merges"];
+const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "agents", "merges"];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
+  envs: "Environment variables",
   sessions: "Sessions",
   agents: "Agents",
   merges: "Merges"
@@ -501,10 +521,117 @@ function validateEnvAssignment(value) {
   }
   const target = assignment.slice(0, slashIndex);
   const key = assignment.slice(slashIndex + 1);
-  if (target !== "backend" && target !== "frontend" || key.length === 0) {
+  if (target !== "backend" && target !== "frontend" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
     throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
   }
 }
+function parseEnvAssignment(value) {
+  validateEnvAssignment(value);
+  const equalsIndex = value.indexOf("=");
+  const slashIndex = value.indexOf("/");
+  return {
+    target: value.slice(0, slashIndex),
+    name: value.slice(slashIndex + 1, equalsIndex),
+    value: value.slice(equalsIndex + 1)
+  };
+}
+function parseSetEnvArgs(args) {
+  const parsed = {
+    assignments: [],
+    target: "backend",
+    onlyMissing: false,
+    includeEmpty: false
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    if (arg === "-e" || arg === "--env") {
+      const value = requireValue(args[index + 1], `Missing value for ${arg}`);
+      validateEnvAssignment(value);
+      parsed.assignments.push(value);
+      index += 1;
+      continue;
+    }
+    const inlineEnv = parseLongOptionWithEquals(arg, "--env");
+    if (inlineEnv !== void 0) {
+      validateEnvAssignment(inlineEnv);
+      parsed.assignments.push(inlineEnv);
+      continue;
+    }
+    if (arg === "--from-env-file") {
+      parsed.fromEnvFile = requireValue(args[index + 1], "Missing value for --from-env-file");
+      index += 1;
+      continue;
+    }
+    const inlineFile = parseLongOptionWithEquals(arg, "--from-env-file");
+    if (inlineFile !== void 0) {
+      parsed.fromEnvFile = requireValue(inlineFile, "Missing value for --from-env-file");
+      continue;
+    }
+    if (arg === "--target") {
+      const target = requireValue(args[index + 1], "Missing value for --target");
+      if (target !== "backend" && target !== "frontend") {
+        throw new Error("Invalid --target. Expected backend or frontend");
+      }
+      parsed.target = target;
+      index += 1;
+      continue;
+    }
+    const inlineTarget = parseLongOptionWithEquals(arg, "--target");
+    if (inlineTarget !== void 0) {
+      if (inlineTarget !== "backend" && inlineTarget !== "frontend") {
+        throw new Error("Invalid --target. Expected backend or frontend");
+      }
+      parsed.target = inlineTarget;
+      continue;
+    }
+    if (arg === "--description") {
+      parsed.description = requireValue(args[index + 1], "Missing value for --description");
+      index += 1;
+      continue;
+    }
+    const inlineDescription = parseLongOptionWithEquals(arg, "--description");
+    if (inlineDescription !== void 0) {
+      parsed.description = requireValue(inlineDescription, "Missing value for --description");
+      continue;
+    }
+    if (arg === "--optional") {
+      if (parsed.optional === false) throw new Error("Use only one of --optional or --required");
+      parsed.optional = true;
+      continue;
+    }
+    if (arg === "--required") {
+      if (parsed.optional === true) throw new Error("Use only one of --optional or --required");
+      parsed.optional = false;
+      continue;
+    }
+    if (arg === "--only-missing") {
+      parsed.onlyMissing = true;
+      continue;
+    }
+    if (arg === "--include-empty") {
+      parsed.includeEmpty = true;
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown set envs flag: ${arg}` : `Unexpected set envs value: ${arg}`);
+  }
+  if (parsed.assignments.length > 0 && parsed.fromEnvFile) {
+    throw new Error("Use either -e/--env or --from-env-file, not both");
+  }
+  if (parsed.assignments.length === 0 && !parsed.fromEnvFile) {
+    throw new Error("Provide at least one -e/--env assignment or --from-env-file <path>");
+  }
+  return parsed;
+}
+function resolveLocalPath(filePath) {
+  if (filePath === "~") return import_node_os.default.homedir();
+  if (filePath.startsWith("~/")) return import_node_path.default.join(import_node_os.default.homedir(), filePath.slice(2));
+  return import_node_path.default.resolve(filePath);
+}
+function readDotenvFile(filePath) {
+  const resolvedPath = resolveLocalPath(filePath);
+  return (0, import_dotenv.parse)(import_node_fs.default.readFileSync(resolvedPath));
+}
 function parseEnvFlags(args) {
   const envs = [];
   for (let i = 0; i < args.length; i += 1) {
@@ -739,6 +866,108 @@ function renderSessionList(sessions) {
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
+function summarizeEnvData(data) {
+  const summary = {};
+  for (const target of ["backend", "frontend"]) {
+    const entries = data[target];
+    if (!entries) continue;
+    summary[target] = Object.fromEntries(
+      Object.entries(entries).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
+        name,
+        {
+          optional: env.optional ?? false,
+          description: env.description,
+          hasValue: env.value !== null
+        }
+      ])
+    );
+  }
+  return summary;
+}
+function renderEnvSummary(data) {
+  const lines = [];
+  for (const target of ["backend", "frontend"]) {
+    const entries = Object.entries(data[target] ?? {});
+    if (entries.length === 0) continue;
+    if (lines.length > 0) lines.push("");
+    lines.push(`${target}:`);
+    for (const [name, env] of entries) {
+      lines.push(`  ${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
+    }
+  }
+  return lines.length > 0 ? `${lines.join("\n")}
+` : "No environment variables declared.\n";
+}
+function renderEnvSetResult(result) {
+  const lines = [
+    `Updated ${result.updated.length} environment variable${result.updated.length === 1 ? "" : "s"} for ${result.project}/${result.branch}.`
+  ];
+  if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
+  if (result.skippedEmpty.length > 0) lines.push(`Skipped ${result.skippedEmpty.length} empty value(s).`);
+  if (result.updated.length > 0) {
+    lines.push(...result.updated.map(({ target, name }) => `  ${target}/${name}`));
+  }
+  return `${lines.join("\n")}
+`;
+}
+async function setBranchEnvs(client, projectRef, branchName, args) {
+  const options = parseSetEnvArgs(args);
+  const project = await client.projects.describe(projectRef);
+  const current = await client.projects.env.get(project.id, branchName);
+  const assignments = options.fromEnvFile ? Object.entries(readDotenvFile(options.fromEnvFile)).map(([name, value]) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      throw new Error(`Invalid environment variable name in dotenv file: ${name}`);
+    }
+    return { target: options.target, name, value };
+  }) : options.assignments.map(parseEnvAssignment);
+  const uniqueAssignments = /* @__PURE__ */ new Map();
+  for (const assignment of assignments) uniqueAssignments.set(`${assignment.target}/${assignment.name}`, assignment);
+  const update = {};
+  const result = {
+    success: true,
+    project: project.path,
+    branch: branchName,
+    updated: [],
+    skippedExisting: [],
+    skippedEmpty: []
+  };
+  const missingDescriptions = [];
+  const importedDescription = options.fromEnvFile ? `Imported from ${import_node_path.default.basename(options.fromEnvFile)}.` : void 0;
+  for (const assignment of uniqueAssignments.values()) {
+    const identity = { target: assignment.target, name: assignment.name };
+    if (!options.includeEmpty && assignment.value.length === 0) {
+      result.skippedEmpty.push(identity);
+      continue;
+    }
+    const existing = current[assignment.target]?.[assignment.name];
+    if (options.onlyMissing && existing?.value !== null && existing?.value !== void 0) {
+      result.skippedExisting.push(identity);
+      continue;
+    }
+    const description = options.description ?? existing?.description ?? importedDescription;
+    if (!description) {
+      missingDescriptions.push(identity);
+      continue;
+    }
+    const targetUpdate = update[assignment.target] ??= {};
+    const optional = options.optional ?? existing?.optional;
+    targetUpdate[assignment.name] = {
+      description,
+      value: assignment.value,
+      ...optional === void 0 ? {} : { optional }
+    };
+    result.updated.push(identity);
+  }
+  if (missingDescriptions.length > 0) {
+    throw new Error(
+      `--description is required when declaring new envs with -e: ${missingDescriptions.map(({ target, name }) => `${target}/${name}`).join(", ")}`
+    );
+  }
+  if (result.updated.length > 0) {
+    await client.projects.env.update(project.id, branchName, update);
+  }
+  return result;
+}
 function renderAgentStart(agent) {
   return [
     `Agent: ${agent.sessionId}`,
@@ -940,6 +1169,24 @@ Sessions: ${result.sessions.length}
 `);
     return;
   }
+  if (first === "get" && second === "envs") {
+    const projectRef = requireValue(args[2], "Missing project reference");
+    const branchName = requireValue(args[3], "Missing branch name");
+    const project = await client.projects.describe(projectRef);
+    const envs = summarizeEnvData(await client.projects.env.get(project.id, branchName));
+    write({ project: project.path, branch: branchName, envs }, renderEnvSummary(envs));
+    return;
+  }
+  if (first === "set" && second === "envs") {
+    const result = await setBranchEnvs(
+      client,
+      requireValue(args[2], "Missing project reference"),
+      requireValue(args[3], "Missing branch name"),
+      args.slice(4)
+    );
+    write(result, renderEnvSetResult(result));
+    return;
+  }
   if (first === "projects" && second === "sessions" && third === "list" || first === "get" && second === "sessions") {
     const offset = first === "get" ? 2 : 3;
     const projectRef = requireValue(args[offset], "Missing project reference");
@@ -1177,8 +1424,36 @@ function resolveCommandExecution(options, rest) {
         pluginArgs
       };
     }
+    if (target === "envs") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `get envs`");
+      }
+      if (!options.branch) {
+        throw new Error("--branch/-b is required for `get envs`");
+      }
+      return {
+        kind: "plugin",
+        pluginArgs: ["get", "envs", options.project, options.branch]
+      };
+    }
     throw new Error("Unknown get command");
   }
+  if (command === "set") {
+    const target = commandArgs[0];
+    if (target !== "envs") {
+      throw new Error("Unknown set command");
+    }
+    if (!options.project) {
+      throw new Error("--project/-p is required for `set envs`");
+    }
+    if (!options.branch) {
+      throw new Error("--branch/-b is required for `set envs`");
+    }
+    return {
+      kind: "plugin",
+      pluginArgs: ["set", "envs", options.project, options.branch, ...commandArgs.slice(1)]
+    };
+  }
   if (command === "describe") {
     const target = commandArgs[0];
     if (target === "project") {
@@ -1487,7 +1762,10 @@ async function main(argv = process.argv.slice(2)) {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parseSetEnvArgs,
+  readDotenvFile,
   renderConversationResponse,
   resolveCommandExecution,
-  runR5dctlCli
+  runR5dctlCli,
+  summarizeEnvData
 });

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "type": "commonjs"
 }

package/dist/mjs/cli.mjs

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
+import { parse as parseDotenv } from "dotenv";
 import {
   R5dctlApiError,
   R5dctlClient
@@ -63,6 +64,21 @@ const SHARED_HELP_ENTRIES = [
   { section: "projects", usage: "delete project <namespace/name|id>", description: "Delete a project." },
   { section: "branches", usage: "-p <project> get branches", description: "List branches for a project." },
   { section: "branches", usage: "-p <project> describe branch <branch>", description: "Show branch URLs and sessions." },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> get envs",
+    description: "List declared envs and whether each has a value, without revealing values."
+  },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--target <backend|frontend>] [--only-missing]",
+    description: "Securely import branch envs from a dotenv file without putting values in command arguments."
+  },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> set envs -e backend/KEY=value [--description <text>] [--only-missing]",
+    description: "Set one or more branch envs directly."
+  },
   {
     section: "sessions",
     usage: "-p <project> get sessions [--branch <branch>]",
@@ -111,11 +127,12 @@ const SHARED_HELP_ENTRIES = [
   { section: "merges", usage: "-p <project> continue-merge <target-branch>", description: "Commit a resolved merge." },
   { section: "merges", usage: "-p <project> abort-merge <target-branch>", description: "Abort an in-progress merge." }
 ];
-const HELP_SECTION_ORDER = ["auth", "projects", "branches", "sessions", "agents", "merges"];
+const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "agents", "merges"];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
+  envs: "Environment variables",
   sessions: "Sessions",
   agents: "Agents",
   merges: "Merges"
@@ -461,10 +478,117 @@ function validateEnvAssignment(value) {
   }
   const target = assignment.slice(0, slashIndex);
   const key = assignment.slice(slashIndex + 1);
-  if (target !== "backend" && target !== "frontend" || key.length === 0) {
+  if (target !== "backend" && target !== "frontend" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
     throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
   }
 }
+function parseEnvAssignment(value) {
+  validateEnvAssignment(value);
+  const equalsIndex = value.indexOf("=");
+  const slashIndex = value.indexOf("/");
+  return {
+    target: value.slice(0, slashIndex),
+    name: value.slice(slashIndex + 1, equalsIndex),
+    value: value.slice(equalsIndex + 1)
+  };
+}
+function parseSetEnvArgs(args) {
+  const parsed = {
+    assignments: [],
+    target: "backend",
+    onlyMissing: false,
+    includeEmpty: false
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    if (arg === "-e" || arg === "--env") {
+      const value = requireValue(args[index + 1], `Missing value for ${arg}`);
+      validateEnvAssignment(value);
+      parsed.assignments.push(value);
+      index += 1;
+      continue;
+    }
+    const inlineEnv = parseLongOptionWithEquals(arg, "--env");
+    if (inlineEnv !== void 0) {
+      validateEnvAssignment(inlineEnv);
+      parsed.assignments.push(inlineEnv);
+      continue;
+    }
+    if (arg === "--from-env-file") {
+      parsed.fromEnvFile = requireValue(args[index + 1], "Missing value for --from-env-file");
+      index += 1;
+      continue;
+    }
+    const inlineFile = parseLongOptionWithEquals(arg, "--from-env-file");
+    if (inlineFile !== void 0) {
+      parsed.fromEnvFile = requireValue(inlineFile, "Missing value for --from-env-file");
+      continue;
+    }
+    if (arg === "--target") {
+      const target = requireValue(args[index + 1], "Missing value for --target");
+      if (target !== "backend" && target !== "frontend") {
+        throw new Error("Invalid --target. Expected backend or frontend");
+      }
+      parsed.target = target;
+      index += 1;
+      continue;
+    }
+    const inlineTarget = parseLongOptionWithEquals(arg, "--target");
+    if (inlineTarget !== void 0) {
+      if (inlineTarget !== "backend" && inlineTarget !== "frontend") {
+        throw new Error("Invalid --target. Expected backend or frontend");
+      }
+      parsed.target = inlineTarget;
+      continue;
+    }
+    if (arg === "--description") {
+      parsed.description = requireValue(args[index + 1], "Missing value for --description");
+      index += 1;
+      continue;
+    }
+    const inlineDescription = parseLongOptionWithEquals(arg, "--description");
+    if (inlineDescription !== void 0) {
+      parsed.description = requireValue(inlineDescription, "Missing value for --description");
+      continue;
+    }
+    if (arg === "--optional") {
+      if (parsed.optional === false) throw new Error("Use only one of --optional or --required");
+      parsed.optional = true;
+      continue;
+    }
+    if (arg === "--required") {
+      if (parsed.optional === true) throw new Error("Use only one of --optional or --required");
+      parsed.optional = false;
+      continue;
+    }
+    if (arg === "--only-missing") {
+      parsed.onlyMissing = true;
+      continue;
+    }
+    if (arg === "--include-empty") {
+      parsed.includeEmpty = true;
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown set envs flag: ${arg}` : `Unexpected set envs value: ${arg}`);
+  }
+  if (parsed.assignments.length > 0 && parsed.fromEnvFile) {
+    throw new Error("Use either -e/--env or --from-env-file, not both");
+  }
+  if (parsed.assignments.length === 0 && !parsed.fromEnvFile) {
+    throw new Error("Provide at least one -e/--env assignment or --from-env-file <path>");
+  }
+  return parsed;
+}
+function resolveLocalPath(filePath) {
+  if (filePath === "~") return os.homedir();
+  if (filePath.startsWith("~/")) return path.join(os.homedir(), filePath.slice(2));
+  return path.resolve(filePath);
+}
+function readDotenvFile(filePath) {
+  const resolvedPath = resolveLocalPath(filePath);
+  return parseDotenv(fs.readFileSync(resolvedPath));
+}
 function parseEnvFlags(args) {
   const envs = [];
   for (let i = 0; i < args.length; i += 1) {
@@ -699,6 +823,108 @@ function renderSessionList(sessions) {
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
+function summarizeEnvData(data) {
+  const summary = {};
+  for (const target of ["backend", "frontend"]) {
+    const entries = data[target];
+    if (!entries) continue;
+    summary[target] = Object.fromEntries(
+      Object.entries(entries).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
+        name,
+        {
+          optional: env.optional ?? false,
+          description: env.description,
+          hasValue: env.value !== null
+        }
+      ])
+    );
+  }
+  return summary;
+}
+function renderEnvSummary(data) {
+  const lines = [];
+  for (const target of ["backend", "frontend"]) {
+    const entries = Object.entries(data[target] ?? {});
+    if (entries.length === 0) continue;
+    if (lines.length > 0) lines.push("");
+    lines.push(`${target}:`);
+    for (const [name, env] of entries) {
+      lines.push(`  ${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
+    }
+  }
+  return lines.length > 0 ? `${lines.join("\n")}
+` : "No environment variables declared.\n";
+}
+function renderEnvSetResult(result) {
+  const lines = [
+    `Updated ${result.updated.length} environment variable${result.updated.length === 1 ? "" : "s"} for ${result.project}/${result.branch}.`
+  ];
+  if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
+  if (result.skippedEmpty.length > 0) lines.push(`Skipped ${result.skippedEmpty.length} empty value(s).`);
+  if (result.updated.length > 0) {
+    lines.push(...result.updated.map(({ target, name }) => `  ${target}/${name}`));
+  }
+  return `${lines.join("\n")}
+`;
+}
+async function setBranchEnvs(client, projectRef, branchName, args) {
+  const options = parseSetEnvArgs(args);
+  const project = await client.projects.describe(projectRef);
+  const current = await client.projects.env.get(project.id, branchName);
+  const assignments = options.fromEnvFile ? Object.entries(readDotenvFile(options.fromEnvFile)).map(([name, value]) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      throw new Error(`Invalid environment variable name in dotenv file: ${name}`);
+    }
+    return { target: options.target, name, value };
+  }) : options.assignments.map(parseEnvAssignment);
+  const uniqueAssignments = /* @__PURE__ */ new Map();
+  for (const assignment of assignments) uniqueAssignments.set(`${assignment.target}/${assignment.name}`, assignment);
+  const update = {};
+  const result = {
+    success: true,
+    project: project.path,
+    branch: branchName,
+    updated: [],
+    skippedExisting: [],
+    skippedEmpty: []
+  };
+  const missingDescriptions = [];
+  const importedDescription = options.fromEnvFile ? `Imported from ${path.basename(options.fromEnvFile)}.` : void 0;
+  for (const assignment of uniqueAssignments.values()) {
+    const identity = { target: assignment.target, name: assignment.name };
+    if (!options.includeEmpty && assignment.value.length === 0) {
+      result.skippedEmpty.push(identity);
+      continue;
+    }
+    const existing = current[assignment.target]?.[assignment.name];
+    if (options.onlyMissing && existing?.value !== null && existing?.value !== void 0) {
+      result.skippedExisting.push(identity);
+      continue;
+    }
+    const description = options.description ?? existing?.description ?? importedDescription;
+    if (!description) {
+      missingDescriptions.push(identity);
+      continue;
+    }
+    const targetUpdate = update[assignment.target] ??= {};
+    const optional = options.optional ?? existing?.optional;
+    targetUpdate[assignment.name] = {
+      description,
+      value: assignment.value,
+      ...optional === void 0 ? {} : { optional }
+    };
+    result.updated.push(identity);
+  }
+  if (missingDescriptions.length > 0) {
+    throw new Error(
+      `--description is required when declaring new envs with -e: ${missingDescriptions.map(({ target, name }) => `${target}/${name}`).join(", ")}`
+    );
+  }
+  if (result.updated.length > 0) {
+    await client.projects.env.update(project.id, branchName, update);
+  }
+  return result;
+}
 function renderAgentStart(agent) {
   return [
     `Agent: ${agent.sessionId}`,
@@ -900,6 +1126,24 @@ Sessions: ${result.sessions.length}
 `);
     return;
   }
+  if (first === "get" && second === "envs") {
+    const projectRef = requireValue(args[2], "Missing project reference");
+    const branchName = requireValue(args[3], "Missing branch name");
+    const project = await client.projects.describe(projectRef);
+    const envs = summarizeEnvData(await client.projects.env.get(project.id, branchName));
+    write({ project: project.path, branch: branchName, envs }, renderEnvSummary(envs));
+    return;
+  }
+  if (first === "set" && second === "envs") {
+    const result = await setBranchEnvs(
+      client,
+      requireValue(args[2], "Missing project reference"),
+      requireValue(args[3], "Missing branch name"),
+      args.slice(4)
+    );
+    write(result, renderEnvSetResult(result));
+    return;
+  }
   if (first === "projects" && second === "sessions" && third === "list" || first === "get" && second === "sessions") {
     const offset = first === "get" ? 2 : 3;
     const projectRef = requireValue(args[offset], "Missing project reference");
@@ -1137,8 +1381,36 @@ function resolveCommandExecution(options, rest) {
         pluginArgs
       };
     }
+    if (target === "envs") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `get envs`");
+      }
+      if (!options.branch) {
+        throw new Error("--branch/-b is required for `get envs`");
+      }
+      return {
+        kind: "plugin",
+        pluginArgs: ["get", "envs", options.project, options.branch]
+      };
+    }
     throw new Error("Unknown get command");
   }
+  if (command === "set") {
+    const target = commandArgs[0];
+    if (target !== "envs") {
+      throw new Error("Unknown set command");
+    }
+    if (!options.project) {
+      throw new Error("--project/-p is required for `set envs`");
+    }
+    if (!options.branch) {
+      throw new Error("--branch/-b is required for `set envs`");
+    }
+    return {
+      kind: "plugin",
+      pluginArgs: ["set", "envs", options.project, options.branch, ...commandArgs.slice(1)]
+    };
+  }
   if (command === "describe") {
     const target = commandArgs[0];
     if (target === "project") {
@@ -1446,7 +1718,10 @@ export {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parseSetEnvArgs,
+  readDotenvFile,
   renderConversationResponse,
   resolveCommandExecution,
-  runR5dctlCli
+  runR5dctlCli,
+  summarizeEnvData
 };

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "type": "module"
 }

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlEnvData, type R5dctlEnvTarget, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -38,12 +38,29 @@ export declare function parseGlobalArgs(argv: string[]): {
     rest: string[];
 };
 export declare function parseAnswerFlags(args: string[]): string[];
+export type SetEnvOptions = {
+    assignments: string[];
+    fromEnvFile?: string;
+    target: R5dctlEnvTarget;
+    description?: string;
+    optional?: boolean;
+    onlyMissing: boolean;
+    includeEmpty: boolean;
+};
+export declare function parseSetEnvArgs(args: string[]): SetEnvOptions;
+export declare function readDotenvFile(filePath: string): Record<string, string>;
 export declare function parseEnvFlags(args: string[]): string[];
 export declare function parsePromptArgs(args: string[]): {
     mode: ChatMode;
     model: ModelTier;
     message: string;
 };
+export type EnvSummaryData = Partial<Record<R5dctlEnvTarget, Record<string, {
+    optional: boolean;
+    description: string;
+    hasValue: boolean;
+}>>>;
+export declare function summarizeEnvData(data: R5dctlEnvData): EnvSummaryData;
 export declare function parseConversationRenderArgs(args: string[]): ConversationRenderOptions;
 export declare function renderConversationResponse(read: R5dctlConversationResponse): string;
 export declare function resolveCommandExecution(options: GlobalOptions, rest: string[]): CommandExecutionPlan;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "type": "module",
   "main": "./dist/cjs/cli.cjs",
   "module": "./dist/mjs/cli.mjs",
@@ -26,7 +26,8 @@
     "r5dctl": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.20"
+    "@ricsam/r5d-api": "^0.0.22",
+    "dotenv": "^17"
   },
   "files": [
     "dist",