feat(cli): add --env KEY=VALUE flag for inline environment variables (#111)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: mcclurejt

packages/cli/src/commands/compute/app/deploy.ts

@@ -35,6 +35,7 @@ import {
   resolveDockerHubImageDigest,
 } from "../../../utils/dockerhub";
 import { isTlsEnabledFromEnvFile } from "../../../utils/tls";
+import { mergeInlineEnvVars } from "../../../utils/env";
 import type { SubmitBuildRequest } from "@layr-labs/ecloud-sdk";
 
 export default class AppDeploy extends Command {
@@ -63,6 +64,11 @@ export default class AppDeploy extends Command {
       default: ".env",
       env: "ECLOUD_ENVFILE_PATH",
     }),
+    env: Flags.string({
+      required: false,
+      description: "Inline environment variable in KEY=VALUE format (can be specified multiple times)",
+      multiple: true,
+    }),
     "log-visibility": Flags.string({
       required: false,
       description: "Log visibility setting: public, private, or off",
@@ -371,6 +377,11 @@ export default class AppDeploy extends Command {
       // 4. Get env file path interactively
       envFilePath = envFilePath ?? (await getEnvFileInteractive(flags["env-file"]));
 
+      // 4b. Merge inline --env KEY=VALUE vars (overrides env file values)
+      if (flags.env && flags.env.length > 0) {
+        envFilePath = mergeInlineEnvVars(envFilePath, flags.env);
+      }
+
       // 5. Get instance type interactively
       const availableTypes = await fetchAvailableInstanceTypes(
         environment,

packages/cli/src/commands/compute/app/upgrade.ts

@@ -32,6 +32,7 @@ import {
   resolveDockerHubImageDigest,
 } from "../../../utils/dockerhub";
 import { isTlsEnabledFromEnvFile } from "../../../utils/tls";
+import { mergeInlineEnvVars } from "../../../utils/env";
 import type { SubmitBuildRequest } from "@layr-labs/ecloud-sdk";
 
 export default class AppUpgrade extends Command {
@@ -62,6 +63,11 @@ export default class AppUpgrade extends Command {
       default: ".env",
       env: "ECLOUD_ENVFILE_PATH",
     }),
+    env: Flags.string({
+      required: false,
+      description: "Inline environment variable in KEY=VALUE format (can be specified multiple times)",
+      multiple: true,
+    }),
     "log-visibility": Flags.string({
       required: false,
       description: "Log visibility setting: public, private, or off",
@@ -287,6 +293,11 @@ export default class AppUpgrade extends Command {
       // 4. Get env file path interactively
       envFilePath = envFilePath ?? (await getEnvFileInteractive(flags["env-file"]));
 
+      // 4b. Merge inline --env KEY=VALUE vars (overrides env file values)
+      if (flags.env && flags.env.length > 0) {
+        envFilePath = mergeInlineEnvVars(envFilePath, flags.env);
+      }
+
       // 5. Get current instance type (best-effort, used as default)
       const { publicClient, walletClient, address } = createViemClients({
         privateKey,

packages/cli/src/utils/__tests__/env.test.ts

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { mergeInlineEnvVars } from "../env";
+
+describe("mergeInlineEnvVars", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "env-test-"));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns original path when no inline vars provided", () => {
+    const envFile = path.join(tmpDir, ".env");
+    fs.writeFileSync(envFile, "FOO=bar\n");
+    expect(mergeInlineEnvVars(envFile, [])).toBe(envFile);
+  });
+
+  it("creates a temp file with inline vars when no env file exists", () => {
+    const result = mergeInlineEnvVars("", ["FOO=bar", "BAZ=qux"]);
+    const content = fs.readFileSync(result, "utf-8");
+    expect(content).toContain("FOO=bar");
+    expect(content).toContain("BAZ=qux");
+  });
+
+  it("merges inline vars with existing env file", () => {
+    const envFile = path.join(tmpDir, ".env");
+    fs.writeFileSync(envFile, "EXISTING=value\nOTHER=stuff\n");
+    const result = mergeInlineEnvVars(envFile, ["NEW=added"]);
+    const content = fs.readFileSync(result, "utf-8");
+    expect(content).toContain("EXISTING=value");
+    expect(content).toContain("OTHER=stuff");
+    expect(content).toContain("NEW=added");
+  });
+
+  it("inline vars override env file vars with same key", () => {
+    const envFile = path.join(tmpDir, ".env");
+    fs.writeFileSync(envFile, "FOO=old\nKEEP=me\n");
+    const result = mergeInlineEnvVars(envFile, ["FOO=new"]);
+    const content = fs.readFileSync(result, "utf-8");
+    expect(content).not.toContain("FOO=old");
+    expect(content).toContain("FOO=new");
+    expect(content).toContain("KEEP=me");
+  });
+
+  it("preserves comments and blank lines from env file", () => {
+    const envFile = path.join(tmpDir, ".env");
+    fs.writeFileSync(envFile, "# This is a comment\n\nFOO=bar\n");
+    const result = mergeInlineEnvVars(envFile, ["BAZ=qux"]);
+    const content = fs.readFileSync(result, "utf-8");
+    expect(content).toContain("# This is a comment");
+    expect(content).toContain("FOO=bar");
+    expect(content).toContain("BAZ=qux");
+  });
+
+  it("handles values containing equals signs", () => {
+    const result = mergeInlineEnvVars("", ["URL=https://example.com?a=1&b=2"]);
+    const content = fs.readFileSync(result, "utf-8");
+    expect(content).toContain("URL=https://example.com?a=1&b=2");
+  });
+
+  it("throws on invalid format (missing =)", () => {
+    expect(() => mergeInlineEnvVars("", ["INVALID"])).toThrow(
+      'Invalid --env format: "INVALID". Expected KEY=VALUE',
+    );
+  });
+
+  it("throws on empty key", () => {
+    expect(() => mergeInlineEnvVars("", ["=value"])).toThrow(
+      'Invalid --env format: "=value". Key cannot be empty',
+    );
+  });
+
+  it("allows empty value", () => {
+    const result = mergeInlineEnvVars("", ["EMPTY="]);
+    const content = fs.readFileSync(result, "utf-8");
+    expect(content).toContain("EMPTY=");
+  });
+});

packages/cli/src/utils/env.ts

@@ -0,0 +1,75 @@
+/**
+ * Utilities for merging inline --env KEY=VALUE flags with env files
+ */
+
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+/**
+ * Parse an inline env var string of the form KEY=VALUE.
+ * Throws if the format is invalid.
+ */
+function parseInlineEnvVar(envVar: string): [string, string] {
+  const eqIndex = envVar.indexOf("=");
+  if (eqIndex === -1) {
+    throw new Error(`Invalid --env format: "${envVar}". Expected KEY=VALUE`);
+  }
+
+  const key = envVar.substring(0, eqIndex).trim();
+  if (!key) {
+    throw new Error(`Invalid --env format: "${envVar}". Key cannot be empty`);
+  }
+
+  const value = envVar.substring(eqIndex + 1);
+  return [key, value];
+}
+
+/**
+ * Merge inline env vars with an env file, writing the result to a temp file.
+ * Inline vars override env file vars with the same key.
+ *
+ * Returns the path to the merged temp file, or the original env file path
+ * if there are no inline vars to merge.
+ */
+export function mergeInlineEnvVars(envFilePath: string, inlineEnvVars: string[]): string {
+  if (!inlineEnvVars || inlineEnvVars.length === 0) {
+    return envFilePath;
+  }
+
+  // Parse inline vars first to fail fast on bad format
+  const inlineEntries = inlineEnvVars.map(parseInlineEnvVar);
+
+  // Read existing env file content (if any)
+  let existingLines: string[] = [];
+  if (envFilePath && fs.existsSync(envFilePath)) {
+    existingLines = fs.readFileSync(envFilePath, "utf-8").split("\n");
+  }
+
+  // Build a set of keys being overridden by inline vars
+  const inlineKeys = new Set(inlineEntries.map(([key]) => key));
+
+  // Filter out lines from the env file that are overridden by inline vars
+  const filteredLines = existingLines.filter((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      return true; // keep comments and blank lines
+    }
+    const eqIndex = trimmed.indexOf("=");
+    if (eqIndex === -1) {
+      return true; // keep malformed lines
+    }
+    const key = trimmed.substring(0, eqIndex).trim();
+    return !inlineKeys.has(key);
+  });
+
+  // Append inline vars
+  const inlineLines = inlineEntries.map(([key, value]) => `${key}=${value}`);
+  const merged = [...filteredLines, ...inlineLines].join("\n");
+
+  // Write to temp file
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ecloud-env-"));
+  const tmpFile = path.join(tmpDir, ".env");
+  fs.writeFileSync(tmpFile, merged);
+  return tmpFile;
+}