@dotlabs-hq/env-cli 1.0.0

package/README.md

@@ -0,0 +1,93 @@
+# @dotlabs-hq/env-cli
+
+Node.js CLI for managing projects, env files, secrets, and imports against `https://env.wpsadi.dev`.
+
+## Install
+
+- `npm install`
+
+## Development
+
+- `npm run dev -- --help`
+- `npm run typecheck`
+- `npm run build`
+
+## Publishing
+
+- the package is built to `dist/`
+- the published executable is `dist/index.js`
+- `npm publish` runs `prepublishOnly`, which typechecks and builds first
+- GitHub Actions can publish automatically using npm trusted publishing
+- if you prefer token-based publishing, you can adapt the workflow to provide `NODE_AUTH_TOKEN`
+
+## Command groups
+
+- `env auth <login|whoami|logout|doctor>`
+- `env project <list|create|get|update|delete>`
+- `env file <list|create|show|upload|delete>`
+- `env secret <list|create|get|update|delete>`
+- `env import file <projectName> <fileName> --from <path>`
+- `env config <get|set|clear>`
+
+## Global flags
+
+- `--endpoint <url>`
+- `--username <name>`
+- `--api-key <token>`
+- `--json`
+- `--yes`
+- `--quiet`
+- `--help`
+
+## Environment variables
+
+- `ENV_ENDPOINT`
+- `ENV_API_TOKEN`
+- `ENV_API_KEY`
+- `ENV_USERNAME`
+
+Resolution order:
+
+1. command flags
+2. environment variables
+3. local config file
+4. built-in defaults
+
+## Local config
+
+Config is stored at:
+
+- Windows: `%USERPROFILE%\.env-cli\config.json`
+
+Example:
+
+```json
+{
+	"endpoint": "https://env.wpsadi.dev",
+	"username": "wpsadi",
+	"apiKey": "token"
+}
+```
+
+## Examples
+
+- `env auth login`
+- `env project create my-app --description "Production config"`
+- `env file upload my-app .env --from .env.local`
+- `env secret create my-app .env DATABASE_URL --value postgres://localhost/db`
+- `env import file my-app .env.production --from .env.production --mode overwrite --yes`
+- `env config get --json`
+
+## API surface expected by the CLI
+
+The CLI is implemented against the REST shape defined in [Plan.md](Plan.md), including:
+
+- `/api/:username/me`
+- `/api/:username/projects`
+- `/api/:username/projects/:projectName`
+- `/api/:username/projects/:projectName/files`
+- `/api/:username/projects/:projectName/files/:fileName/secrets`
+- `/api/:username/projects/:projectName/files/:fileName/import`
+- existing file-level endpoints at `/api/:username/:projectName/:fileName`
+
+If the backend has not exposed those routes yet, the CLI will build correctly but related commands will fail at runtime until the API is available.

package/dist/index.js

