getmyenv 0.9.0 → 0.9.2

package/README.md

@@ -34,6 +34,58 @@ Prompts and status lines go to stderr, so `export --stdout > .env` stays clean.
 
 Commit `.getmyenv/project.json`. `token.json` and `claim.json` stay local and are gitignored.
 
+<!-- cli:help -->
+Output of `npx getmyenv --help` (0.9.2):
+
+```text
+Usage: getmyenv [options] [command]
+
+Keep using environment variables. Stop managing them as files.
+
+Options:
+  -V, --version               output the version number
+  --api-url <url>             API base URL
+  -h, --help                  display help for command
+
+Commands:
+  start [options]             Set up this folder (same as bare npx getmyenv).
+                              Status when already linked.
+  run [options] [context]     Run a command with a context's variables in its
+                              environment
+  status [options]            Show project, token, contexts and the run command
+  context                     List, create or pick contexts
+  set [options] <pairs...>    Set values: set KEY=VALUE, or set KEY to be
+                              prompted
+  unset [options] <names...>  Remove values from a context
+  ls [options]                Variable names by context with status (never
+                              values)
+  import [options] [file]     Encrypt a .env file and upload it (.env.<slug>
+                              goes to that context)
+  export [options]            Write a context to a plaintext .env file, for
+                              tools that need one
+  guest [options]             Create a guest project without an account. It
+                              works for 30 days. Claim it within 60.
+  claim [options]             Claim a guest project (reads .getmyenv/claim.json,
+                              or asks for the claim code)
+  backup [options]            Write an encrypted backup of open contexts
+  restore [options] <file>    Restore a backup into this folder's project (open
+                              contexts with the same slug)
+  lock [options]              Forget every unlocked context key on this machine
+                              (OS keychain)
+  unlink [options]            Revoke this folder's token and remove local
+                              .getmyenv files
+  help [command]              display help for command
+
+Environment:
+  GETMYENV_TOKEN          Token for CI and servers (instead of .getmyenv/token.json). A server token holds its context key.
+  GETMYENV_API_URL        API base URL (https, or http://localhost)
+  GETMYENV_CONFIG_DIR     Machine identity and cache dir (default ~/.config/getmyenv)
+  GETMYENV_SKIP_UPDATE    Set to 1 to skip the update notice
+  GETMYENV_KEYCHAIN       Set to 0 to always ask for the Vault password
+  GETMYENV_MACHINE_LABEL  Name shown for this machine in access requests
+```
+<!-- /cli:help -->
+
 ## Vault password
 
 Each context has its own key, sealed to your account. Your Vault password opens your account key. For open contexts, after you enter the Vault password in a terminal, the unlocked context keys stay in your OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) for 8 hours. The password is never stored.
@@ -65,7 +117,7 @@ Server tokens are read-only. `set` needs the folder token from browser sign-in,
 ## Open and Read-only
 
 - Open contexts: the CLI can read and write. Browser sign-in gives the folder a token in `.getmyenv/token.json`.
