akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/commands/env/env-cli.js

@@ -10,28 +10,28 @@
  * copy.
  *
  * `akm env` manages whole `.env` files under each stash's env/ directory.
- * Values are NEVER written to stdout or structured output — only key NAMES and
- * start-of-line comments are surfaced. akm does not manage individual entries;
+ * Values and comment text are NEVER written to stdout or structured output —
+ * only key NAMES are surfaced (comments routinely contain commented-out
+ * credentials). akm does not manage individual entries;
  * you edit the `.env` file yourself and akm loads it. Replaced the deprecated
  * `vault` type (removed in 0.9.0).
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { defineCommand } from "citty";
-import { getStringArg, hasSubcommand } from "../../cli/parse-args.js";
-import { output, runWithJsonErrors } from "../../cli/shared.js";
+import { getStringArg } from "../../cli/parse-args.js";
+import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { deriveCanonicalAssetName, resolveAssetPathFromName } from "../../core/asset/asset-spec.js";
 import { isWithin, writeFileAtomic } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { findEnvSource, makeEnvRef, parseEnvRef, resolveEnvPath } from "../../core/env-secret-ref.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
-import { appendEvent } from "../../core/events.js";
 import { isQuiet } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { getHyphenatedArg, parseFlagValue } from "../../output/context.js";
+import { parseFlagValue } from "../../output/context.js";
 import { readStdin } from "../../runtime.js";