@@ -0,0 +1,936 @@
+#!/usr/bin/env node
+
+// src/constants.ts
+var DEFAULT_ENDPOINT = "https://env.wpsadi.dev";
+var CONFIG_DIR_NAME = ".env-cli";
+var CONFIG_FILE_NAME = "config.json";
+var REQUEST_TIMEOUT_MS = 15e3;
+var EXIT_CODES = {
+  success: 0,
+  generic: 1,
+  usage: 2,
+  auth: 3,
+  network: 4
+};
+var IMPORT_MODES = ["merge", "overwrite"];
+
+// src/errors.ts
+var EXIT_CODE_BY_TYPE = {
+  api_error: EXIT_CODES.generic,
+  auth_error: EXIT_CODES.auth,
+  config_error: EXIT_CODES.auth,
+  network_error: EXIT_CODES.network,
+  usage_error: EXIT_CODES.usage,
+  user_cancelled: EXIT_CODES.generic,
+  validation_error: EXIT_CODES.usage
+};
+var CliError = class extends Error {
+  exitCode;
+  type;
+  constructor(type, message, exitCode) {
+    super(message);
+    this.name = "CliError";
+    this.type = type;
+    this.exitCode = exitCode ?? EXIT_CODE_BY_TYPE[type];
+  }
+};
+var isCliError = (error) => error instanceof CliError;
+var toCliError = (error) => {
+  if (isCliError(error)) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new CliError("api_error", error.message);
+  }
+  return new CliError("api_error", "Unknown error");
+};
+
+// src/output.ts
+import pc from "picocolors";
+import { intro, outro, spinner as createSpinner } from "@clack/prompts";
+var SilentSpinner = class {
+  fail(_message) {
+  }
+  start(_message) {
+  }
+  stop(_message) {
+  }
+};
+var Output = class {
+  constructor(mode, quiet) {
+    this.mode = mode;
+    this.quiet = quiet;
+  }
+  intro(message) {
+    if (this.mode === "human" && !this.quiet) {
+      intro(message);
+    }
+  }
+  outro(message) {
+    if (this.mode === "human" && !this.quiet) {
+      outro(message);
+    }
+  }
+  info(message) {
+    if (this.mode === "human" && !this.quiet) {
+      console.log(pc.cyan(message));
+    }
+  }
+  muted(message) {
+    if (this.mode === "human" && !this.quiet) {
+      console.log(pc.dim(message));
+    }
+  }
+  success(message) {
+    if (this.mode === "human" && !this.quiet) {
+      console.log(pc.green(`\u2714 ${message}`));
+    }
+  }
+  error(message) {
+    if (this.mode === "human") {
+      console.error(pc.red(`\u2716 ${message}`));
+    }
+  }
+  list(title, items) {
+    if (this.mode !== "human" || this.quiet) {
+      return;
+    }
+    console.log(pc.bold(title));
+    for (const item of items) {
+      console.log(`  \u2022 ${item}`);
+    }
+  }
+  spinner() {
+    if (this.mode !== "human" || this.quiet) {
+      return new SilentSpinner();
+    }
+    const instance = createSpinner();
+    return {
+      fail(message) {
+        instance.stop(pc.red(message), 1);
+      },
+      start(message) {
+        instance.start(message);
+      },
+      stop(message) {
+        instance.stop(pc.green(message));
+      }
+    };
+  }
+  json(result) {
+    console.log(JSON.stringify({ success: true, ...result }, null, 2));
+  }
+};
+var printJsonError = (message, type) => {
+  console.error(
+    JSON.stringify(
+      {
+        success: false,
+        error: { message, type }
+      },
+      null,
+      2
+    )
+  );
+};
+
+// src/client.ts
+var asMessage = (payload) => {
+  if (!payload || typeof payload !== "object") {
+    return void 0;
+  }
+  const record = payload;
+  if (typeof record.message === "string") {
+    return record.message;
+  }
+  const errorValue = record.error;
+  if (typeof errorValue === "string") {
+    return errorValue;
+  }
+  if (errorValue && typeof errorValue === "object") {
+    const errorRecord = errorValue;
+    if (typeof errorRecord.message === "string") {
+      return errorRecord.message;
+    }
+  }
+  return void 0;
+};
+var EnvApiClient = class {
+  constructor(endpoint, apiKey) {
+    this.endpoint = endpoint;
+    this.apiKey = apiKey;
+  }
+  async request(path, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("accept", "application/json");
+    if (init?.body) {
+      headers.set("content-type", "application/json");
+    }
+    if (this.apiKey) {
+      headers.set("authorization", `Bearer ${this.apiKey}`);
+    }
+    let response;
+    try {
+      response = await fetch(`${this.endpoint}${path}`, {
+        ...init,
+        headers,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new CliError("network_error", error.message);
+      }
+      throw new CliError("network_error", "Request failed");
+    }
+    const text2 = await response.text();
+    const payload = text2 ? JSON.parse(text2) : null;
+    if (!response.ok) {
+      const message = asMessage(payload) ?? `${response.status} ${response.statusText}`;
+      const type = response.status === 401 || response.status === 403 ? "auth_error" : "api_error";
+      throw new CliError(type, message);
+    }
+    return payload;
+  }
+  getMe(username) {
+    return this.request(`/api/${username}/me`);
+  }
+  listProjects(username) {
+    return this.request(`/api/${username}/projects`);
+  }
+  createProject(username, projectName, description) {
+    return this.request(`/api/${username}/projects`, {
+      body: JSON.stringify({ description, projectName }),
+      method: "POST"
+    });
+  }
+  getProject(username, projectName) {
+    return this.request(`/api/${username}/projects/${projectName}`);
+  }
+  updateProject(username, projectName, description) {
+    return this.request(`/api/${username}/projects/${projectName}`, {
+      body: JSON.stringify({ description }),
+      method: "PATCH"
+    });
+  }
+  deleteProject(username, projectName) {
+    return this.request(`/api/${username}/projects/${projectName}`, { method: "DELETE" });
+  }
+  listFiles(username, projectName) {
+    return this.request(`/api/${username}/projects/${projectName}/files`);
+  }
+  createFile(username, projectName, fileName) {
+    return this.request(`/api/${username}/projects/${projectName}/files`, {
+      body: JSON.stringify({ fileName }),
+      method: "POST"
+    });
+  }
+  showFile(username, projectName, fileName) {
+    return this.request(`/api/${username}/${projectName}/${fileName}`);
+  }
+  uploadFile(username, projectName, fileName, content) {
+    return this.request(`/api/${username}/${projectName}/${fileName}`, {
+      body: JSON.stringify({ content }),
+      method: "PUT"
+    });
+  }
+  deleteFile(username, projectName, fileName) {
+    return this.request(`/api/${username}/${projectName}/${fileName}`, { method: "DELETE" });
+  }
+  listSecrets(username, projectName, fileName) {
+    return this.request(`/api/${username}/projects/${projectName}/files/${fileName}/secrets`);
+  }
+  createSecret(username, projectName, fileName, keyName, value) {
+    return this.request(`/api/${username}/projects/${projectName}/files/${fileName}/secrets`, {
+      body: JSON.stringify({ keyName, value }),
+      method: "POST"
+    });
+  }
+  getSecret(username, projectName, fileName, keyName) {
+    return this.request(`/api/${username}/projects/${projectName}/files/${fileName}/secrets/${keyName}`);
+  }
+  updateSecret(username, projectName, fileName, keyName, value) {
+    return this.request(`/api/${username}/projects/${projectName}/files/${fileName}/secrets/${keyName}`, {
+      body: JSON.stringify({ value }),
+      method: "PATCH"
+    });
+  }
+  deleteSecret(username, projectName, fileName, keyName) {
+    return this.request(`/api/${username}/projects/${projectName}/files/${fileName}/secrets/${keyName}`, {
+      method: "DELETE"
+    });
+  }
+  importFile(username, projectName, fileName, content, mode) {
+    return this.request(`/api/${username}/projects/${projectName}/files/${fileName}/import`, {
+      body: JSON.stringify({ content, mode }),
+      method: "POST"
+    });
+  }
+};
+
+// src/config.ts
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+
+// src/validation.ts
+import { z } from "zod";
+var ProjectNameSchema = z.string().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/, "Use letters, numbers, '_' or '-'");
+var FileNameSchema = z.string().min(1).max(128).regex(/^\.?[A-Za-z0-9._-]+$/, "Use .env-style file names only").refine((value) => !value.includes("/") && !value.includes("\\"), {
+  message: "Paths are not allowed in file names"
+}).refine((value) => !value.includes(".."), {
+  message: "Path traversal is not allowed"
+});
+var SecretKeySchema = z.string().min(1).max(128).regex(/^[A-Z0-9_]+$/, "Use uppercase letters, numbers, and underscores");
+var NonEmptyStringSchema = z.string().min(1);
+var EndpointSchema = z.string().url();
+var ImportModeSchema = z.enum(IMPORT_MODES);
+var StoredConfigSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  endpoint: EndpointSchema.optional(),
+  username: z.string().min(1).optional()
+});
+var parseRequired = (schema, value, label) => {
+  if (!value) {
+    throw new CliError("validation_error", `${label} is required`);
+  }
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    throw new CliError("validation_error", `${label}: ${result.error.issues[0]?.message ?? "Invalid value"}`);
+  }
+  return result.data;
+};
+var parseOptionalMode = (value) => {
+  if (!value) {
+    return void 0;
+  }
+  const result = ImportModeSchema.safeParse(value);
+  if (!result.success) {
+    throw new CliError("validation_error", "Mode must be merge or overwrite");
+  }
+  return result.data;
+};
+
+// src/config.ts
+var configFilePath = join(homedir(), CONFIG_DIR_NAME, CONFIG_FILE_NAME);
+var getConfigPath = () => configFilePath;
+var readConfig = async () => {
+  try {
+    const content = await readFile(configFilePath, "utf8");
+    const parsed = JSON.parse(content);
+    return StoredConfigSchema.parse(parsed);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return {};
+    }
+    throw new CliError("config_error", "Failed to read local config");
+  }
+};
+var writeConfig = async (config) => {
+  const parsed = StoredConfigSchema.safeParse(config);
+  if (!parsed.success) {
+    throw new CliError("config_error", "Refusing to write invalid config");
+  }
+  await mkdir(dirname(configFilePath), { recursive: true });
+  await writeFile(configFilePath, `${JSON.stringify(parsed.data, null, 2)}
+`, "utf8");
+};
+var clearConfig = async () => {
+  await rm(configFilePath, { force: true });
+};
+var resolveConfig = (flags, storedConfig) => {
+  const endpoint = flags.endpoint ?? process.env.ENV_ENDPOINT ?? storedConfig.endpoint ?? DEFAULT_ENDPOINT;
+  const endpointCheck = EndpointSchema.safeParse(endpoint);
+  if (!endpointCheck.success) {
+    throw new CliError("config_error", "Configured endpoint is not a valid URL");
+  }
+  return {
+    apiKey: flags.apiKey ?? process.env.ENV_API_TOKEN ?? process.env.ENV_API_KEY ?? storedConfig.apiKey,
+    endpoint: endpointCheck.data.replace(/\/+$/, ""),
+    username: flags.username ?? process.env.ENV_USERNAME ?? storedConfig.username
+  };
+};
+
+// src/help.ts
+var GLOBAL_OPTIONS = [
+  { description: "Use a custom API endpoint", name: "--endpoint <url>" },
+  { description: "Override the configured username", name: "--username <name>" },
+  { description: "Override the configured API key", name: "--api-key <token>" },
+  { description: "Print machine-readable JSON", name: "--json" },
+  { description: "Skip confirmation prompts", name: "--yes" },
+  { description: "Suppress non-error human output", name: "--quiet" }
+];
+var HELP = {
+  root: {
+    description: "Manage env.wpsadi.dev projects, files, secrets, and imports.",
+    examples: ["env auth login", "env project list", "env import file my-app .env --from .env.production --mode merge"],
+    options: [...GLOBAL_OPTIONS],
+    usage: ["env <command>", "env help <command>"]
+  },
+  auth: {
+    description: "Authenticate and inspect CLI configuration.",
+    examples: ["env auth login", "env auth whoami", "env auth doctor"],
+    usage: ["env auth <login|whoami|logout|doctor>"]
+  },
+  config: {
+    description: "Manage local CLI config stored in the user profile.",
+    examples: ["env config get", "env config set endpoint https://env.wpsadi.dev", "env config clear --yes"],
+    usage: ["env config <get|set|clear>"]
+  },
+  file: {
+    description: "Manage env files inside a project.",
+    examples: ["env file list my-app", "env file create my-app .env", "env file upload my-app .env --from .env.local"],
+    usage: ["env file <list|create|delete|show|upload> [args]"]
+  },
+  import: {
+    description: "Bulk import a local env file.",
+    examples: ["env import file my-app .env --from .env --mode overwrite"],
+    usage: ["env import file <projectName> <fileName> --from <path> [--mode merge|overwrite]"]
+  },
+  project: {
+    description: "Manage projects.",
+    examples: ["env project list", "env project create my-app", "env project delete my-app --yes"],
+    usage: ["env project <list|create|get|update|delete> [args]"]
+  },
+  secret: {
+    description: "Manage one secret at a time.",
+    examples: ["env secret list my-app .env", "env secret create my-app .env DATABASE_URL --value postgres://..."],
+    usage: ["env secret <list|create|get|update|delete> [args]"]
+  }
+};
+var renderHelp = (topic) => {
+  const help = HELP[topic ?? "root"] ?? HELP.root;
+  const lines = [help.description, "", "Usage:"];
+  for (const usage of help.usage) {
+    lines.push(`  ${usage}`);
+  }
+  if (help.options?.length) {
+    lines.push("", "Options:");
+    for (const option of help.options) {
+      lines.push(`  ${option.name.padEnd(22)} ${option.description}`);
+    }
+  }
+  lines.push("", "Examples:");
+  for (const example of help.examples) {
+    lines.push(`  ${example}`);
+  }
+  if (!topic || topic === "root") {
+    lines.push("", "Commands:", "  auth", "  config", "  file", "  import", "  project", "  secret");
+  }
+  lines.push("", "Environment variables:", "  ENV_ENDPOINT", "  ENV_API_TOKEN or ENV_API_KEY", "  ENV_USERNAME");
+  return `${lines.join("\n")}
+`;
+};
+
+// src/utils/prompts.ts
+import { cancel, confirm, isCancel, password, select, text } from "@clack/prompts";
+var unwrap = (value) => {
+  if (isCancel(value)) {
+    cancel("Cancelled");
+    throw new CliError("user_cancelled", "Operation cancelled by user");
+  }
+  return value;
+};
+var promptText = async (message, initialValue, placeholder, required = true) => {
+  const value = await text({
+    message,
+    initialValue,
+    placeholder,
+    validate(input) {
+      if (!required) {
+        return void 0;
+      }
+      return input.trim() ? void 0 : "Value is required";
+    }
+  });
+  return unwrap(value).trim();
+};
+var promptPassword = async (message) => {
+  const value = await password({
+    message,
+    validate(input) {
+      return input.trim() ? void 0 : "Value is required";
+    }
+  });
+  return unwrap(value).trim();
+};
+var promptConfirm = async (message, initialValue = false) => {
+  const value = await confirm({ message, initialValue });
+  return unwrap(value);
+};
+var promptSelect = async (message, options) => {
+  const value = await select({
+    message,
+    options: options.map((option) => ({
+      label: option.label,
+      value: option.value
+    }))
+  });
+  return unwrap(value);
+};
+
+// src/utils/command.ts
+var requireUsername = (context) => {
+  if (!context.config.username) {
+    throw new CliError("config_error", "Username is required. Run 'env auth login' or pass --username.");
+  }
+  return context.config.username;
+};
+var requireApiKey = (context) => {
+  if (!context.config.apiKey) {
+    throw new CliError("config_error", "API key is required. Run 'env auth login' or pass --api-key.");
+  }
+  return context.config.apiKey;
+};
+var asRecord = (value) => {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+};
+var asRecordArray = (value, keys) => {
+  if (Array.isArray(value)) {
+    return value.filter((item) => Boolean(item) && typeof item === "object");
+  }
+  const record = asRecord(value);
+  for (const key of keys) {
+    const candidate = record[key];
+    if (Array.isArray(candidate)) {
+      return candidate.filter((item) => Boolean(item) && typeof item === "object");
+    }
+  }
+  return [];
+};
+var recordToJson = (value) => {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return { value: String(value) };
+  }
+};
+var pickString = (record, keys) => {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+};
+
+// src/commands/auth.ts
+var validateAuth = async (endpoint, username, apiKey) => {
+  const client = new EnvApiClient(endpoint, apiKey);
+  try {
+    return await client.getMe(username);
+  } catch (error) {
+    if (error instanceof CliError) {
+      throw error;
+    }
+    throw new CliError("auth_error", "Authentication failed");
+  }
+};
+var runAuth = async (context, args) => {
+  const subcommand = args[0] ?? "login";
+  if (subcommand === "login") {
+    context.output.intro("Env CLI login");
+    const endpoint = context.flags.endpoint ? parseRequired(EndpointSchema, context.flags.endpoint, "Endpoint") : context.canPrompt ? parseRequired(
+      EndpointSchema,
+      await promptText("API endpoint", context.config.endpoint),
+      "Endpoint"
+    ) : context.config.endpoint;
+    const username = context.flags.username ?? (context.canPrompt ? await promptText("Username", context.config.username) : context.config.username);
+    const apiKey = context.flags.apiKey ?? (context.canPrompt ? await promptPassword("API key") : context.config.apiKey);
+    const safeUsername = parseRequired(NonEmptyStringSchema, username, "Username");
+    const safeApiKey = parseRequired(NonEmptyStringSchema, apiKey, "API key");
+    const spin = context.output.spinner();
+    spin.start("Validating credentials");
+    const profile = await validateAuth(endpoint, safeUsername, safeApiKey);
+    spin.stop("Credentials verified");
+    await writeConfig({ apiKey: safeApiKey, endpoint, username: safeUsername });
+    context.output.outro("Saved local config");
+    return { data: recordToJson(profile), message: "Logged in successfully" };
+  }
+  if (subcommand === "whoami" || subcommand === "doctor") {
+    const username = context.config.username;
+    const apiKey = requireApiKey(context);
+    if (!username) {
+      throw new CliError("config_error", "Username is not configured");
+    }
+    const spin = context.output.spinner();
+    spin.start(subcommand === "doctor" ? "Checking configuration" : "Fetching profile");
+    const profile = await validateAuth(context.config.endpoint, username, apiKey);
+    spin.stop("Configuration looks good");
+    const profileRecord = typeof profile === "object" && profile ? profile : {};
+    const userRecord = typeof profileRecord.user === "object" && profileRecord.user ? profileRecord.user : profileRecord;
+    if (subcommand === "doctor") {
+      context.output.list("Resolved configuration", [
+        `endpoint: ${context.config.endpoint}`,
+        `username: ${username}`,
+        `api key: ${context.config.apiKey ? "set" : "missing"}`
+      ]);
+      return {
+        data: {
+          endpoint: context.config.endpoint,
+          profile: recordToJson(profile),
+          username
+        },
+        message: "Configuration verified"
+      };
+    }
+    context.output.list("Authenticated user", [
+      `username: ${pickString(userRecord, ["username", "login", "name"]) ?? username}`,
+      `endpoint: ${context.config.endpoint}`
+    ]);
+    return { data: recordToJson(profile), message: "Authenticated user" };
+  }
+  if (subcommand === "logout") {
+    if (!context.flags.yes && context.canPrompt) {
+      const confirmed = await promptConfirm("Remove local credentials?", false);
+      if (!confirmed) {
+        throw new CliError("user_cancelled", "Operation cancelled by user");
+      }
+    }
+    await clearConfig();
+    return { data: { cleared: true }, message: "Logged out" };
+  }
+  throw new CliError("usage_error", `Unknown auth command: ${subcommand}`);
+};
+
+// src/commands/config.ts
+var runConfig = async (context, args) => {
+  const subcommand = args[0] ?? "get";
+  if (subcommand === "get") {
+    context.output.list("Config", [
+      `path: ${getConfigPath()}`,
+      `endpoint: ${context.config.endpoint}`,
+      `username: ${context.rawConfig.username ?? "<unset>"}`,
+      `api key: ${context.rawConfig.apiKey ? "set" : "<unset>"}`
+    ]);
+    return {
+      data: recordToJson({ path: getConfigPath(), resolved: context.config, stored: context.rawConfig }),
+      message: "Loaded config"
+    };
+  }
+  if (subcommand === "set") {
+    const key = args[1];
+    const value = args[2] ?? (context.canPrompt ? await promptText(`Value for ${key ?? "setting"}`) : void 0);
+    if (!key || !value) {
+      throw new CliError("usage_error", "Usage: env config set <endpoint|username> <value>");
+    }
+    const nextConfig = { ...context.rawConfig };
+    if (key === "endpoint") {
+      nextConfig.endpoint = EndpointSchema.parse(value);
+    } else if (key === "username") {
+      nextConfig.username = value;
+    } else {
+      throw new CliError("usage_error", "Only endpoint and username can be set directly");
+    }
+    await writeConfig(nextConfig);
+    return { data: recordToJson(nextConfig), message: `Updated ${key}` };
+  }
+  if (subcommand === "clear") {
+    if (!context.flags.yes && context.canPrompt) {
+      const confirmed = await promptConfirm("Clear local config?", false);
+      if (!confirmed) {
+        throw new CliError("user_cancelled", "Operation cancelled by user");
+      }
+    }
+    await clearConfig();
+    return { data: { cleared: true }, message: "Cleared local config" };
+  }
+  throw new CliError("usage_error", `Unknown config command: ${subcommand}`);
+};
+
+// src/utils/env-file.ts
+import { readFile as readFile2, stat } from "fs/promises";
+import { resolve } from "path";
+var readLocalEnvFile = async (filePath) => {
+  const resolvedPath = resolve(filePath);
+  let fileStat;
+  try {
+    fileStat = await stat(resolvedPath);
+  } catch {
+    throw new CliError("validation_error", `File not found: ${resolvedPath}`);
+  }
+  if (!fileStat.isFile()) {
+    throw new CliError("validation_error", `Not a file: ${resolvedPath}`);
+  }
+  const content = await readFile2(resolvedPath, "utf8");
+  if (!content.trim()) {
+    throw new CliError("validation_error", "Import file is empty");
+  }
+  return { content, path: resolvedPath };
+};
+
+// src/commands/file.ts
+var runFile = async (context, args) => {
+  requireApiKey(context);
+  const username = requireUsername(context);
+  const client = new EnvApiClient(context.config.endpoint, context.config.apiKey);
+  const subcommand = args[0] ?? "list";
+  const projectName = args[1] ?? (context.canPrompt ? await promptText("Project name") : void 0);
+  if (subcommand === "list") {
+    const safeProjectName2 = parseRequired(ProjectNameSchema, projectName, "Project name");
+    const data = await client.listFiles(username, safeProjectName2);
+    const files = asRecordArray(data, ["files", "data"]);
+    context.output.list("Files", files.map((file) => pickString(file, ["fileName", "name"]) ?? JSON.stringify(file)));
+    return { data: recordToJson(files), message: `Listed files for ${safeProjectName2}` };
+  }
+  const safeProjectName = parseRequired(ProjectNameSchema, projectName, "Project name");
+  const fileName = args[2] ?? (context.canPrompt ? await promptText("File name", ".env") : void 0);
+  const safeFileName = parseRequired(FileNameSchema, fileName, "File name");
+  if (subcommand === "create") {
+    const created = await client.createFile(username, safeProjectName, safeFileName);
+    return { data: recordToJson(created), message: `Created file ${safeFileName}` };
+  }
+  if (subcommand === "show") {
+    const data = await client.showFile(username, safeProjectName, safeFileName);
+    context.output.info(JSON.stringify(recordToJson(data), null, 2));
+    return { data: recordToJson(data), message: `Fetched file ${safeFileName}` };
+  }
+  if (subcommand === "upload") {
+    const sourcePath = context.flags.from ?? (context.canPrompt ? await promptText("Path to local env file") : void 0);
+    const localFile = await readLocalEnvFile(parseRequired(NonEmptyStringSchema, sourcePath, "Source path"));
+    const result = await client.uploadFile(username, safeProjectName, safeFileName, localFile.content);
+    return { data: recordToJson(result), message: `Uploaded ${localFile.path}` };
+  }
+  if (subcommand === "delete") {
+    if (!context.flags.yes && context.canPrompt) {
+      const confirmed = await promptConfirm(`Delete file ${safeFileName}?`, false);
+      if (!confirmed) {
+        throw new CliError("user_cancelled", "Operation cancelled by user");
+      }
+    }
+    const result = await client.deleteFile(username, safeProjectName, safeFileName);
+    return { data: recordToJson(asRecord(result)), message: `Deleted file ${safeFileName}` };
+  }
+  throw new CliError("usage_error", `Unknown file command: ${subcommand}`);
+};
+
+// src/commands/import.ts
+var runImport = async (context, args) => {
+  requireApiKey(context);
+  const username = requireUsername(context);
+  const client = new EnvApiClient(context.config.endpoint, context.config.apiKey);
+  const subcommand = args[0] ?? "file";
+  if (subcommand !== "file") {
+    throw new CliError("usage_error", "Usage: env import file <projectName> <fileName> --from <path>");
+  }
+  const projectName = parseRequired(ProjectNameSchema, args[1] ?? (context.canPrompt ? await promptText("Project name") : void 0), "Project name");
+  const fileName = parseRequired(FileNameSchema, args[2] ?? (context.canPrompt ? await promptText("File name", ".env") : void 0), "File name");
+  const sourcePath = context.flags.from ?? (context.canPrompt ? await promptText("Path to local env file") : void 0);
+  if (!sourcePath) {
+    throw new CliError("usage_error", "--from is required");
+  }
+  const localFile = await readLocalEnvFile(sourcePath);
+  const mode = parseOptionalMode(context.flags.mode) ?? (context.canPrompt ? await promptSelect("Import mode", [
+    { label: "Merge existing values", value: "merge" },
+    { label: "Overwrite file contents", value: "overwrite" }
+  ]) : "merge");
+  if (mode === "overwrite" && !context.flags.yes && context.canPrompt) {
+    const confirmed = await promptConfirm(`Overwrite ${projectName}/${fileName}?`, false);
+    if (!confirmed) {
+      throw new CliError("user_cancelled", "Operation cancelled by user");
+    }
+  }
+  const result = await client.importFile(username, projectName, fileName, localFile.content, mode);
+  return {
+    data: recordToJson({ mode, path: localFile.path, result }),
+    message: `Imported ${localFile.path} into ${projectName}/${fileName}`
+  };
+};
+
+// src/commands/project.ts
+var runProject = async (context, args) => {
+  requireApiKey(context);
+  const username = requireUsername(context);
+  const client = new EnvApiClient(context.config.endpoint, context.config.apiKey);
+  const subcommand = args[0] ?? "list";
+  if (subcommand === "list") {
+    const data = await client.listProjects(username);
+    const projects = asRecordArray(data, ["projects", "data"]);
+    context.output.list("Projects", projects.map((project) => pickString(project, ["projectName", "name", "slug"]) ?? JSON.stringify(project)));
+    return { data: recordToJson(projects), message: "Listed projects" };
+  }
+  const projectName = args[1] ?? (context.canPrompt ? await promptText("Project name") : void 0);
+  const safeProjectName = parseRequired(ProjectNameSchema, projectName, "Project name");
+  if (subcommand === "create") {
+    const description = context.flags.description ?? (context.canPrompt ? await promptText("Description (optional)", "", "optional", false) : void 0);
+    const created = await client.createProject(username, safeProjectName, description || void 0);
+    return { data: recordToJson(created), message: `Created project ${safeProjectName}` };
+  }
+  if (subcommand === "get") {
+    const project = await client.getProject(username, safeProjectName);
+    context.output.info(JSON.stringify(recordToJson(project), null, 2));
+    return { data: recordToJson(project), message: `Fetched project ${safeProjectName}` };
+  }
+  if (subcommand === "update") {
+    const description = context.flags.description ?? (context.canPrompt ? await promptText("New description", "", "optional", false) : void 0);
+    const project = await client.updateProject(username, safeProjectName, description || void 0);
+    return { data: recordToJson(project), message: `Updated project ${safeProjectName}` };
+  }
+  if (subcommand === "delete") {
+    if (!context.flags.yes && context.canPrompt) {
+      const confirmed = await promptConfirm(`Delete project ${safeProjectName}?`, false);
+      if (!confirmed) {
+        throw new CliError("user_cancelled", "Operation cancelled by user");
+      }
+    }
+    const result = await client.deleteProject(username, safeProjectName);
+    return { data: recordToJson(asRecord(result)), message: `Deleted project ${safeProjectName}` };
+  }
+  throw new CliError("usage_error", `Unknown project command: ${subcommand}`);
+};
+
+// src/commands/secret.ts
+import { z as z2 } from "zod";
+var NonEmptySchema = z2.string().min(1);
+var runSecret = async (context, args) => {
+  requireApiKey(context);
+  const username = requireUsername(context);
+  const client = new EnvApiClient(context.config.endpoint, context.config.apiKey);
+  const subcommand = args[0] ?? "list";
+  const projectName = parseRequired(ProjectNameSchema, args[1] ?? (context.canPrompt ? await promptText("Project name") : void 0), "Project name");
+  const fileName = parseRequired(FileNameSchema, args[2] ?? (context.canPrompt ? await promptText("File name", ".env") : void 0), "File name");
+  if (subcommand === "list") {
+    const data = await client.listSecrets(username, projectName, fileName);
+    const secrets = asRecordArray(data, ["secrets", "data"]);
+    context.output.list("Secrets", secrets.map((secret) => pickString(secret, ["keyName", "key", "name"]) ?? JSON.stringify(secret)));
+    return { data: recordToJson(secrets), message: `Listed secrets for ${fileName}` };
+  }
+  const keyName = parseRequired(SecretKeySchema, args[3] ?? (context.canPrompt ? await promptText("Secret key") : void 0), "Secret key");
+  if (subcommand === "get") {
+    const result = await client.getSecret(username, projectName, fileName, keyName);
+    context.output.info(JSON.stringify(recordToJson(result), null, 2));
+    return { data: recordToJson(result), message: `Fetched secret ${keyName}` };
+  }
+  if (subcommand === "create" || subcommand === "update") {
+    const value = context.flags.value ?? (context.canPrompt ? await promptPassword("Secret value") : void 0);
+    const safeValue = parseRequired(NonEmptySchema, value, "Secret value");
+    const result = subcommand === "create" ? await client.createSecret(username, projectName, fileName, keyName, safeValue) : await client.updateSecret(username, projectName, fileName, keyName, safeValue);
+    return { data: recordToJson(result), message: `${subcommand === "create" ? "Created" : "Updated"} secret ${keyName}` };
+  }
+  if (subcommand === "delete") {
+    if (!context.flags.yes && context.canPrompt) {
+      const confirmed = await promptConfirm(`Delete secret ${keyName}?`, false);
+      if (!confirmed) {
+        throw new CliError("user_cancelled", "Operation cancelled by user");
+      }
+    }
+    const result = await client.deleteSecret(username, projectName, fileName, keyName);
+    return { data: recordToJson(asRecord(result)), message: `Deleted secret ${keyName}` };
+  }
+  throw new CliError("usage_error", `Unknown secret command: ${subcommand}`);
+};
+
+// src/cli.ts
+var VALUE_FLAGS = /* @__PURE__ */ new Set(["api-key", "description", "endpoint", "from", "mode", "username", "value"]);
+var parseFlags = (argv) => {
+  const flags = { help: false, json: false, quiet: false, yes: false };
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token?.startsWith("--")) {
+      positionals.push(token ?? "");
+      continue;
+    }
+    const [rawName, inlineValue] = token.slice(2).split("=", 2);
+    const name = rawName ?? "";
+    if (name === "help") {
+      flags.help = true;
+      continue;
+    }
+    if (name === "json") {
+      flags.json = true;
+      continue;
+    }
+    if (name === "quiet") {
+      flags.quiet = true;
+      continue;
+    }
+    if (name === "yes") {
+      flags.yes = true;
+      continue;
+    }
+    if (!VALUE_FLAGS.has(name)) {
+      throw new CliError("usage_error", `Unknown flag: --${name}`);
+    }
+    const value = inlineValue ?? argv[index + 1];
+    if (!value) {
+      throw new CliError("usage_error", `Flag --${name} requires a value`);
+    }
+    index += inlineValue ? 0 : 1;
+    if (name === "mode") {
+      flags.mode = parseOptionalMode(value);
+      continue;
+    }
+    if (name === "api-key") flags.apiKey = value;
+    if (name === "description") flags.description = value;
+    if (name === "endpoint") flags.endpoint = value;
+    if (name === "from") flags.from = value;
+    if (name === "username") flags.username = value;
+    if (name === "value") flags.value = value;
+  }
+  return { flags, positionals };
+};
+var dispatch = async (context, positionals) => {
+  const [command, ...args] = positionals;
+  if (!command || command === "help") {
+    return { data: { help: renderHelp(args[0]) }, message: renderHelp(args[0]) };
+  }
+  if (context.flags.help) {
+    return { data: { help: renderHelp(command) }, message: renderHelp(command) };
+  }
+  void new EnvApiClient(context.config.endpoint, context.config.apiKey);
+  if (command === "auth") return runAuth(context, args);
+  if (command === "config") return runConfig(context, args);
+  if (command === "file") return runFile(context, args);
+  if (command === "import") return runImport(context, args);
+  if (command === "project") return runProject(context, args);
+  if (command === "secret") return runSecret(context, args);
+  throw new CliError("usage_error", `Unknown command: ${command}`);
+};
+var runCli = async (argv) => {
+  const { flags, positionals } = parseFlags(argv);
+  const rawConfig = await readConfig();
+  const config = resolveConfig(flags, rawConfig);
+  const output = new Output(flags.json ? "json" : "human", flags.quiet);
+  const context = {
+    canPrompt: !flags.json && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY),
+    config,
+    cwd: process.cwd(),
+    flags,
+    output,
+    rawConfig
+  };
+  if (!positionals.length || flags.help) {
+    return { output, result: { data: { help: renderHelp(positionals[0]) }, message: renderHelp(positionals[0]) } };
+  }
+  return { output, result: await dispatch(context, positionals) };
+};
+
+// src/index.ts
+var main = async () => {
+  try {
+    const { output, result } = await runCli(process.argv.slice(2));
+    if (process.argv.includes("--json")) {
+      output.json(result);
+    } else if (result.message) {
+      if (result.message.startsWith("Manage ") || result.message.includes("Usage:")) {
+        console.log(result.message);
+      } else {
+        output.success(result.message);
+      }
+    }
+    process.exit(EXIT_CODES.success);
+  } catch (error) {
+    const cliError = toCliError(error);
+    if (process.argv.includes("--json")) {
+      printJsonError(cliError.message, cliError.type);
+    } else if (isCliError(cliError)) {
+      console.error(cliError.message);
+    }
+    process.exit(cliError.exitCode);
+  }
+};
+void main();

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@dotlabs-hq/env-cli",
+  "version": "1.0.0",
+  "description": "CLI tool for managing environment variables",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "env": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "url": "https://github.com/dotlab-hq/env-cli"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup src/index.ts --format esm --platform node --target node20 --out-dir dist --clean",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.0.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.9.2"
+  }
+}