-- Read-only contexts: the CLI can read and export, never write. Set values in the dashboard. Use a server token from Project settings, Tokens (one context, IP allowlist) with `GETMYENV_TOKEN`. Each server token has a new machines rule: ask you on Requests (default), trust machines from its allowed IPs on first read (each entry /24 or narrower, IPv6 /64), or block them. Trusted machines read without asking. `status` shows the rule.
+- Read-only contexts: the CLI can read and export, never write. Only the owner sets Read-only values, in the dashboard. Use a server token from Project settings, Tokens (one context, IP allowlist) with `GETMYENV_TOKEN`. Each server token has a new machines rule: ask you on Requests (default), trust machines from its allowed IPs on first read (each entry /24 or narrower, IPv6 /64), or block them. Trusted machines read without asking. `status` shows the rule.
 
 ## Chaining
 

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+import { Command } from "commander";
 /**
  * Split `run` operands around `--`.
  * `run staging -- npm start`: context staging, command npm start.
@@ -8,4 +9,5 @@ export declare function splitRunArgs(operands: string[], argv: string[], explain
     context?: string;
     command: string[];
 };
+export declare function buildProgram(argv: string[]): Command;
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { CLI_API_OPTION, CLI_DESCRIPTION, cliCommand, cliEnvHelp, } from "@getmyenv/shared";
 import { backupCommand } from "./commands/backup.js";
 import { claimCommand } from "./commands/claim.js";
 import { contextCreateCommand, contextListCommand, contextUseCommand, } from "./commands/context.js";
@@ -14,11 +15,6 @@ import { startCommand } from "./commands/start.js";
 import { statusCommand } from "./commands/status.js";
 import { unlinkCommand } from "./commands/unlink.js";
 import { CLI_VERSION } from "./lib/api.js";
-const CONTEXT_OPTION = [
-    "-c, --context <slug>",
-    "Context to use (default: the server token's context, then project.json, then development)",
-];
-const API_OPTION = ["--api-url <url>", "API base URL"];
 /**
  * Split `run` operands around `--`.
  * `run staging -- npm start`: context staging, command npm start.
@@ -36,23 +32,32 @@ export function splitRunArgs(operands, argv, explain) {
         return { context: operands[0], command: [] };
     return { command: operands };
 }
-export async function runCli(argv) {
+/** A command, its arguments, flags and examples, all from the shared CLI spec. */
+function define(parent, name, withApi = true) {
+    const spec = cliCommand(name);
+    const leaf = spec.name.split(" ").at(-1);
+    const cmd = parent.command(leaf, spec.isDefault ? { isDefault: true } : {}).description(spec.description);
+    for (const a of spec.args)
+        cmd.argument(a.name, a.description ?? "");
+    for (const o of spec.options)
+        cmd.option(o.flags, o.description, o.defaultValue);
+    if (withApi)
+        cmd.option(CLI_API_OPTION.flags, CLI_API_OPTION.description);
+    if (spec.usage)
+        cmd.usage(spec.usage);
+    if (spec.examples) {
+        cmd.addHelpText("after", ["", "Examples:", ...spec.examples.map((e) => `  ${e}`)].join("\n"));
+    }
+    return cmd;
+}
+export function buildProgram(argv) {
     const program = new Command();
     program
         .name("getmyenv")
-        .description("Keep using environment variables. Stop managing them as files.")
+        .description(CLI_DESCRIPTION)
         .version(CLI_VERSION)
-        .option(...API_OPTION)
-        .addHelpText("after", [
-        "",
-        "Environment:",
-        "  GETMYENV_TOKEN          Token for CI and servers (instead of .getmyenv/token.json). A server token holds its context key.",
-        "  GETMYENV_API_URL        API base URL (https, or http://localhost)",
-        "  GETMYENV_CONFIG_DIR     Machine identity and cache dir (default ~/.config/getmyenv)",
-        "  GETMYENV_SKIP_UPDATE    Set to 1 to skip the update notice",
-        "  GETMYENV_KEYCHAIN       Set to 0 to always ask for the Vault password",
-        "  GETMYENV_MACHINE_LABEL  Name shown for this machine in access requests",
-    ].join("\n"))
+        .option(CLI_API_OPTION.flags, CLI_API_OPTION.description)
+        .addHelpText("after", cliEnvHelp())
         .helpCommand(true)
         .action((opts) => startCommand(opts));
     // The root owns --api-url wherever it appears, so hand it to the command that runs.
@@ -62,29 +67,8 @@ export async function runCli(argv) {
             actionCommand.setOptionValue("apiUrl", apiUrl);
         }
     });