+import { buildChildEnv } from "./child-env.js";
 /**
  * Walk each stash's env files and return one entry per `.env` file, using the
  * env asset spec's canonical-name logic (e.g. `env/team/prod.env` →
@@ -69,16 +69,14 @@ function listEnvsRecursive(listKeysFn) {
     }
     return result;
 }
-const envListCommand = defineCommand({
+const envListCommand = defineJsonCommand({
     meta: { name: "list", description: "List all env files across all stashes with their key names (no values)" },
-    run() {
-        return runWithJsonErrors(async () => {
-            const { listKeys } = await import("./env.js");
-            output("env-list", { envs: listEnvsRecursive(listKeys) });
-        });
+    async run() {
+        const { listKeys } = await import("./env.js");
+        output("env-list", { envs: listEnvsRecursive(listKeys) });
     },
 });
-const envCreateCommand = defineCommand({
+const envCreateCommand = defineJsonCommand({
     meta: {
         name: "create",
         description: "Create an env file (empty by default; seed an existing `.env` with --from-file or --from-stdin). No-op if it already exists and no source is given.",
@@ -101,58 +99,56 @@ const envCreateCommand = defineCommand({
             default: false,
         },
     },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const { createEnv, writeEnv } = await import("./env.js");
-            // `create` always targets env/, never the frozen vaults/ copy.
-            const parsed = parseEnvRef(args.name);
-            // `name` is flat; subdirectory placement is `--path`'s job.
-            assertFlatAssetName(parsed.name);
-            parsed.name = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), parsed.name);
-            const source = findEnvSource(parsed.origin);
-            const envRoot = path.join(source.path, "env");
-            const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-            if (!isWithin(absPath, envRoot)) {
-                throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-            }
-            const fromFile = getHyphenatedArg(args, "from-file");
-            const fromStdin = getHyphenatedArg(args, "from-stdin") === true;
-            if (fromFile !== undefined && fromStdin) {
-                throw new UsageError("Pass only one of --from-file or --from-stdin.", "INVALID_FLAG_VALUE");
+    async run({ args }) {
+        const { createEnv, writeEnv } = await import("./env.js");
+        // `create` always targets env/, never the frozen vaults/ copy.
+        const parsed = parseEnvRef(args.name);
+        // `name` is flat; subdirectory placement is `--path`'s job.
+        assertFlatAssetName(parsed.name);
+        parsed.name = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), parsed.name);
+        const source = findEnvSource(parsed.origin);
+        const envRoot = path.join(source.path, "env");
+        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+        if (!isWithin(absPath, envRoot)) {
+            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+        }
+        const fromFile = args["from-file"];
+        const fromStdin = args["from-stdin"] === true;
+        if (fromFile !== undefined && fromStdin) {
+            throw new UsageError("Pass only one of --from-file or --from-stdin.", "INVALID_FLAG_VALUE");
+        }
+        if (fromFile !== undefined || fromStdin) {
+            // Ingest path: never silently clobber an existing env file.
+            if (fs.existsSync(absPath)) {
+                throw new UsageError(`Env "${makeEnvRef(parsed.name, source)}" already exists. Remove it first (\`akm env remove\`) or edit the file directly.`, "RESOURCE_ALREADY_EXISTS");
             }
-            if (fromFile !== undefined || fromStdin) {
-                // Ingest path: never silently clobber an existing env file.
-                if (fs.existsSync(absPath)) {
-                    throw new UsageError(`Env "${makeEnvRef(parsed.name, source)}" already exists. Remove it first (\`akm env remove\`) or edit the file directly.`, "RESOURCE_ALREADY_EXISTS");
-                }
-                let content;
-                if (fromFile !== undefined) {
-                    if (!fs.existsSync(fromFile)) {
-                        throw new NotFoundError(`Source file not found: ${fromFile}`, "FILE_NOT_FOUND");
-                    }
-                    content = fs.readFileSync(fromFile, "utf8");
-                }
-                else {
-                    const MAX_ENV_BYTES = 1024 * 1024; // 1 MB
-                    const buf = await readStdin(MAX_ENV_BYTES, () => new UsageError("Env file exceeds 1 MB limit.", "INVALID_FLAG_VALUE"));
-                    content = buf.toString("utf8");
+            let content;
+            if (fromFile !== undefined) {
+                if (!fs.existsSync(fromFile)) {
+                    throw new NotFoundError(`Source file not found: ${fromFile}`, "FILE_NOT_FOUND");
                 }
-                writeEnv(absPath, content);
+                content = fs.readFileSync(fromFile, "utf8");
             }
             else {
-                createEnv(absPath);
+                const MAX_ENV_BYTES = 1024 * 1024; // 1 MB
+                const buf = await readStdin(MAX_ENV_BYTES, () => new UsageError("Env file exceeds 1 MB limit.", "INVALID_FLAG_VALUE"));
+                content = buf.toString("utf8");
             }
-            if (args.sensitive) {
-                const markerPath = absPath.replace(/\.env$/, ".sensitive");
-                if (!fs.existsSync(markerPath)) {
-                    fs.writeFileSync(markerPath, "", { mode: 0o600 });
-                }
+            writeEnv(absPath, content);
+        }
+        else {
+            createEnv(absPath);
+        }
+        if (args.sensitive) {
+            const markerPath = absPath.replace(/\.env$/, ".sensitive");
+            if (!fs.existsSync(markerPath)) {
+                fs.writeFileSync(markerPath, "", { mode: 0o600 });
             }
-            output("env-create", { ref: makeEnvRef(parsed.name, source) });
-        });
+        }
+        output("env-create", { ref: makeEnvRef(parsed.name, source) });
     },
 });
-const envPathCommand = defineCommand({
+const envPathCommand = defineJsonCommand({
     meta: {
         name: "path",
         description: "Print the absolute env file path (Docker `_FILE` convention / `--env-file`). To inject values, use `akm env run <ref> -- <cmd>` — do NOT `source` the raw file.",
@@ -161,24 +157,22 @@ const envPathCommand = defineCommand({
         ref: { type: "positional", description: "Env ref", required: true },
         quiet: { type: "boolean", alias: "q", description: "Suppress the unsafe-source warning", default: false },
     },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const { name, absPath, source } = resolveEnvPath(args.ref);
-            if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
-            }
-            // The raw `.env` may contain `X=$(cmd)`, which executes if `source`d.
-            // Warning goes to stderr (never contaminates the path on stdout) and is
-            // suppressed with --quiet for the legitimate `_FILE` / `--env-file` use.
-            if (args.quiet !== true) {
-                process.stderr.write(`warning: this is the raw file path. Do NOT \`source\` it (shell substitutions in the file would execute).\n` +
-                    `         To inject values run: akm env run ${args.ref} -- <command>\n`);
-            }
-            process.stdout.write(`${absPath}\n`);
-        });
+    async run({ args }) {
+        const { name, absPath, source } = resolveEnvPath(args.ref);
+        if (!fs.existsSync(absPath)) {
+            throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
+        }
+        // The raw `.env` may contain `X=$(cmd)`, which executes if `source`d.
+        // Warning goes to stderr (never contaminates the path on stdout) and is
+        // suppressed with --quiet for the legitimate `_FILE` / `--env-file` use.
+        if (args.quiet !== true) {
+            process.stderr.write(`warning: this is the raw file path. Do NOT \`source\` it (shell substitutions in the file would execute).\n` +
+                `         To inject values run: akm env run ${args.ref} -- <command>\n`);
+        }
+        process.stdout.write(`${absPath}\n`);
     },
 });
-const envExportCommand = defineCommand({
+const envExportCommand = defineJsonCommand({
     meta: {
         name: "export",
         description: "Write safe `export KEY='value'` lines to a file (mode 0600) for `source`-ing — requires --out <path>. Values are re-serialised single-quoted so a raw `.env` cannot execute on load, and are NEVER printed to stdout. To use values directly, prefer `akm env run <ref> -- <command>`.",
@@ -187,23 +181,21 @@ const envExportCommand = defineCommand({
         ref: { type: "positional", description: "Env ref", required: true },
         out: { type: "string", alias: "o", description: "Destination file (required). Written at mode 0600." },
     },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const outPath = getHyphenatedArg(args, "out");
-            if (!outPath) {
-                throw new UsageError("`akm env export` writes to a file — pass --out <path>.\n" +
-                    "       To use values directly, run `akm env run <ref> -- <command>` (or `-- $SHELL` for an interactive\n" +
-                    "       session). export never prints values to stdout, to avoid leaking them into a captured context.", "MISSING_REQUIRED_ARGUMENT");
-            }
-            const { name, absPath, source } = resolveEnvPath(args.ref);
-            if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
-            }
-            const { buildShellExportScript } = await import("./env.js");
-            const resolvedOut = path.resolve(outPath);
-            writeFileAtomic(resolvedOut, buildShellExportScript(absPath), 0o600);
-            output("env-export", { ref: makeEnvRef(name, source), out: resolvedOut });
-        });
+    async run({ args }) {
+        const outPath = args.out;
+        if (!outPath) {
+            throw new UsageError("`akm env export` writes to a file — pass --out <path>.\n" +
+                "       To use values directly, run `akm env run <ref> -- <command>` (or `-- $SHELL` for an interactive\n" +
+                "       session). export never prints values to stdout, to avoid leaking them into a captured context.", "MISSING_REQUIRED_ARGUMENT");
+        }
+        const { name, absPath, source } = resolveEnvPath(args.ref);
+        if (!fs.existsSync(absPath)) {
+            throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
+        }
+        const { buildShellExportScript } = await import("./env.js");
+        const resolvedOut = path.resolve(outPath);
+        writeFileAtomic(resolvedOut, buildShellExportScript(absPath), 0o600);
+        output("env-export", { ref: makeEnvRef(name, source), out: resolvedOut });
     },
 });
 /**
@@ -239,74 +231,21 @@ async function runEnvInjected(target, opts) {
         }
         throw new NotFoundError(`Env not found: ${makeEnvRef(name, source)}`);
     }
-    const { loadEnv } = await import("./env.js");
-    const allValues = loadEnv(absPath);
-    // Value-safe key filtering (--only / --except operate on key NAMES only).
-    let envValues = allValues;
-    if (opts.only && opts.except) {
-        throw new UsageError("Pass only one of --only or --except.", "INVALID_FLAG_VALUE");
-    }
-    if (opts.only) {
-        const wanted = new Set(opts.only);
-        const missing = opts.only.filter((k) => !(k in allValues));
-        if (missing.length > 0) {
-            process.stderr.write(`warning: --only key(s) not present in ${makeEnvRef(name, source)}: ${missing.join(", ")}\n`);
-        }
-        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => wanted.has(k)));
-    }
-    else if (opts.except) {
-        const excluded = new Set(opts.except);
-        envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => !excluded.has(k)));
-    }
-    // Substitute `${secret:NAME}` tokens in values with the value of the sibling
-    // secret asset in the SAME stash. The lookup is injected so commands/env.ts
-    // keeps its narrow dependency surface; we resolve each name against this env's
-    // own `source`. A missing secret is a hard error — inject NOTHING (no partial
-    // injection). Resolved values are never logged or printed.
-    const { resolveSecretTokens } = await import("./env.js");
-    const { readValue } = await import("./secret.js");
-    const secretsRoot = path.join(source.path, "secrets");
-    const resolveSecret = (secretName) => {
-        const secretPath = resolveAssetPathFromName("secret", secretsRoot, secretName);
-        // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
-        if (!isWithin(secretPath, secretsRoot)) {
-            throw new UsageError(`Secret name "${secretName}" escapes the secrets directory.`);
-        }
-        if (!fs.existsSync(secretPath))
-            return undefined;
-        // Match `secret run`: read utf8, do not trim (stay consistent with that path).
-        return readValue(secretPath).toString("utf8");
-    };
-    const { values: substituted, missing } = resolveSecretTokens(envValues, resolveSecret);
-    if (missing.length > 0) {
-        const envRef = makeEnvRef(name, source);
-        throw new NotFoundError(`Env "${envRef}" references secret(s) not found in its stash: ${missing.map((n) => `secret:${n}`).join(", ")}. Nothing was injected.`, "FILE_NOT_FOUND", `Create the missing secret, e.g. \`akm secret set secret:${missing[0]}\`.`);
-    }
-    envValues = substituted;
-    const keys = Object.keys(envValues);
-    // Scan injected keys for known process-hijacking variables (LD_PRELOAD,
-    // PATH, ...). Block for third-party-sourced stashes (origin has a registryId);
-    // warn for the operator's own first-party stash, where they own the file.
-    const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
-    const dangerous = keys.filter(isDangerousEnvKey);
-    if (dangerous.length > 0) {
-        const detail = `Env "${makeEnvRef(name, source)}" injects process-hijacking variable(s): ${dangerous.join(", ")}.`;
-        if (source.registryId) {
-            throw new UsageError(`Refusing to inject env from a third-party stash. ${detail}\n` +
-                `       Review the file, then copy the values into a first-party env if you trust them.`, "INVALID_FLAG_VALUE");
-        }
-        process.stderr.write(`warning: ${detail} Injecting anyway (first-party stash).\n`);
-    }
-    const mergedEnv = { ...process.env };
+    // Load → filter → secret-substitute → dangerous-key policy → keys-only
+    // audit event. Shared with the workflow engine's per-unit env bindings —
+    // see env-binding.ts for the extracted core and its safety invariants.
+    const { resolveEnvBinding } = await import("./env-binding.js");
+    const { values: envValues } = resolveEnvBinding(target, {
+        only: opts.only,
+        except: opts.except,
+    });
+    const mergedEnv = buildChildEnv(process.env, {
+        clean: opts.clean === true,
+        inherit: opts.inherit ?? [],
+    });
     for (const [envKey, envValue] of Object.entries(envValues)) {
         mergedEnv[envKey] = envValue;
     }
-    // Audit trail: keys only, never values.
-    appendEvent({
-        eventType: "env_access",
-        ref: makeEnvRef(name, source),
-        metadata: { keys },
-    });
     const result = spawnSync(command[0], command.slice(1), {
         stdio: "inherit",
         env: mergedEnv,
@@ -336,12 +275,12 @@ function parseKeyListFlag(raw) {
         .filter(Boolean);
     return keys.length > 0 ? keys : undefined;
 }
-const envRunCommand = defineCommand({
+const envRunCommand = defineJsonCommand({
     meta: {
         name: "run",
         description: 
         // biome-ignore lint/suspicious/noTemplateCurlyInString: literal `${secret:NAME}` token syntax documented for users, not interpolation
-        "Run a command with the env file injected into its environment: `akm env run <ref> -- <command>`. Use `-- $SHELL` for an interactive session. Restrict which variables are injected with --only / --except. Values may embed `${secret:NAME}` tokens, replaced at run time with the sibling `secret:NAME` value from the same stash.",
+        "Run a command with the env file injected into its environment: `akm env run <ref> -- <command>`. Use `-- $SHELL` for an interactive session. Restrict which variables are injected with --only / --except. Values may embed `${secret:NAME}` tokens, replaced at run time with the sibling `secret:NAME` value from the same stash. Pass --clean to start the child with a minimal inherited environment instead of the full parent environment.",
     },
     args: {
         target: { type: "positional", description: "Env ref", required: true },
@@ -350,47 +289,56 @@ const envRunCommand = defineCommand({
             description: "Inject ONLY these keys (comma-separated). Mutually exclusive with --except.",
         },
         except: { type: "string", description: "Inject all keys EXCEPT these (comma-separated)." },
+        clean: {
+            type: "boolean",
+            description: "Start the child with a minimal inherited environment (PATH/HOME/locale/terminal basics) instead of the full parent environment.",
+            default: false,
+        },
+        inherit: {
+            type: "string",
+            description: "When used with --clean, also inherit these parent env vars (comma-separated). Ignored without --clean.",
+        },
     },
-    run({ args }) {
-        return runWithJsonErrors(() => runEnvInjected(args.target, {
-            only: parseKeyListFlag(getHyphenatedArg(args, "only")),
-            except: parseKeyListFlag(getHyphenatedArg(args, "except")),
-        }));
+    async run({ args }) {
+        await runEnvInjected(args.target, {
+            only: parseKeyListFlag(args.only),
+            except: parseKeyListFlag(args.except),
+            clean: args.clean === true,
+            inherit: parseKeyListFlag(args.inherit) ?? [],
+        });
     },
 });
-const envRemoveCommand = defineCommand({
+const envRemoveCommand = defineJsonCommand({
     meta: { name: "remove", description: "Remove an env file (and its .sensitive marker, if any)" },
     args: {
         ref: { type: "positional", description: "Env ref", required: true },
         yes: { type: "boolean", alias: "y", description: "Skip confirmation prompt", default: false },
     },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const parsed = parseEnvRef(args.ref);
-            const source = findEnvSource(parsed.origin);
-            const envRoot = path.join(source.path, "env");
-            const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-            if (!isWithin(absPath, envRoot)) {
-                throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-            }
-            const { confirmDestructive } = await import("../../cli/confirm.js");
-            const confirmed = await confirmDestructive(`Remove env "${args.ref}"? This cannot be undone.`, {
-                yes: args.yes === true,
-            });
-            if (!confirmed) {
-                process.stderr.write("Aborted.\n");
-                return;
-            }
-            if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Env not found: ${makeEnvRef(parsed.name, source)}`);
-            }
-            const { removeEnv } = await import("./env.js");
-            const removed = removeEnv(absPath);
-            output("env-remove", { ref: makeEnvRef(parsed.name, source), removed });
+    async run({ args }) {
+        const parsed = parseEnvRef(args.ref);
+        const source = findEnvSource(parsed.origin);
+        const envRoot = path.join(source.path, "env");
+        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+        if (!isWithin(absPath, envRoot)) {
+            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+        }
+        const { confirmDestructive } = await import("../../cli/confirm.js");
+        const confirmed = await confirmDestructive(`Remove env "${args.ref}"? This cannot be undone.`, {
+            yes: args.yes === true,
         });
+        if (!confirmed) {
+            process.stderr.write("Aborted.\n");
+            return;
+        }
+        if (!fs.existsSync(absPath)) {
+            throw new NotFoundError(`Env not found: ${makeEnvRef(parsed.name, source)}`);
+        }
+        const { removeEnv } = await import("./env.js");
+        const removed = removeEnv(absPath);
+        output("env-remove", { ref: makeEnvRef(parsed.name, source), removed });
     },
 });
-const envSetCommand = defineCommand({
+const envSetCommand = defineJsonCommand({
     meta: {
         name: "set",
         description: "Set (create or update) a single KEY in an env file: `akm env set <ref> <KEY>`. The value is read from stdin by default (never via argv); use --from-env <VAR> or --from-file <path>. Preserves existing comments and key order; the value is never printed. Creates the env file if it does not exist.",
@@ -401,59 +349,57 @@ const envSetCommand = defineCommand({
         "from-env": { type: "string", description: "Read the value from the named environment variable" },
         "from-file": { type: "string", description: "Read the value from this file" },
     },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const parsed = parseEnvRef(args.ref);
-            const source = findEnvSource(parsed.origin);
-            const envRoot = path.join(source.path, "env");
-            const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-            if (!isWithin(absPath, envRoot)) {
-                throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-            }
-            const key = String(args.key);
-            const { ENV_KEY_RE, setEnvKey } = await import("./env.js");
-            if (!ENV_KEY_RE.test(key)) {
-                throw new UsageError(`Invalid env key "${key}". Keys match [A-Za-z_][A-Za-z0-9_]*.`, "INVALID_FLAG_VALUE");
-            }
-            const fromEnv = getHyphenatedArg(args, "from-env");
-            const fromFile = getHyphenatedArg(args, "from-file");
-            if (fromEnv !== undefined && fromFile !== undefined) {
-                throw new UsageError("Pass only one of --from-file or --from-env (or use stdin).", "INVALID_FLAG_VALUE");
-            }
-            const MAX_ENV_VALUE_BYTES = 1024 * 1024; // 1 MB
-            let value;
-            if (fromFile !== undefined) {
-                if (!fs.existsSync(fromFile)) {
-                    throw new NotFoundError(`File not found: ${fromFile}`, "FILE_NOT_FOUND");
-                }
-                const buf = fs.readFileSync(fromFile);
-                if (buf.byteLength > MAX_ENV_VALUE_BYTES)
-                    throw new UsageError("Value exceeds the 1 MB limit.");
-                value = buf.toString("utf8");
-            }
-            else if (fromEnv !== undefined) {
-                const v = process.env[fromEnv];
-                if (v === undefined) {
-                    throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
-                }
-                value = v;
-            }
-            else {
-                const buf = await readStdin(MAX_ENV_VALUE_BYTES, () => new UsageError("Value exceeds the 1 MB limit."));
-                // Strip a single trailing newline so `echo "$VAL" | akm env set` is exact.
-                value = buf.toString("utf8").replace(/\n$/, "");
+    async run({ args }) {
+        const parsed = parseEnvRef(args.ref);
+        const source = findEnvSource(parsed.origin);
+        const envRoot = path.join(source.path, "env");
+        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+        if (!isWithin(absPath, envRoot)) {
+            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+        }
+        const key = String(args.key);
+        const { ENV_KEY_RE, setEnvKey } = await import("./env.js");
+        if (!ENV_KEY_RE.test(key)) {
+            throw new UsageError(`Invalid env key "${key}". Keys match [A-Za-z_][A-Za-z0-9_]*.`, "INVALID_FLAG_VALUE");
+        }
+        const fromEnv = args["from-env"];
+        const fromFile = args["from-file"];
+        if (fromEnv !== undefined && fromFile !== undefined) {
+            throw new UsageError("Pass only one of --from-file or --from-env (or use stdin).", "INVALID_FLAG_VALUE");
+        }
+        const MAX_ENV_VALUE_BYTES = 1024 * 1024; // 1 MB
+        let value;
+        if (fromFile !== undefined) {
+            if (!fs.existsSync(fromFile)) {
+                throw new NotFoundError(`File not found: ${fromFile}`, "FILE_NOT_FOUND");
             }
-            setEnvKey(absPath, key, value);
-            // Warn (never block) on process-hijacking key names, matching the env-run audit.
-            const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
-            if (isDangerousEnvKey(key) && !isQuiet()) {
-                process.stderr.write(`warning: "${key}" can influence process execution when this env is loaded via 'akm env run'.\n`);
+            const buf = fs.readFileSync(fromFile);
+            if (buf.byteLength > MAX_ENV_VALUE_BYTES)
+                throw new UsageError("Value exceeds the 1 MB limit.");
+            value = buf.toString("utf8");
+        }
+        else if (fromEnv !== undefined) {
+            const v = process.env[fromEnv];
+            if (v === undefined) {
+                throw new UsageError(`Environment variable "${fromEnv}" is not set.`, "INVALID_FLAG_VALUE");
             }
-            output("env-set", { ref: makeEnvRef(parsed.name, source), key });
-        });
+            value = v;
+        }
+        else {
+            const buf = await readStdin(MAX_ENV_VALUE_BYTES, () => new UsageError("Value exceeds the 1 MB limit."));
+            // Strip a single trailing newline so `echo "$VAL" | akm env set` is exact.
+            value = buf.toString("utf8").replace(/\n$/, "");
+        }
+        setEnvKey(absPath, key, value);
+        // Warn (never block) on process-hijacking key names, matching the env-run audit.
+        const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
+        if (isDangerousEnvKey(key) && !isQuiet()) {
+            process.stderr.write(`warning: "${key}" can influence process execution when this env is loaded via 'akm env run'.\n`);
+        }
+        output("env-set", { ref: makeEnvRef(parsed.name, source), key });
     },
 });
-const envUnsetCommand = defineCommand({
+const envUnsetCommand = defineJsonCommand({
     meta: {
         name: "unset",
         description: "Remove one or more KEYs from an env file: `akm env unset <ref> <KEY...>`. Preserves other keys and comments. To remove the whole file, use `akm env remove`.",
@@ -464,66 +410,56 @@ const envUnsetCommand = defineCommand({
         // non-required so citty doesn't block before we emit a structured error.
         key: { type: "positional", description: "Key name(s) to remove (one or more)", required: false },
     },
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            const parsed = parseEnvRef(args.ref);
-            const source = findEnvSource(parsed.origin);
-            const envRoot = path.join(source.path, "env");
-            const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
-            if (!isWithin(absPath, envRoot)) {
-                throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-            }
-            if (!fs.existsSync(absPath)) {
-                throw new NotFoundError(`Env not found: ${makeEnvRef(parsed.name, source)}`);
-            }
-            // citty puts every positional in `args._` (incl. the ref at [0]); the keys
-            // are the remaining positionals. citty also mis-captures the space-separated
-            // value of a global flag (`--format json`) as a positional, so drop any
-            // token that is actually a global flag's value (cli.ts:1335 documents this).
-            const globalFlagValues = new Set(["--format", "--shape", "--detail", "--scope", "--filter", "--target"]
-                .map((flag) => parseFlagValue(process.argv, flag))
-                .filter((v) => typeof v === "string"));
-            const keys = (Array.isArray(args._) ? args._.map(String) : [])
-                .slice(1)
-                .filter((k) => !globalFlagValues.has(k));
-            if (keys.length === 0) {
-                throw new UsageError("Usage: akm env unset <ref> <KEY...> (one or more keys).", "MISSING_REQUIRED_ARGUMENT");
-            }
-            const { ENV_KEY_RE, unsetEnvKeys } = await import("./env.js");
-            const invalid = keys.filter((k) => !ENV_KEY_RE.test(k));
-            if (invalid.length > 0) {
-                throw new UsageError(`Invalid env key(s): ${invalid.join(", ")}.`, "INVALID_FLAG_VALUE");
-            }
-            const { removed, missing } = unsetEnvKeys(absPath, keys);
-            output("env-unset", { ref: makeEnvRef(parsed.name, source), removed, missing });
-        });
+    async run({ args }) {
+        const parsed = parseEnvRef(args.ref);
+        const source = findEnvSource(parsed.origin);
+        const envRoot = path.join(source.path, "env");
+        const absPath = resolveAssetPathFromName("env", envRoot, parsed.name);
+        if (!isWithin(absPath, envRoot)) {
+            throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
+        }
+        if (!fs.existsSync(absPath)) {
+            throw new NotFoundError(`Env not found: ${makeEnvRef(parsed.name, source)}`);
+        }
+        // citty puts every positional in `args._` (incl. the ref at [0]); the keys
+        // are the remaining positionals. citty also mis-captures the space-separated
+        // value of a global flag (`--format json`) as a positional, so drop any
+        // token that is actually a global flag's value (cli.ts:1335 documents this).
+        const globalFlagValues = new Set(["--format", "--shape", "--detail", "--scope", "--filter", "--target"]
+            .map((flag) => parseFlagValue(process.argv, flag))
+            .filter((v) => typeof v === "string"));
+        const keys = (Array.isArray(args._) ? args._.map(String) : [])
+            .slice(1)
+            .filter((k) => !globalFlagValues.has(k));
+        if (keys.length === 0) {
+            throw new UsageError("Usage: akm env unset <ref> <KEY...> (one or more keys).", "MISSING_REQUIRED_ARGUMENT");
+        }
+        const { ENV_KEY_RE, unsetEnvKeys } = await import("./env.js");
+        const invalid = keys.filter((k) => !ENV_KEY_RE.test(k));
+        if (invalid.length > 0) {
+            throw new UsageError(`Invalid env key(s): ${invalid.join(", ")}.`, "INVALID_FLAG_VALUE");
+        }
+        const { removed, missing } = unsetEnvKeys(absPath, keys);
+        output("env-unset", { ref: makeEnvRef(parsed.name, source), removed, missing });
     },
 });
-// Single source of truth: the routing set is derived from the subCommands keys
-// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
-const envSubCommands = {
-    list: envListCommand,
-    path: envPathCommand,
-    export: envExportCommand,
-    run: envRunCommand,
-    create: envCreateCommand,
-    set: envSetCommand,
-    unset: envUnsetCommand,
-    remove: envRemoveCommand,
-};
-const ENV_SUBCOMMAND_SET = new Set(Object.keys(envSubCommands));
-export const envCommand = defineCommand({
+export const envCommand = defineGroupCommand({
     meta: {
         name: "env",
         description: "Manage `.env` files — a group of related CONFIGURATION values for an app or service (URLs, flags, plus any credentials it needs), loaded together. Values may or may not be sensitive; akm protects them all the same (key names visible, values never in structured output). For a single sensitive value used on its own (an auth token, key, or cert), use `akm secret`.",
     },
-    subCommands: envSubCommands,
-    run({ args }) {
-        return runWithJsonErrors(async () => {
-            if (hasSubcommand(args, ENV_SUBCOMMAND_SET))
-                return;
-            const { listKeys } = await import("./env.js");
-            output("env-list", { envs: listEnvsRecursive(listKeys) });
-        });
+    subCommands: {
+        list: envListCommand,
+        path: envPathCommand,
+        export: envExportCommand,
+        run: envRunCommand,
+        create: envCreateCommand,
+        set: envSetCommand,
+        unset: envUnsetCommand,
+        remove: envRemoveCommand,
+    },
+    async defaultRun() {
+        const { listKeys } = await import("./env.js");
+        output("env-list", { envs: listEnvsRecursive(listKeys) });
     },
 });