getmyenv 0.13.0 → 0.14.1

package/dist/commands/set.d.ts

@@ -4,9 +4,25 @@ export type SetOpts = {
     expires?: string;
     /** Read the one value from stdin, so it never lands in argv or shell history. */
     stdin?: boolean;
+    /** Prompt for every name with no value in the context. */
+    missing?: boolean;
 };
+/** Names declared in the project with no value in this context, in project order. */
+export declare function missingNames(keys: Array<{
+    name: string;
+    status: Record<string, string>;
+}>, slug: string): string[];
+export declare function parseExpires(raw: string | undefined, now?: Date): string | null | undefined;
 /** `set KEY[=VALUE] ...` Omitted values are prompted without echo. */
 export declare function setCommand(args: string[], opts: SetOpts): Promise<void>;
+/**
+ * Why unset changed nothing. A declared name with no value in the context
+ * stays in the project, and run still asks for it, so point to --all.
+ */
+export declare function unsetNoChangeLines(skipped: string[], keys: Array<{
+    name: string;
+    status: Record<string, string>;
+}>, slug: string, all: boolean): string[];
 export declare function unsetCommand(names: string[], opts: {
     context?: string;
     apiUrl?: string;

package/dist/commands/set.js

@@ -1,5 +1,5 @@
-import pc from "picocolors";
-import { variableNameSchema } from "@getmyenv/shared";
+import { pc, pcErr } from "../lib/colors.js";
+import { ownEnvNameError, plural, suggestVariableName, unsafeEnvWarning, VARIABLE_NAME_HELP, variableNameSchema } from "@getmyenv/shared";
 import { promptHidden } from "../lib/fs.js";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { resolveContext } from "../lib/context.js";
@@ -14,31 +14,57 @@ async function readStdinValue() {
     }
     return Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
 }
+/** Names declared in the project with no value in this context, in project order. */
+export function missingNames(keys, slug) {
+    return keys.filter((k) => (k.status[slug] ?? "missing") === "missing").map((k) => k.name);
+}
+function invalidNameMessage(name) {
+    const hint = suggestVariableName(name);
+    return `Invalid name: ${name}. ${VARIABLE_NAME_HELP}${hint ? ` Did you mean ${hint}?` : ""}`;
+}
 function parsePair(arg) {
     const eq = arg.indexOf("=");
     if (eq <= 0)
         return { name: arg.trim() };
     return { name: arg.slice(0, eq).trim(), value: arg.slice(eq + 1) };
 }
-function parseExpires(raw) {
+/** A date a year from now, as YYYY-MM-DD, for examples that do not age. */
+function exampleDate(now) {
+    const d = new Date(now);
+    d.setUTCFullYear(d.getUTCFullYear() + 1);
+    return d.toISOString().slice(0, 10);
+}
+export function parseExpires(raw, now = new Date()) {
     if (raw === undefined)
         return undefined;
     if (raw === "never" || raw === "")
         return null;
     const d = new Date(raw);
     if (Number.isNaN(d.getTime())) {
-        throw new Error("--expires takes a date like 2026-12-31, or never.");
+        throw new Error(`--expires takes a date like ${exampleDate(now)}, or never.`);
+    }
+    if (d.getTime() <= now.getTime()) {
+        throw new Error(`--expires must be a future date, like ${exampleDate(now)}, or never.`);
     }
     return d.toISOString();
 }
 /** `set KEY[=VALUE] ...` Omitted values are prompted without echo. */
 export async function setCommand(args, opts) {
+    if (opts.missing && (args.length > 0 || opts.stdin)) {
+        throw new Error("--missing asks for every variable with no value. Run it without names or --stdin: npx getmyenv set --missing");
+    }
+    if (!opts.missing && args.length === 0) {
+        throw new Error("Name a variable: npx getmyenv set KEY, or ask for every missing one: npx getmyenv set --missing");
+    }
     const pairs = args.map(parsePair);
     for (const p of pairs) {
         if (!variableNameSchema.safeParse(p.name).success) {
-            throw new Error(`Invalid name: ${p.name}. Use an environment variable name like API_KEY.`);
+            throw new Error(invalidNameMessage(p.name));
         }
     }
+    const own = ownEnvNameError(pairs.map((p) => p.name));
+    if (own)
+        throw new Error(own);
     const expiresAt = parseExpires(opts.expires);
     if (opts.stdin) {
         if (pairs.length !== 1 || pairs[0].value !== undefined) {
@@ -51,9 +77,26 @@ export async function setCommand(args, opts) {
     const linked = await ensureTokenAndLink({ apiUrl: opts.apiUrl });
     const ctx = resolveContext(linked.who, linked.meta, opts.context);
     assertWritable(linked, ctx);
+    if (opts.missing) {
+        const names = missingNames(linked.who.keys, ctx.slug);
+        if (names.length === 0) {
+            console.log(`${pc.green("✓")} Every variable in ${ctx.slug} has a value.`);
+            return;
+        }
+        if (!process.stdin.isTTY) {
+            throw new Error(`${plural(names.length, "variable")} ${names.length === 1 ? "has" : "have"} no value in ${ctx.slug}: ${names.join(", ")}. No terminal to ask in. Ask the human to run npx getmyenv set --missing in a terminal.`);
+        }
+        console.error(pcErr.dim(`${plural(names.length, "variable")} ${names.length === 1 ? "has" : "have"} no value in ${ctx.slug}. Leave one empty to skip it.`));
+        for (const name of names)
+            pairs.push({ name });
+    }
     const values = {};
-    if (opts.stdin)
-        values[pairs[0].name] = await readStdinValue();
+    if (opts.stdin) {
+        const piped = await readStdinValue();
+        if (piped === "")
+            throw new Error(`stdin was empty. Pipe a value, or declare the name with ${pairs[0].name}=`);
+        values[pairs[0].name] = piped;
+    }
     for (const p of pairs) {
         if (opts.stdin)
             break;
@@ -62,9 +105,17 @@ export async function setCommand(args, opts) {
             continue;
         }
         if (!process.stdin.isTTY) {
-            throw new Error(`No value for ${p.name}. Pipe it with --stdin, pass ${p.name}=VALUE, or run in a terminal to be prompted.`);
+            throw new Error(`No value for ${p.name}, and no terminal to ask in. Ask the human to run npx getmyenv set ${p.name} in a terminal, or pass ${p.name}=VALUE, or pipe it with --stdin.`);
         }
-        values[p.name] = await promptHidden(`${p.name} (hidden): `);
+        const typed = await promptHidden(`${p.name} (hidden): `);
+        // With --missing, an empty answer skips the name. It already exists with no value.
+        if (opts.missing && typed === "")
+            continue;
+        values[p.name] = typed;
+    }
+    if (Object.keys(values).length === 0) {
+        console.log(pc.dim("Nothing to set."));
+        return;
     }
     const res = await uploadValues({
         linked,
@@ -76,17 +127,45 @@ export async function setCommand(args, opts) {
         console.log(`${pc.green("✓")} ${name} ${pc.dim(`set in ${ctx.slug}`)}`);
     for (const name of res.declared)
         console.log(`${pc.yellow("○")} ${name} ${pc.dim(`declared, no value in ${ctx.slug}`)}`);
+    // KEY= on a name that already exists: the server keeps it as it is. Say so.
+    for (const [name, value] of Object.entries(values)) {
+        if (value !== "" || res.declared.includes(name))
+            continue;
+        const status = linked.who.keys.find((k) => k.name === name)?.status[ctx.slug];
+        console.log(status && status !== "missing"
+            ? `${pc.dim("=")} ${name} ${pc.dim(`already has a value in ${ctx.slug}. An empty value does not clear it: npx getmyenv unset ${name}`)}`
+            : `${pc.dim("=")} ${name} ${pc.dim(`already declared, no value in ${ctx.slug}`)}`);
+    }
     const newNames = pairs.map((p) => p.name).filter((n) => !linked.who.keys.some((k) => k.name === n));
     if (newNames.length > 0)
         await refreshKnownKeys(linked.apiUrl);
     printDidYouMean(newNames);
     printPublicSecretWarnings(values);
+    const unsafe = unsafeEnvWarning(Object.keys(values));
+    if (unsafe)
+        console.error(pcErr.yellow(unsafe));
     syncFromLinked(linked, { added: [...res.set, ...res.declared] });
 }
+/**
+ * Why unset changed nothing. A declared name with no value in the context
+ * stays in the project, and run still asks for it, so point to --all.
+ */
+export function unsetNoChangeLines(skipped, keys, slug, all) {
+    const declared = all ? [] : skipped.filter((n) => keys.some((k) => k.name === n));
+    const other = skipped.filter((n) => !declared.includes(n));
+    const lines = [];
+    if (declared.length > 0) {
+        const one = declared.length === 1;
+        lines.push(`${declared.join(", ")} ${one ? "has" : "have"} no value in ${slug}. The ${one ? "name stays" : "names stay"} in the project, and run asks for ${one ? "it" : "them"}. Remove ${one ? "it" : "them"}: npx getmyenv unset ${declared.join(" ")} --all`);
+    }
+    if (other.length > 0)
+        lines.push(`No change: ${other.join(", ")}`);
+    return lines;
+}
 export async function unsetCommand(names, opts) {
     for (const n of names) {
         if (!variableNameSchema.safeParse(n).success)
-            throw new Error(`Invalid name: ${n}`);
+            throw new Error(invalidNameMessage(n));
     }
     const linked = await ensureTokenAndLink({ apiUrl: opts.apiUrl });
     const ctx = resolveContext(linked.who, linked.meta, opts.context);
@@ -100,7 +179,7 @@ export async function unsetCommand(names, opts) {
     for (const name of res.removed)
         console.log(`${pc.green("✓")} ${name} ${pc.dim(where)}`);
     const skipped = names.filter((n) => !res.removed.includes(n));
-    if (skipped.length > 0)
-        console.log(pc.dim(`No change: ${skipped.join(", ")}`));
+    for (const line of unsetNoChangeLines(skipped, linked.who.keys, ctx.slug, opts.all === true))
+        console.log(pc.dim(line));
     syncFromLinked(linked, opts.all ? { removed: res.removed } : {});
 }

package/dist/commands/start.js

@@ -1,11 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
-import pc from "picocolors";
-import { DEFAULT_CONTEXT_SLUG, FACTS, GUEST_TOTAL_DAYS, TEMPLATE_FILE, } from "@getmyenv/shared";
+import { pcErr as pc } from "../lib/colors.js";
+import { DEFAULT_CONTEXT_SLUG, FACTS, TEMPLATE_FILE, } 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";
-import { NOT_LINKED_STEPS } from "../lib/bootstrap.js";
+import { notLinkedMessage } from "../lib/bootstrap.js";
 import { readTemplateFile } from "../lib/template-file.js";
 import { createGuestProject, folderNameHint } from "./guest.js";
 import { statusCommand } from "./status.js";
@@ -95,7 +95,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 ${GUEST_TOTAL_DAYS} days)`, "Sign in"], 0);
+    const choice = await promptChoice("How do you want to start?", [`Start without an account (guest project, active while you use it)`, "Sign in"], 0);
     console.error("");
     let context = DEFAULT_CONTEXT_SLUG;
     let dashboardUrl = null;
@@ -171,7 +171,7 @@ export function startChoices(existing, file) {
 async function startFromTemplateFile(file, opts) {
     const n = file.keys.length;
     console.error(`${TEMPLATE_FILE} lists ${n} variable${n === 1 ? "" : "s"}. Values are asked after setup.\n`);
-    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);
+    const choice = await promptChoice("How do you want to start?", [`Start without an account (guest project, active while you use it)`, "Sign in"], 0);
     console.error("");
     const suggested = file.name ?? folderNameHint();
     let project;
@@ -230,8 +230,8 @@ export async function startCommand(opts) {
         return;
     }
     if (!process.stdin.isTTY) {
-        console.log(NOT_LINKED_STEPS);
-        return;
+        // No terminal to set up in: an agent or a script must not read this as success.
+        throw new Error(notLinkedMessage());
     }
     await startSetup({ apiUrl: opts.apiUrl, template });
 }

package/dist/commands/status.js

@@ -1,4 +1,4 @@
-import pc from "picocolors";
+import { pc } from "../lib/colors.js";
 import { NEW_MACHINE_POLICY_LABELS } from "@getmyenv/shared";
 import { isDefaultApiUrl } from "../lib/api.js";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
@@ -8,7 +8,7 @@ import { runLine } from "./start.js";
 const TOKEN_KIND = {
     folder: "folder (open contexts, read and write)",
     guest: "guest (Development, read and write)",
-    server: "server (one read-only context)",
+    server: "server (one Read-only context)",
 };
 /** Project, token, contexts with value counts, and the run command. Names only. */
 export async function statusCommand(opts = {}) {
@@ -36,7 +36,7 @@ export async function statusCommand(opts = {}) {
             return s === "set" || s === "expiring_soon";
         }).length;
         const marker = c.slug === current ? pc.green("*") : " ";
-        const lock = c.protection === "locked" ? pc.yellow(" read-only") : "";
+        const lock = c.protection === "locked" ? pc.yellow(" Read-only") : "";
         const name = c.name.toLowerCase() === c.slug ? "" : pc.dim(`  ${c.name}`);
         console.log(`  ${marker} ${c.slug.padEnd(width)}  ${set}/${total} set${lock}${name}`);
     }

package/dist/commands/template.js

@@ -1,4 +1,4 @@
-import pc from "picocolors";
+import { pcErr as pc } from "../lib/colors.js";
 import { linkDomain, parseTemplateRef, } from "@getmyenv/shared";
 import { promptHidden } from "../lib/fs.js";
 import { ApiClient, getSessionToken, resolveApiUrl } from "../lib/api.js";
@@ -62,7 +62,7 @@ export async function applyTemplateFile(file, opts) {
     const todo = missingIn(file.keys, linked, ctx);
     if (todo.length > 0) {
         console.error(`No value yet in ${ctx.slug}: ${todo.map((k) => k.name).join(", ")}`);
-        console.error("Set each one: npx getmyenv set NAME\n");
+        console.error(`Set ${todo.length === 1 ? "it" : "them"} in a terminal: npx getmyenv set --missing\n`);
     }
     return { context: ctx.slug };
 }
@@ -109,7 +109,7 @@ export async function askMissingValues(keys, linked, ctx) {
     }
     const skipped = todo.filter((k) => !pairs[k.name]).map((k) => k.name);
     if (skipped.length > 0) {
-        console.error(pc.dim(`No value yet: ${skipped.join(", ")}. Set later with npx getmyenv set NAME`));
+        console.error(pc.dim(`No value yet: ${skipped.join(", ")}. Set later in a terminal: npx getmyenv set --missing`));
     }
     console.error("");
 }

package/dist/commands/unlink.d.ts

@@ -1,8 +1,17 @@
+export type UnlinkOpts = {
+    apiUrl?: string;
+    yes?: boolean;
+    local?: boolean;
+};
+/** Why the revoke failed, and the ways on. Nothing was removed. */
+export declare function revokeFailedMessage(opts: {
+    unreachable: boolean;
+    guest: boolean;
+}): string;
 /**
  * Unlink this folder: revoke its token and remove local getmyenv files.
- * The project, its contexts and values stay.
+ * The project, its contexts and values stay. A committed project.json stays
+ * when this machine has no token: it belongs to the repo, not to this machine.
+ * --local removes the files without revoking the token.
  */
-export declare function unlinkCommand(opts: {
-    apiUrl?: string;
-    yes?: boolean;
-}): Promise<void>;
+export declare function unlinkCommand(opts: UnlinkOpts): Promise<void>;

package/dist/commands/unlink.js

@@ -1,37 +1,85 @@
 import fs from "node:fs";
 import path from "node:path";
-import pc from "picocolors";
-import { getLocalDir, promptConfirm, readClaimFile, readProjectMeta } from "../lib/fs.js";
-import { clearFolderToken, readFolderToken } from "../lib/credentials.js";
+import { pc } from "../lib/colors.js";
+import { TOKEN_ENDED_CODE } from "@getmyenv/shared";
+import { clearClaimFile, getLocalDir, promptConfirm, readClaimFile, readProjectMeta, } from "../lib/fs.js";
+import { clearFolderToken, isTrackedByGit, readFolderToken, readFolderTokenLenient, tokenFilePath, } from "../lib/credentials.js";
 import { clearCachedKeys, keychainAccount } from "../lib/keychain.js";
 import { ApiClient, ApiError, resolveApiUrl } from "../lib/api.js";
+/** project.json as far as it can be read. A broken one is still removed with the token. */
+function readMetaLenient() {
+    try {
+        return readProjectMeta();
+    }
+    catch {
+        return null;
+    }
+}
+/** token.json that exists but cannot be read as a token. Its token cannot be revoked from here. */
+function tokenFileIsBroken() {
+    if (!fs.existsSync(tokenFilePath()))
+        return false;
+    try {
+        return readFolderToken() === null;
+    }
+    catch {
+        return true;
+    }
+}
+/** Why the revoke failed, and the ways on. Nothing was removed. */
+export function revokeFailedMessage(opts) {
+    const first = opts.unreachable
+        ? "Could not reach the server to revoke this folder's token. Nothing was removed."
+        : "Could not revoke the token on the server. Nothing was removed.";
+    const retry = opts.guest
+        ? "Try again when the server is reachable."
+        : "Try again, or revoke it in Project settings, Tokens first.";
+    return `${first} ${retry} To remove only the local files: npx getmyenv unlink --local`;
+}
 /**
  * Unlink this folder: revoke its token and remove local getmyenv files.
- * The project, its contexts and values stay.
+ * The project, its contexts and values stay. A committed project.json stays
+ * when this machine has no token: it belongs to the repo, not to this machine.
+ * --local removes the files without revoking the token.
  */
 export async function unlinkCommand(opts) {
-    const meta = readProjectMeta();
-    const folder = readFolderToken();
+    const meta = readMetaLenient();
+    const folder = readFolderTokenLenient();
+    const brokenToken = tokenFileIsBroken();
     const projectFile = path.join(getLocalDir(), "project.json");
-    if (!folder && !meta?.projectId && !fs.existsSync(projectFile)) {
+    const hasToken = Boolean(folder) || brokenToken;
+    const keepProjectFile = !hasToken && fs.existsSync(projectFile) && isTrackedByGit(projectFile);
+    if (!hasToken && !meta?.projectId && !fs.existsSync(projectFile)) {
         console.log(pc.dim("This folder is not linked."));
         return;
     }
     if (!opts.yes && !process.stdin.isTTY) {
-        throw new Error("Unlink revokes this folder's token. Without a terminal, pass --yes.");
+        throw new Error(folder && !opts.local
+            ? "Unlink revokes this folder's token. Without a terminal, pass --yes."
+            : "Unlink removes this folder's .getmyenv files. Without a terminal, pass --yes.");
     }
     if (!opts.yes) {
         const label = meta?.projectName ?? meta?.projectId ?? "this folder";
-        const tokenLine = readClaimFile()
-            ? "Removes .getmyenv files except claim.json. The guest token stays, so claim still works."
-            : "Revokes this folder's token and removes .getmyenv files.";
-        const ok = await promptConfirm(`Unlink ${label}? ${tokenLine} The project and its values stay.`, { defaultYes: false });
+        const tokenLine = !hasToken
+            ? "This machine has no token for it. Removes the local .getmyenv files."
+            : readClaimFile()
+                ? "Removes .getmyenv files except claim.json. The guest token stays, so claim still works."
+                : opts.local
+                    ? "Removes .getmyenv files without revoking the token."
+                    : "Revokes this folder's token and removes .getmyenv files.";
+        const ok = await promptConfirm(`Unlink ${label}? ${tokenLine} The project and its values stay.`, {
+            defaultYes: false,
+        });
         if (!ok) {
             console.log(pc.dim("Kept."));
             return;
         }
     }
-    if (folder) {
+    let guestEnded = false;
+    if (folder && opts.local) {
+        console.log(pc.yellow("The token was not revoked. It keeps working on the server until it expires or its project ends. Revoke it in Project settings, Tokens."));
+    }
+    else if (folder) {
         try {
             const res = await new ApiClient(resolveApiUrl(opts.apiUrl), folder.token).request("DELETE", "/api/cli/token");
             if (res?.revoked === false) {
@@ -45,22 +93,36 @@ export async function unlinkCommand(opts) {
             // 401/404: the token is already gone on the server. Anything else keeps
             // token.json, so a still-valid token is never left without a local copy.
             if (!(err instanceof ApiError && (err.status === 401 || err.status === 404))) {
-                throw new Error("Could not revoke the token on the server. Nothing was removed. Try again, or revoke it in Project settings, Tokens first.");
+                throw new Error(revokeFailedMessage({
+                    unreachable: err instanceof ApiError && err.status === 0,
+                    guest: readClaimFile() !== null,
+                }));
             }
-            console.log(pc.dim("Token was already revoked."));
+            console.log(pc.dim("The token already no longer works on the server."));
+            // A guest token only ends when its project was claimed or deleted. claim.json is no use then.
+            guestEnded = err.code === TOKEN_ENDED_CODE && readClaimFile() !== null;
         }
     }
+    else if (brokenToken) {
+        console.log(pc.yellow("token.json was not valid, so its token could not be revoked from here. If it held one, revoke it in Project settings, Tokens."));
+    }
     const projectId = meta?.projectId ?? folder?.projectId;
     if (projectId && (await clearCachedKeys(keychainAccount(resolveApiUrl(opts.apiUrl), projectId)))) {
         console.log(`${pc.green("✓")} Removed the unlocked keys from the OS keychain`);
     }
     if (clearFolderToken())
         console.log(`${pc.green("✓")} Removed token.json`);
-    if (fs.existsSync(projectFile)) {
+    if (keepProjectFile) {
+        console.log(pc.dim("Kept project.json. It is committed, so every clone knows its project."));
+    }
+    else if (fs.existsSync(projectFile)) {
         fs.unlinkSync(projectFile);
         console.log(`${pc.green("✓")} Removed project.json`);
     }
-    if (readClaimFile()) {
+    if (guestEnded && clearClaimFile()) {
+        console.log(`${pc.green("✓")} Removed claim.json. The guest project was claimed or deleted, so it has no use.`);
+    }
+    else if (readClaimFile()) {
         console.log(pc.yellow("Kept claim.json. It holds the claim code and guest passphrase. Delete it if you do not need the project."));
     }
     try {

package/dist/lib/api-url.d.ts

@@ -8,6 +8,8 @@ export declare function apiUrlForDisk(url: string | undefined | null): string |
 export declare function isLocalHost(hostname: string): boolean;
 /** https anywhere, http only for localhost. Returns the parsed URL or null. */
 export declare function parseSafeUrl(raw: string): URL | null;
+/** GETMYENV_PUSH_API_URL replaces the Vercel or Netlify API base, for tests. */
+export declare function pushApiBase(fallback: string, env?: string | undefined): string;
 /**
  * Pick the API base: --api-url, then GETMYENV_API_URL, then the gitignored
  * token.json, then production. project.json is committed, so it is never read.

package/dist/lib/api-url.js

@@ -36,6 +36,16 @@ export function parseSafeUrl(raw) {
         return url;
     return null;
 }
+/** GETMYENV_PUSH_API_URL replaces the Vercel or Netlify API base, for tests. */
+export function pushApiBase(fallback, env = process.env.GETMYENV_PUSH_API_URL) {
+    const raw = env?.trim();
+    if (!raw)
+        return fallback;
+    if (!parseSafeUrl(raw)) {
+        throw new Error(`Refusing GETMYENV_PUSH_API_URL ${raw}. Use https, or http://localhost for local tests.`);
+    }
+    return normalizeApiBase(raw);
+}
 /**
  * Pick the API base: --api-url, then GETMYENV_API_URL, then the gitignored
  * token.json, then production. project.json is committed, so it is never read.

package/dist/lib/api.d.ts

@@ -5,7 +5,25 @@ import type { NewMachinePolicy } from "@getmyenv/shared";
 /** From package.json, which ships with the package: src/lib and dist/lib are both two levels down. */
 export declare const CLI_VERSION: string;
 export { isDefaultApiUrl, parseSafeUrl } from "./api-url.js";
-export declare const API_TIMEOUT_MS = 30000;
+/** Short on purpose: a stuck process keeps npx's cache lock, so a second `npx getmyenv` waits silently. */
+export declare const API_TIMEOUT_MS = 8000;
+/** A request still running after this prints one "Contacting" line on stderr. */
+export declare const CONTACTING_AFTER_MS = 1000;
+/** Error thrown when a request runs past `API_TIMEOUT_MS`, headers and body together. */
+export declare class RequestTimeoutError extends Error {
+    constructor();
+}
+/**
+ * Runs `work` with an abort signal and a hard deadline. The deadline rejects even
+ * if the socket ignores the abort, and covers reading the body, not only the
+ * headers. Timers are cleared when `work` settles, so nothing outlives the request.
+ */
+export declare function withDeadline<T>(work: (signal: AbortSignal) => Promise<T>, opts?: {
+    timeoutMs?: number;
+    contacting?: string;
+}): Promise<T>;
+/** Test hook: lets the "Contacting" line print again. */
+export declare function resetContactingForTests(): void;
 export type Protection = "open" | "locked";
 export type ValueStatus = "set" | "expiring_soon" | "expired" | "missing";
 export type ContextInfo = {
@@ -45,7 +63,9 @@ export type WhoamiResponse = {
 };
 export declare class ApiError extends Error {
     status: number;
-    constructor(message: string, status: number);
+    /** Machine-readable reason from the server, like `token_ended`. */
+    code?: string;
+    constructor(message: string, status: number, code?: string);
 }
 export declare function resolveApiUrl(cliOverride?: string): string;
 export declare class ApiClient {