-    program
-        .command("start")
-        .description("Set up this folder (same as bare npx getmyenv). Status when already linked.")
-        .option("--template <id>", "Add a template's variables and ask for their values (id or link)")
-        .option(...API_OPTION)
-        .action((opts) => startCommand(opts));
-    program
-        .command("run")
-        .description("Run a command with a context's variables in its environment")
-        .usage("[context] [options] -- <command...>")
-        .addHelpText("after", [
-        "",
-        "Examples:",
-        "  npx getmyenv run -- npm run dev",
-        "  npx getmyenv run staging -- node server.js",
-        "  GETMYENV_TOKEN=<server token> npx getmyenv run production -- node server.js",
-    ].join("\n"))
-        .argument("[context]", "Context slug (same as -c)")
-        .option(...CONTEXT_OPTION)
-        .option("--explain", "List each variable and where its value comes from (names only)")
-        .option("--keep-existing", "Keep variables already set in the parent environment")
-        .option("--allow-missing", "Run even when some variables have no value in this context")
-        .option(...API_OPTION)
+    define(program, "start").action((opts) => startCommand(opts));
+    define(program, "run")
         .allowUnknownOption(true)
         .allowExcessArguments(true)
         .action(async (_ctx, opts, cmd) => {
@@ -94,106 +78,26 @@ export async function runCli(argv) {
         }
         await runCommand({ ...opts, context: opts.context ?? split.context }, split.command);
     });
-    program
-        .command("status")
-        .description("Show project, token, contexts and the run command")
-        .option(...API_OPTION)
-        .action((opts) => statusCommand(opts));
-    const context = program.command("context").description("List, create or pick contexts");
-    context
-        .command("list", { isDefault: true })
-        .description("List contexts (* marks this folder's default)")
-        .option(...API_OPTION)
-        .action((opts) => contextListCommand(opts));
-    context
-        .command("create <name>")
-        .description('Create an open context, e.g. context create "Customer Acme"')
-        .option("--from <slug>", "Copy values from an open context")
-        .option("--use", "Make it this folder's default")
-        .option(...API_OPTION)
-        .action((name, opts) => contextCreateCommand(name, opts));
-    context
-        .command("use <slug>")
-        .description("Set this folder's default context (saved in project.json)")
-        .option(...API_OPTION)
-        .action((slug, opts) => contextUseCommand(slug, opts));
-    program
-        .command("set")
-        .description("Set values: set KEY=VALUE, or set KEY to be prompted")
-        .argument("<pairs...>", "KEY or KEY=VALUE")
-        .option(...CONTEXT_OPTION)
-        .option("--expires <date>", "Expiry date, e.g. 2026-12-31, or never")
-        .option("--stdin", "Read the value of one KEY from stdin (keeps it out of argv)")
-        .option(...API_OPTION)
-        .action((pairs, opts) => setCommand(pairs, opts));
-    program
-        .command("unset")
-        .description("Remove values from a context")
-        .argument("<names...>", "Variable names")
-        .option(...CONTEXT_OPTION)
-        .option("--all", "Delete the variable from every context")
-        .option(...API_OPTION)
-        .action((names, opts) => unsetCommand(names, opts));
-    program
-        .command("ls")
-        .description("Variable names by context with status (never values)")
-        .option(...CONTEXT_OPTION)
-        .option(...API_OPTION)
-        .action((opts) => lsCommand(opts));
-    program
-        .command("import")
-        .description("Encrypt a .env file and upload it (.env.<slug> goes to that context)")
-        .argument("[file]", "Env file (default: .env files in this folder)")
-        .option(...CONTEXT_OPTION)
-        .option("--prune", "Unset values in the context that are not in the file")
-        .option("--dry-run", "Show what would change without uploading")
-        .option("--yes", "Do not ask for confirmation")
-        .option(...API_OPTION)
-        .action((file, opts) => importCommand(file, opts));
-    program
-        .command("export")
-        .description("Write a context to a plaintext .env file, for tools that need one")
-        .option(...CONTEXT_OPTION)
-        .option("-o, --output <file>", "Output file", ".env")
-        .option("--stdout", "Write to stdout instead of a file")
-        .option("--yes", "Change an existing file without asking")
-        .option(...API_OPTION)
-        .action((opts) => exportCommand(opts));
-    program
-        .command("guest")
-        .description("Create a guest project without an account. It works for 30 days. Claim it within 60.")
-        .option("--name <name>", "Project name (default: folder name)")
-        .option(...API_OPTION)
-        .action((opts) => guestCommand(opts));
-    program
-        .command("claim")
-        .description("Claim a guest project (reads .getmyenv/claim.json, or asks for the claim code)")
-        .option(...API_OPTION)
-        .action((opts) => claimCommand(opts));
-    program
-        .command("backup")
-        .description("Write an encrypted backup of open contexts")
-        .option("-o, --output <file>", "Output file (default: <project>.getmyenv-backup)")
-        .option(...API_OPTION)
-        .action((opts) => backupCommand(opts));
-    program
-        .command("restore <file>")
-        .description("Restore a backup into this folder's project (open contexts with the same slug)")
-        .option("--dry-run", "Check the backup and show what would be restored")
-        .option("--yes", "Do not ask for confirmation")
-        .option(...API_OPTION)
-        .action((file, opts) => restoreCommand(file, opts));
-    program
-        .command("lock")
-        .description("Forget every unlocked context key on this machine (OS keychain)")
-        .option(...API_OPTION)
-        .action((opts) => lockCommand(opts));
-    program
-        .command("unlink")
-        .description("Revoke this folder's token and remove local .getmyenv files")
-        .option("--yes", "Do not ask for confirmation")
-        .option(...API_OPTION)
-        .action((opts) => unlinkCommand(opts));
+    define(program, "status").action((opts) => statusCommand(opts));
+    const context = define(program, "context", false);
+    define(context, "context list").action((opts) => contextListCommand(opts));
+    define(context, "context create").action((name, opts) => contextCreateCommand(name, opts));
+    define(context, "context use").action((slug, opts) => contextUseCommand(slug, opts));
+    define(program, "set").action((pairs, opts) => setCommand(pairs, opts));
+    define(program, "unset").action((names, opts) => unsetCommand(names, opts));
+    define(program, "ls").action((opts) => lsCommand(opts));
+    define(program, "import").action((file, opts) => importCommand(file, opts));
+    define(program, "export").action((opts) => exportCommand(opts));
+    define(program, "guest").action((opts) => guestCommand(opts));
+    define(program, "claim").action((opts) => claimCommand(opts));
+    define(program, "backup").action((opts) => backupCommand(opts));
+    define(program, "restore").action((file, opts) => restoreCommand(file, opts));
+    define(program, "lock").action((opts) => lockCommand(opts));
+    define(program, "unlink").action((opts) => unlinkCommand(opts));
+    return program;
+}
+export async function runCli(argv) {
+    const program = buildProgram(argv);
     const first = argv[2];
     if (first &&
         !first.startsWith("-") &&

package/dist/commands/claim.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { GUEST_GRACE_DAYS } from "@getmyenv/shared";
 import { createUserKeys, openSealedKey, sealContextKey, unwrapPrivateKey, wipe, } from "@getmyenv/crypto";
 import { clearClaimFile, ensureGitignoreHasEnv, promptHidden, readClaimFile, readLine, readProjectMeta, writeClaimFile, writeProjectMeta, } from "../lib/fs.js";
 import { readFolderToken, writeFolderToken } from "../lib/credentials.js";
@@ -136,7 +137,7 @@ export async function claimCommand(opts = {}) {
         throw new Error("This claim code is not valid. Check .getmyenv/claim.json or the code shown at creation.");
     }
     if (start.status === "expired") {
-        throw new Error("This guest project expired more than 30 days ago. It can no longer be claimed.");
+        throw new Error(`This guest project expired more than ${GUEST_GRACE_DAYS} days ago. It can no longer be claimed.`);
     }
     if (start.status === "claimed") {
         await resumeClaim(apiUrl, claim);

package/dist/commands/import.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
+import { FACTS } from "@getmyenv/shared";
 import { contextSlugFromEnvFile, ensureGitignoreHasEnv, parseEnvFile, promptConfirm, rootEnvFiles, } from "../lib/fs.js";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { defaultContextSlug, findContext, resolveContext } from "../lib/context.js";
@@ -103,7 +104,7 @@ export async function importCommand(file, opts) {
             continue;
         }
         if (ctx.protection === "locked") {
-            console.error(pc.yellow(`Skipped ${label}: ${ctx.slug} is read-only. Set values in the dashboard.`));
+            console.error(pc.yellow(`Skipped ${label}: ${ctx.slug} is read-only. ${FACTS.readOnlyWho}`));
             skipped++;
             continue;
         }

package/dist/commands/start.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
-import { DEFAULT_CONTEXT_SLUG } from "@getmyenv/shared";
+import { DEFAULT_CONTEXT_SLUG, GUEST_TOTAL_DAYS } from "@getmyenv/shared";
 import { promptChoice, promptConfirm, readClaimFile, readLine, readProjectMeta, rootEnvFiles, writeProjectMeta, } from "../lib/fs.js";
 import { ApiClient, getSessionToken, resolveApiUrl } from "../lib/api.js";
 import { authorizeFolder } from "../lib/authorize.js";
@@ -80,7 +80,7 @@ export async function startSetup(opts) {
         }
         return;
     }
-    const choice = await promptChoice("How do you want to start?", ["Start without an account (guest project, claim within 60 days)", "Sign in"], 0);
+    const choice = await promptChoice("How do you want to start?", [`Start without an account (guest project, claim within ${GUEST_TOTAL_DAYS} days)`, "Sign in"], 0);
     console.error("");
     let context = DEFAULT_CONTEXT_SLUG;
     let dashboardUrl = null;

package/dist/lib/bootstrap.js

@@ -1,4 +1,5 @@
 import pc from "picocolors";
+import { GUEST_GRACE_MS } from "@getmyenv/shared";
 import { ensureGitignoreHasEnv, readClaimFile, readProjectMeta, writeProjectMeta, } from "./fs.js";
 import { ApiClient, ApiError, getSessionToken, resolveApiUrl, } from "./api.js";
 import { assertTokenNotCommitted } from "./credentials.js";
@@ -14,9 +15,9 @@ export function printGuestBanner(who) {
     const DAY = 24 * 60 * 60 * 1000;
     const expires = who.guestExpiresAt ? new Date(who.guestExpiresAt).getTime() : NaN;
     const needClaim = readClaimFile() ? "" : " Needs the claim code and guest passphrase shown at creation.";
-    const plural = (n) => (n === 1 ? "1 day" : `${n} days`);
+    const plural = (n) => `${n} day${n === 1 ? "" : "s"}`;
     if (Number.isFinite(expires) && expires <= Date.now()) {
-        const graceLeft = Math.max(0, Math.ceil((expires + 30 * DAY - Date.now()) / DAY));
+        const graceLeft = Math.max(0, Math.ceil((expires + GUEST_GRACE_MS - Date.now()) / DAY));
         console.error(pc.yellow(`Guest project expired. Values can't change. run works for ${plural(graceLeft)} more. Export or claim it: npx getmyenv claim.${needClaim}\n`));
         return;
     }

package/dist/lib/fs.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import os from "node:os";
 import readline from "node:readline";
 import dotenv from "dotenv";
-import { CONTEXT_SLUG_RE, isValidContextSlug, isValidVariableName, LOCAL_DIR, slugify, } from "@getmyenv/shared";
+import { CONTEXT_SLUG_RE, isValidContextSlug, isValidVariableName, LOCAL_DIR, VAULT_UNLOCK_DURATION, slugify, } from "@getmyenv/shared";
 const SLUG_RE = CONTEXT_SLUG_RE;
 /**
  * Nearest folder at or above cwd with a linked `.getmyenv/`, so commands work
@@ -142,7 +142,7 @@ export function readLine(question) {
 export async function promptHidden(question) {
     const stdin = process.stdin;
     if (!stdin.isTTY) {
-        throw new Error("No terminal to ask for the Vault password. Unlock once in a terminal: open contexts stay unlocked for 8 hours. On servers and in CI, use a server token.");
+        throw new Error(`No terminal to ask for the Vault password. Unlock once in a terminal: open contexts stay unlocked for ${VAULT_UNLOCK_DURATION}. On servers and in CI, use a server token.`);
     }
     // Prompts go to stderr so stdout stays clean for `export --stdout > .env` and pipes.
     const out = process.stderr;

package/dist/lib/keychain.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { VAULT_UNLOCK_MS } from "@getmyenv/shared";
 /**
  * Unlocked open context keys, remembered in the OS keychain (macOS Keychain,
  * Windows Credential Manager, Linux Secret Service) for a few hours so `run`
@@ -6,7 +7,7 @@ import { createHash } from "node:crypto";
  * Never the Vault password or the private key.
  */
 const SERVICE = "getmyenv";
-export const KEYCHAIN_TTL_MS = 8 * 60 * 60 * 1000;
+export const KEYCHAIN_TTL_MS = VAULT_UNLOCK_MS;
 let factoryOverride;
 let accountsOverride;
 /** Tests swap in an in-memory keyring. `null` means no keyring available. */

package/dist/lib/upload.js

@@ -1,12 +1,13 @@
 import { encryptSecret, serializePayload } from "@getmyenv/crypto";
+import { FACTS } from "@getmyenv/shared";
 import { contextKey } from "./vault.js";
 /** Fail fast before prompting or encrypting. Mirrors the server's `checkWrite`, which still enforces it. */
 export function assertWritable(linked, ctx) {
     if (linked.who.token.kind === "server") {
-        throw new Error("Server tokens are read-only. Set values in the dashboard.");
+        throw new Error(`Server tokens are read-only. ${FACTS.readOnlyWho}`);
     }
     if (ctx.protection === "locked") {
-        throw new Error(`${ctx.slug} is read-only. Set values in the dashboard.`);
+        throw new Error(`${ctx.slug} is read-only. ${FACTS.readOnlyWho}`);
     }
 }
 /**

package/dist/lib/vault.d.ts

@@ -7,7 +7,7 @@ import type { Linked } from "./bootstrap.js";
  * Folder and guest tokens: the account (or guest) private key is wrapped with
  * the Vault password (or the guest passphrase in claim.json). It is unwrapped
  * here, opens the sealed context keys, and is wiped. Open context keys may
- * stay in the OS keychain for 8 hours. The private key is never stored.
+ * stay in the OS keychain for VAULT_UNLOCK_HOURS. The private key is never stored.
  *
  * Server tokens: GETMYENV_TOKEN holds the token's own private key. It opens
  * the one context key sealed to that token. No Vault password.

package/dist/lib/vault.js

@@ -1,8 +1,9 @@
 import pc from "picocolors";
 import { createUserKeys, generateContextKey, openSealedKey, sealContextKey, splitServerToken, unwrapPrivateKey, wipe, } from "@getmyenv/crypto";
+import { VAULT_UNLOCK_DURATION } from "@getmyenv/shared";
 import { ApiError } from "./api.js";
 import { resolveVaultPassword } from "./guest-key.js";
-import { KEYCHAIN_TTL_MS, keychainAccount, keychainEnabled, readCachedContextKey, storeCachedContextKeys, } from "./keychain.js";
+import { keychainAccount, keychainEnabled, readCachedContextKey, storeCachedContextKeys, } from "./keychain.js";
 /** One unlock per process: several contexts in one command prompt once. */
 const memo = new Map();
 export function fetchVault(linked) {
@@ -92,7 +93,7 @@ async function remember(account, vault, opened) {
     if (entries.length === 0)
         return;
     if (await storeCachedContextKeys(account, entries)) {
-        console.error(pc.dim(`Unlocked on this machine for ${KEYCHAIN_TTL_MS / 3_600_000} hours (OS keychain). Forget it with: npx getmyenv lock\n`));
+        console.error(pc.dim(`Unlocked on this machine for ${VAULT_UNLOCK_DURATION} (OS keychain). Forget it with: npx getmyenv lock\n`));
     }
 }
 function openAll(vault, privateKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getmyenv",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "CLI for getmyenv, an encrypted store for environment variables and secrets. We store ciphertext only.",
   "type": "module",
   "bin": {
@@ -33,8 +33,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@getmyenv/crypto": "0.4.0",
-    "@getmyenv/shared": "0.6.0",
+    "@getmyenv/crypto": "0.4.1",
+    "@getmyenv/shared": "0.7.0",
     "@napi-rs/keyring": "^2.1.0",
     "commander": "^15.0.0",
     "dotenv": "^16.4.7",