getmyenv 0.10.0 → 0.11.1

package/README.md

@@ -32,10 +32,21 @@ npx getmyenv run staging -- npm start # or pick one
 
 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.
+Commit `.getmyenv/project.json` and `.getmyenv/template.json`. `token.json` and `claim.json` stay local and are gitignored. `template.json` lists the variable names, never values. In a fresh clone, `npx getmyenv` can start a new project from it and asks for each value.
+
+What the CLI writes. Not every folder has all four:
+
+```text
+my-app/
+  .getmyenv/
+    project.json   committed. Project id, name and the folder's default context. Written by setup, guest or sign-in.
+    template.json  committed. Variable names, never values. Written once the project has a variable name.
+    token.json     gitignored. The folder token. Written by sign-in or guest. Not used with GETMYENV_TOKEN.
+    claim.json     gitignored, guest only. Claim code and guest passphrase. Keep it private. Written by guest. Deleted by claim.
+```
 
 <!-- cli:help -->
-Output of `npx getmyenv --help` (0.10.0):
+Output of `npx getmyenv --help` (0.11.1):
 
 ```text
 Usage: getmyenv [options] [command]
@@ -88,7 +99,7 @@ Environment:
 
 ## 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.
+One Vault password per account unlocks your private key on your device. Each context has its own key, and each reader gets their own sealed copy. Forgot the Vault password? Your recovery code sets a new one in the dashboard. 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.
 
 - `npx getmyenv lock` removes every entry. `unlink` removes this project's.
 - Server tokens hold their context key and never ask.

package/dist/commands/backup.js

@@ -33,6 +33,6 @@ export async function backupCommand(opts) {
     writePrivateFile(out, serializeBackup(envelope), { overwrite: false });
     console.log(`${pc.green("✓")} Encrypted backup: ${out} (${data.values.length} values, ${data.contexts.length} open contexts)`);
     console.log(pc.dim(data.recoveryWrappedKey
-        ? "It opens with your current Vault password or recovery code. Read-only contexts are backed up from the dashboard."
-        : "It opens with your current Vault password. Read-only contexts are backed up from the dashboard."));
+        ? "It opens with your Vault password or recovery code as they are now, not with newer ones. Read-only contexts are backed up from the dashboard."
+        : "It opens with your Vault password as it is now, not with a newer one. Read-only contexts are backed up from the dashboard."));
 }

package/dist/commands/guest.d.ts

@@ -2,13 +2,17 @@ export type GuestOpts = {
     name?: string;
     apiUrl?: string;
 };
+type CreateGuestOpts = GuestOpts & {
+    /** New project from the template file: project.json may point to another project, and is replaced once this one exists. */
+    replaceProjectMeta?: boolean;
+};
 export declare function folderNameHint(): string;
 /**
  * Create an unclaimed guest project with one open context, Development.
  * Writes token.json and claim.json (gitignored) and project.json (committed).
  * claim.json holds the guest passphrase that wraps the guest key until claim.
  */
-export declare function createGuestProject(opts?: GuestOpts): Promise<{
+export declare function createGuestProject(opts?: CreateGuestOpts): Promise<{
     projectId: string;
     projectName: string;
     guestExpiresAt: string;
@@ -16,3 +20,4 @@ export declare function createGuestProject(opts?: GuestOpts): Promise<{
 /** The steps printed after guest, in plain text. Runtime first, export only as an alternative. */
 export declare function guestNextLines(): string[];
 export declare function guestCommand(opts?: GuestOpts): Promise<void>;
+export {};

package/dist/commands/guest.js

@@ -2,10 +2,11 @@ import { randomBytes } from "node:crypto";
 import path from "node:path";
 import pc from "picocolors";
 import { createUserKeys, wipe } from "@getmyenv/crypto";
-import { FACTS } from "@getmyenv/shared";
+import { FACTS, TEMPLATE_FILE } from "@getmyenv/shared";
 import { ensureGitignoreHasEnv, readProjectMeta, writeClaimFile, writeProjectMeta, } from "../lib/fs.js";
 import { readFolderToken, writeFolderToken } from "../lib/credentials.js";
 import { ApiClient, resolveApiUrl } from "../lib/api.js";
+import { readTemplateFile } from "../lib/template-file.js";
 export function folderNameHint() {
     return path.basename(process.cwd()) || "project";
 }
@@ -15,7 +16,7 @@ export function folderNameHint() {
  * claim.json holds the guest passphrase that wraps the guest key until claim.
  */
 export async function createGuestProject(opts = {}) {
-    if (readFolderToken() || readProjectMeta()?.projectId) {
+    if (readFolderToken() || (readProjectMeta()?.projectId && !opts.replaceProjectMeta)) {
         throw new Error("This folder is already linked. Run: npx getmyenv   (or npx getmyenv unlink first)");
     }
     const apiUrl = resolveApiUrl(opts.apiUrl);
@@ -50,14 +51,14 @@ export async function createGuestProject(opts = {}) {
     ensureGitignoreHasEnv();
     const daysLeft = Math.max(0, Math.ceil((new Date(created.guestExpiresAt).getTime() - Date.now()) / 86_400_000));
     console.error(`${pc.green("✓")} Guest project ${pc.bold(created.projectName)}. Context: development.`);
-    console.error(pc.dim(`Expires in ${daysLeft} days unless claimed. Commit .getmyenv/project.json. token.json and claim.json stay local.`));
+    console.error(pc.dim(`Expires in ${daysLeft} days unless claimed. ${FACTS.committedFiles}`));
     if (process.stdin.isTTY) {
         console.error(pc.dim("claim.json holds the claim code and guest passphrase. Shown once, save them to claim later:"));
         console.error(`  ${pc.dim("Claim code:")}       ${created.claimCode}`);
         console.error(`  ${pc.dim("Guest passphrase:")} ${passphrase}\n`);
     }
     else {
-        console.error(pc.dim(`claim.json holds the claim code and guest passphrase. It is the only copy. Keep it private. ${FACTS.claimLoss}\n`));
+        console.error(pc.dim(`claim.json holds the claim code and guest passphrase. It is the only copy. Keep it private. ${FACTS.claimLoss} ${FACTS.templateFileRecovery}\n`));
     }
     return created;
 }
@@ -87,7 +88,16 @@ function colorNextLine(line) {
 }
 export async function guestCommand(opts = {}) {
     console.error(pc.bold("\ngetmyenv guest\n"));
-    await createGuestProject(opts);
+    const read = readTemplateFile();
+    if (read && !read.ok)
+        console.error(pc.yellow(`${TEMPLATE_FILE} is not valid (${read.reason}). Not used.\n`));
+    const file = read?.ok ? read.file : null;
+    const name = opts.name ?? file?.name;
+    await createGuestProject({ ...opts, ...(name ? { name } : {}) });
+    if (file && file.keys.length > 0) {
+        const { applyTemplateFile } = await import("./template.js");
+        await applyTemplateFile(file, { apiUrl: opts.apiUrl, ask: false });
+    }
     for (const line of guestNextLines())
         console.error(colorNextLine(line));
     console.error("");

package/dist/commands/import.js

@@ -7,6 +7,7 @@ import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { defaultContextSlug, findContext, resolveContext } from "../lib/context.js";
 import { confirmDiff } from "../lib/confirm.js";
 import { printDidYouMean } from "../lib/known-keys.js";
+import { syncFromLinked } from "../lib/template-file.js";
 import { uploadValues } from "../lib/upload.js";
 import { runLine } from "./start.js";
 /** `.env` before `.env.local`, so local files win on merge. */
@@ -96,6 +97,7 @@ export async function importCommand(file, opts) {
     let imported = 0;
     let changed = 0;
     let skipped = 0;
+    const added = [];
     for (const target of targets) {
         const label = target.files.map((f) => path.relative(process.cwd(), f) || f).join(" + ");
         const ctx = await ensureTargetContext(linked, target.slug, opts);
@@ -153,10 +155,12 @@ export async function importCommand(file, opts) {
         });
         imported += res.set.length;
         changed += res.set.length + res.declared.length + res.pruned.length;
+        added.push(...res.set, ...res.declared);
         console.error(`${pc.green("✓")} ${res.set.length} set, ${res.declared.length} declared${res.pruned.length ? `, ${res.pruned.length} unset` : ""} in ${ctx.slug}\n`);
     }
     if (opts.dryRun)
         return;
+    syncFromLinked(linked, { added });
     if (changed === 0 && skipped > 0) {
         throw new Error("Nothing was imported. See the skipped files above.");
     }

package/dist/commands/ls.js

@@ -1,6 +1,7 @@
 import pc from "picocolors";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { resolveContext } from "../lib/context.js";
+import { syncFromLinked } from "../lib/template-file.js";
 const CELL = {
     set: "set",
     expiring_soon: "expiring",
@@ -17,6 +18,7 @@ function paint(status, text) {
 /** Key names by context with status. Never values. */
 export async function lsCommand(opts) {
     const { who, meta } = await ensureTokenAndLink({ apiUrl: opts.apiUrl, quiet: true });
+    syncFromLinked({ who });
     const contexts = opts.context ? [resolveContext(who, meta, opts.context)] : who.contexts;
     if (who.keys.length === 0) {
         console.log(pc.dim("No variables yet. Add one: npx getmyenv set API_KEY"));

package/dist/commands/restore.js

@@ -5,6 +5,7 @@ import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { findContext } from "../lib/context.js";
 import { promptConfirm } from "../lib/fs.js";
 import { resolveVaultPassword } from "../lib/guest-key.js";
+import { syncFromLinked } from "../lib/template-file.js";
 import { writeKey } from "../lib/vault.js";
 /**
  * Restore a backup into this folder's project. The backup opens locally with
@@ -100,6 +101,7 @@ export async function restoreCommand(file, opts) {
         values,
         keyVersions,
     });
+    syncFromLinked(linked, { added: [...envelope.keys, ...values.map((v) => v.key)] });
     const skipped = [...perContext.keys()].filter((slug) => !writable(slug));
     console.log(`${pc.green("✓")} Restored ${res.restored} values into ${res.projectName}`);
     if (skipped.length > 0) {

package/dist/commands/set.js

@@ -4,6 +4,7 @@ import { promptHidden } from "../lib/fs.js";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { resolveContext } from "../lib/context.js";
 import { printDidYouMean } from "../lib/known-keys.js";
+import { syncFromLinked } from "../lib/template-file.js";
 import { assertWritable, uploadValues } from "../lib/upload.js";
 async function readStdinValue() {
     const chunks = [];
@@ -75,6 +76,7 @@ export async function setCommand(args, opts) {
     for (const name of res.declared)
         console.log(`${pc.yellow("○")} ${name} ${pc.dim(`declared, no value in ${ctx.slug}`)}`);
     printDidYouMean(pairs.map((p) => p.name).filter((n) => !linked.who.keys.some((k) => k.name === n)));
+    syncFromLinked(linked, { added: [...res.set, ...res.declared] });
 }
 export async function unsetCommand(names, opts) {
     for (const n of names) {
@@ -95,4 +97,5 @@ export async function unsetCommand(names, opts) {
     const skipped = names.filter((n) => !res.removed.includes(n));
     if (skipped.length > 0)
         console.log(pc.dim(`No change: ${skipped.join(", ")}`));
+    syncFromLinked(linked, opts.all ? { removed: res.removed } : {});
 }

package/dist/commands/start.d.ts

@@ -1,4 +1,5 @@
-import { type PublicTemplate } from "@getmyenv/shared";
+import { type PublicTemplate, type TemplateFile } from "@getmyenv/shared";
+import { type ProjectMeta } from "../lib/fs.js";
 /** Best guess at the app's start command, for the printed `run` line. */
 export declare function suggestedStartCommand(cwd?: string): string;
 export declare function runLine(context: string | null, cwd?: string, startCommand?: string | null): string;
@@ -11,6 +12,8 @@ export declare function startSetup(opts: {
     thenContinue?: boolean;
     template?: PublicTemplate;
 }): Promise<void>;
+/** The two ways to start when project.json and template.json both exist. Sign in comes first. */
+export declare function startChoices(existing: ProjectMeta, file: TemplateFile): [string, string];
 /**
  * Bare `getmyenv`: setup when unlinked (terminal only), status when linked.
  * With --template, add the template's names and ask for their values.

package/dist/commands/start.js

@@ -1,14 +1,15 @@
 import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
-import { DEFAULT_CONTEXT_SLUG, GUEST_TOTAL_DAYS } from "@getmyenv/shared";
+import { DEFAULT_CONTEXT_SLUG, FACTS, GUEST_TOTAL_DAYS, 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 { readTemplateFile } from "../lib/template-file.js";
 import { createGuestProject, folderNameHint } from "./guest.js";
 import { statusCommand } from "./status.js";
-import { applyTemplate, fetchTemplate, printTemplate } from "./template.js";
+import { applyTemplate, applyTemplateFile, fetchTemplate, printTemplate } from "./template.js";
 /** Best guess at the app's start command, for the printed `run` line. */
 export function suggestedStartCommand(cwd = process.cwd()) {
     const pkgFile = path.join(cwd, "package.json");
@@ -70,6 +71,20 @@ export async function startSetup(opts) {
     if (readClaimFile()) {
         throw new Error("This folder has a guest project (claim.json) but no token on this machine. Claim it: npx getmyenv claim");
     }
+    const file = opts.template ? null : loadTemplateFile();
+    if (file && existing?.projectId) {
+        const choices = startChoices(existing, file);
+        const pick = await promptChoice("How do you want to start?", choices, 0);
+        console.error("");
+        if (pick === 1) {
+            await startFromTemplateFile(file, { apiUrl, previous: existing, thenContinue: opts.thenContinue });
+            return;
+        }
+    }
+    else if (file) {
+        await startFromTemplateFile(file, { apiUrl, thenContinue: opts.thenContinue });
+        return;
+    }
     if (existing?.projectId) {
         console.error(`This folder uses ${pc.bold(existing.projectName ?? existing.projectId)}. Sign in to get a token.\n`);
         await authorizeFolder({ apiUrl });
@@ -104,18 +119,7 @@ export async function startSetup(opts) {
             printRunLine(applied.context, opts.template.startCommand);
         return;
     }
-    const files = rootEnvFiles();
-    if (files.length > 0) {
-        const rel = files.map((f) => path.basename(f)).join(", ");
-        const ok = await promptConfirm(`Import ${rel}? Values are encrypted before upload.`, {
-            defaultYes: true,
-        });
-        if (ok) {
-            const { importCommand } = await import("./import.js");
-            await importCommand(undefined, { apiUrl, yes: true, noRunLine: true });
-        }
-    }
-    else {
+    if (!(await offerEnvImport(apiUrl))) {
         console.error("No .env file in this folder. Add values with:\n");
         console.error(pc.cyan("  npx getmyenv set API_KEY"));
         if (dashboardUrl)
@@ -125,6 +129,83 @@ export async function startSetup(opts) {
     if (!opts.thenContinue)
         printRunLine(context);
 }
+/** Offer to import the .env files in this folder. False when there are none. */
+async function offerEnvImport(apiUrl) {
+    const files = rootEnvFiles();
+    if (files.length === 0)
+        return false;
+    const rel = files.map((f) => path.basename(f)).join(", ");
+    const ok = await promptConfirm(`Import ${rel}? Values are encrypted before upload.`, {
+        defaultYes: true,
+    });
+    if (ok) {
+        const { importCommand } = await import("./import.js");
+        await importCommand(undefined, { apiUrl, yes: true, noRunLine: true });
+    }
+    return true;
+}
+/** A template file that cannot be read is reported and not used. */
+function loadTemplateFile() {
+    const read = readTemplateFile();
+    if (!read)
+        return null;
+    if (!read.ok) {
+        console.error(pc.yellow(`${TEMPLATE_FILE} is not valid (${read.reason}). Setup continues without it.\n`));
+        return null;
+    }
+    return read.file;
+}
+/** The two ways to start when project.json and template.json both exist. Sign in comes first. */
+export function startChoices(existing, file) {
+    const n = file.keys.length;
+    return [
+        `Sign in to ${existing.projectName ?? existing.projectId}`,
+        `New project from ${TEMPLATE_FILE} (${n} variable${n === 1 ? "" : "s"}). ${FACTS.templateFileNewProject}`,
+    ];
+}
+/**
+ * A new project with the names in the template file: guest or sign in, then
+ * the .env import offer, then the names are declared and each missing value
+ * is asked. project.json changes only once the new project exists.
+ */
+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);
+    console.error("");
+    const suggested = file.name ?? folderNameHint();
+    let project;
+    let fresh;
+    if (choice === 0) {
+        const name = (await readLine(`Project name ${pc.dim(`[${suggested}]`)}: `)).trim() || suggested;
+        const created = await createGuestProject({
+            name,
+            apiUrl: opts.apiUrl,
+            replaceProjectMeta: Boolean(opts.previous?.projectId),
+        });
+        project = { id: created.projectId, name: created.projectName };
+        fresh = true;
+    }
+    else {
+        const who = await authorizeFolder({ apiUrl: opts.apiUrl, newProject: { name: suggested } });
+        const meta = readProjectMeta();
+        if (meta)
+            writeProjectMeta({ ...meta, context: defaultContextFor(who) });
+        project = who.project;
+        fresh = !who.token.member && who.keys.length === 0;
+    }
+    const before = opts.previous;
+    if (before?.projectId && before.projectId !== project.id) {
+        console.error(pc.dim(`project.json now points to ${project.name}. It pointed to ${before.projectName ?? before.projectId}.`));
+    }
+    if (fresh) {
+        console.error(`New project ${pc.bold(project.name)} with the names from ${TEMPLATE_FILE}. ${FACTS.templateFileNewProject}\n`);
+    }
+    await offerEnvImport(opts.apiUrl);
+    const applied = await applyTemplateFile(file, { apiUrl: opts.apiUrl });
+    if (!opts.thenContinue)
+        printRunLine(applied.context, file.startCommand);
+}
 function printRunLine(context, startCommand) {
     console.error("Start your app with:\n");
     console.error(pc.cyan(`  ${runLine(context, process.cwd(), startCommand)}\n`));

package/dist/commands/status.js

@@ -3,6 +3,7 @@ import { NEW_MACHINE_POLICY_LABELS } from "@getmyenv/shared";
 import { isDefaultApiUrl } from "../lib/api.js";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { defaultContextSlug } from "../lib/context.js";
+import { syncFromLinked } from "../lib/template-file.js";
 import { runLine } from "./start.js";
 const TOKEN_KIND = {
     folder: "folder (open contexts, read and write)",
@@ -12,6 +13,7 @@ const TOKEN_KIND = {
 /** Project, token, contexts with value counts, and the run command. Names only. */
 export async function statusCommand(opts = {}) {
     const { who, apiUrl, meta } = await ensureTokenAndLink({ apiUrl: opts.apiUrl });
+    syncFromLinked({ who });
     const current = defaultContextSlug(who, meta);
     console.log(`${pc.bold(who.project.name)}${who.user ? pc.dim(`  ${who.user.email}`) : ""}`);
     console.log(pc.dim(who.token.member

package/dist/commands/template.d.ts

@@ -1,4 +1,6 @@
-import { type PublicTemplate } from "@getmyenv/shared";
+import { type PublicTemplate, type TemplateFile, type TemplateKey } from "@getmyenv/shared";
+import { type ContextInfo } from "../lib/api.js";
+import { type Linked } from "../lib/bootstrap.js";
 /** Load a public template by id or URL. No token needed. */
 export declare function fetchTemplate(ref: string, apiUrl?: string): Promise<PublicTemplate>;
 export declare function printTemplate(template: PublicTemplate): void;
@@ -11,3 +13,19 @@ export declare function applyTemplate(template: PublicTemplate, opts: {
 }): Promise<{
     context: string;
 }>;
+/**
+ * Declare the template file's names in the linked project, then ask for each
+ * value that is still missing. Without a terminal, list them instead.
+ * Values already set, for example from a .env import, are not touched.
+ */
+export declare function applyTemplateFile(file: TemplateFile, opts: {
+    apiUrl?: string;
+    ask?: boolean;
+}): Promise<{
+    context: string;
+}>;
+/**
+ * Ask for each value still missing in ctx, hidden. Enter skips one and sends
+ * nothing. `linked` must be fresh, so values set a moment ago are not asked.
+ */
+export declare function askMissingValues(keys: TemplateKey[], linked: Linked, ctx: ContextInfo): Promise<void>;

package/dist/commands/template.js

@@ -4,6 +4,7 @@ import { promptHidden } from "../lib/fs.js";
 import { ApiClient, getSessionToken, resolveApiUrl } from "../lib/api.js";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { resolveContext } from "../lib/context.js";
+import { syncFromLinked } from "../lib/template-file.js";
 import { assertWritable, uploadValues } from "../lib/upload.js";
 /** Load a public template by id or URL. No token needed. */
 export async function fetchTemplate(ref, apiUrl) {
@@ -35,11 +36,48 @@ export async function applyTemplate(template, opts) {
     const linked = await ensureTokenAndLink({ apiUrl, quiet: true });
     const ctx = resolveContext(linked.who, linked.meta, undefined);
     assertWritable(linked, ctx);
+    syncFromLinked(linked, { added: template.keys.map((k) => k.name) });
+    await askMissingValues(template.keys, linked, ctx);
+    return { context: ctx.slug };
+}
+/**
+ * Declare the template file's names in the linked project, then ask for each
+ * value that is still missing. Without a terminal, list them instead.
+ * Values already set, for example from a .env import, are not touched.
+ */
+export async function applyTemplateFile(file, opts) {
+    const linked = await ensureTokenAndLink({ apiUrl: opts.apiUrl, quiet: true });
+    const ctx = resolveContext(linked.who, linked.meta, undefined);
+    assertWritable(linked, ctx);
+    const names = file.keys.map((k) => k.name);
+    if (names.length > 0) {
+        await linked.client.request("POST", "/api/cli/values", { context: ctx.slug, values: [], declare: names });
+    }
+    syncFromLinked(linked, { added: names });
+    if (opts.ask ?? process.stdin.isTTY === true) {
+        await askMissingValues(file.keys, linked, ctx);
+        return { context: ctx.slug };
+    }
+    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");
+    }
+    return { context: ctx.slug };
+}
+function missingIn(keys, linked, ctx) {
     const status = new Map(linked.who.keys.map((k) => [k.name, k.status[ctx.slug] ?? "missing"]));
-    const todo = template.keys.filter((k) => (status.get(k.name) ?? "missing") === "missing");
+    return keys.filter((k) => (status.get(k.name) ?? "missing") === "missing");
+}
+/**
+ * Ask for each value still missing in ctx, hidden. Enter skips one and sends
+ * nothing. `linked` must be fresh, so values set a moment ago are not asked.
+ */
+export async function askMissingValues(keys, linked, ctx) {
+    const todo = missingIn(keys, linked, ctx);
     if (todo.length === 0) {
         console.error(`${pc.green("✓")} Every template variable has a value in ${ctx.slug}.`);
-        return { context: ctx.slug };
+        return;
     }
     console.error(`Values for ${pc.bold(ctx.slug)}. Hidden as you type. Enter skips one.\n`);
     const pairs = {};
@@ -71,5 +109,4 @@ export async function applyTemplate(template, opts) {
         console.error(pc.dim(`No value yet: ${skipped.join(", ")}. Set later with npx getmyenv set NAME`));
     }
     console.error("");
-    return { context: ctx.slug };
 }

package/dist/lib/authorize.d.ts

@@ -6,10 +6,20 @@ export declare function browserCommand(raw: string, platform?: NodeJS.Platform):
 } | null;
 export declare function openBrowser(url: string): void;
 export declare function sleep(ms: number): Promise<void>;
+/** The sign-in page preselects the folder's project, or "New project" with a name. */
+export declare function verifyUrlFor(base: string, pick: {
+    projectId?: string;
+    newProject?: {
+        name: string;
+    };
+}): string;
 /**
  * Sign in via the browser and link this folder (writes token.json + project.json).
  * CI uses GETMYENV_TOKEN instead.
  */
 export declare function authorizeFolder(opts?: {
     apiUrl?: string;
+    newProject?: {
+        name: string;
+    };
 }): Promise<WhoamiResponse>;

package/dist/lib/authorize.js

@@ -68,7 +68,18 @@ async function authorizeViaPaste(apiUrl) {
     }
     return saveVerifiedToken(token, apiUrl);
 }
-async function authorizeViaBrowser(apiUrl) {
+/** The sign-in page preselects the folder's project, or "New project" with a name. */
+export function verifyUrlFor(base, pick) {
+    const params = pick.newProject
+        ? `project=new&name=${encodeURIComponent(pick.newProject.name)}`
+        : pick.projectId
+            ? `project=${encodeURIComponent(pick.projectId)}`
+            : "";
+    if (!params)
+        return base;
+    return `${base}${base.includes("?") ? "&" : "?"}${params}`;
+}
+async function authorizeViaBrowser(apiUrl, newProject) {
     const client = new ApiClient(apiUrl);
     let start;
     try {
@@ -80,10 +91,10 @@ async function authorizeViaBrowser(apiUrl) {
         console.error(pc.dim("Falling back to paste.\n"));
         return authorizeViaPaste(apiUrl);
     }
-    const linked = readProjectMeta()?.projectId;
-    const verifyUrl = linked
-        ? `${start.verifyUrl}${start.verifyUrl.includes("?") ? "&" : "?"}project=${encodeURIComponent(linked)}`
-        : start.verifyUrl;
+    const verifyUrl = verifyUrlFor(start.verifyUrl, {
+        projectId: readProjectMeta()?.projectId,
+        newProject,
+    });
     console.error("Open this URL to sign in and pick a project:\n");
     console.error(`  ${verifyUrl}\n`);
     console.error(`Check the page shows this code: ${pc.bold(start.userCode)}\n`);
@@ -124,5 +135,5 @@ export async function authorizeFolder(opts = {}) {
     if (!process.stdin.isTTY) {
         throw new Error("No token in this folder. Run in a terminal to sign in, or set GETMYENV_TOKEN to a server token.");
     }
-    return authorizeViaBrowser(resolveApiUrl(opts.apiUrl));
+    return authorizeViaBrowser(resolveApiUrl(opts.apiUrl), opts.newProject);
 }

package/dist/lib/fs.d.ts

@@ -1,6 +1,7 @@
 /**
  * `.getmyenv/project.json`, committed so a clone knows its project.
  * Holds no API URL: a committed file must not redirect where tokens go.
+ * `.getmyenv/template.json` is committed too: names only, see template-file.ts.
  */
 export type ProjectMeta = {
     projectId?: string;

package/dist/lib/fs.js

@@ -14,7 +14,8 @@ export function getProjectRoot(cwd = process.cwd()) {
     for (;;) {
         const local = path.join(dir, LOCAL_DIR);
         if (fs.existsSync(path.join(local, "project.json")) ||
-            fs.existsSync(path.join(local, "token.json"))) {
+            fs.existsSync(path.join(local, "token.json")) ||
+            fs.existsSync(path.join(local, "template.json"))) {
             return dir;
         }
         const parent = path.dirname(dir);
@@ -220,8 +221,9 @@ export async function promptChoice(question, options, defaultIndex = 0) {
 }
 export function ensureGitignoreHasEnv(cwd = process.cwd()) {
     const gi = path.join(getProjectRoot(cwd), ".gitignore");
-    // project.json is committed so a clone knows its project. The token and the
-    // guest passphrase in claim.json stay on this machine.
+    // project.json and template.json are committed so a clone knows its project
+    // and its names. The token and the guest passphrase in claim.json stay on
+    // this machine.
     const entries = [
         ".env",
         ".env.local",

package/dist/lib/template-file.d.ts

@@ -0,0 +1,34 @@
+import { type TemplateFile } from "@getmyenv/shared";
+import type { Linked } from "./bootstrap.js";
+/**
+ * `.getmyenv/template.json`, committed: the project's variable names, never
+ * values. The CLI keeps it up to date. A fresh clone can start a new project
+ * from it.
+ */
+export type TemplateFileRead = {
+    ok: true;
+    file: TemplateFile;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function templateFilePath(cwd?: string): string;
+/** Null when there is no file. A file that cannot be read or parsed says why. */
+export declare function readTemplateFile(cwd?: string): TemplateFileRead | null;
+export declare function serializeTemplateFile(file: TemplateFile): string;
+/**
+ * Bring the file in line with the project's names. Writes only when the names
+ * change. Never overwrites a file it cannot read, so hand edits are not lost,
+ * and says so every time it skips.
+ */
+export declare function syncTemplateFile(names: readonly string[], projectName: string, cwd?: string): "written" | "unchanged" | "skipped";
+/** CI and servers must not change the working tree. */
+export declare function mayWriteTemplateFile(linked: Pick<Linked, "who">): boolean;
+/**
+ * Sync from the key list a command already has, plus what it just added or
+ * removed. No extra request. A failure here never fails the command.
+ */
+export declare function syncFromLinked(linked: Pick<Linked, "who">, change?: {
+    added?: readonly string[];
+    removed?: readonly string[];
+}): void;

package/dist/lib/template-file.js

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+import { mergeTemplateFile, templateFileSchema, TEMPLATE_FILE, TEMPLATE_FILE_MAX_KEYS, } from "@getmyenv/shared";
+import { getLocalDir } from "./fs.js";
+export function templateFilePath(cwd = process.cwd()) {
+    return path.join(getLocalDir(cwd), "template.json");
+}
+/** Null when there is no file. A file that cannot be read or parsed says why. */
+export function readTemplateFile(cwd = process.cwd()) {
+    const file = templateFilePath(cwd);
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile())
+        return { ok: false, reason: "not a regular file" };
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return { ok: false, reason: "not JSON" };
+    }
+    const parsed = templateFileSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        const where = issue?.path.length ? `${issue.path.join(".")}: ` : "";
+        return { ok: false, reason: `${where}${issue?.message ?? "invalid"}` };
+    }
+    return { ok: true, file: parsed.data };
+}
+export function serializeTemplateFile(file) {
+    return `${JSON.stringify(file, null, 2)}\n`;
+}
+/**
+ * Bring the file in line with the project's names. Writes only when the names
+ * change. Never overwrites a file it cannot read, so hand edits are not lost,
+ * and says so every time it skips.
+ */
+export function syncTemplateFile(names, projectName, cwd = process.cwd()) {
+    const unique = [...new Set(names)];
+    if (unique.length > TEMPLATE_FILE_MAX_KEYS) {
+        console.error(pc.yellow(`${TEMPLATE_FILE} not updated. The project has ${unique.length} names, the file holds ${TEMPLATE_FILE_MAX_KEYS}. It may not match the project.`));
+        return "skipped";
+    }
+    const current = readTemplateFile(cwd);
+    if (current && !current.ok) {
+        console.error(pc.yellow(`${TEMPLATE_FILE} is not valid (${current.reason}). Not updated.`));
+        return "skipped";
+    }
+    if (!current && unique.length === 0)
+        return "unchanged";
+    const merged = mergeTemplateFile(current?.file ?? null, unique, projectName);
+    if (current && serializeTemplateFile(current.file) === serializeTemplateFile(merged))
+        return "unchanged";
+    const file = templateFilePath(cwd);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, serializeTemplateFile(merged));
+    return "written";
+}
+/** CI and servers must not change the working tree. */
+export function mayWriteTemplateFile(linked) {
+    return linked.who.token.kind !== "server" && !process.env.GETMYENV_TOKEN?.trim();
+}
+/**
+ * Sync from the key list a command already has, plus what it just added or
+ * removed. No extra request. A failure here never fails the command.
+ */
+export function syncFromLinked(linked, change = {}) {
+    if (!mayWriteTemplateFile(linked))
+        return;
+    const removed = new Set(change.removed ?? []);
+    const names = [...linked.who.keys.map((k) => k.name), ...(change.added ?? [])].filter((n) => !removed.has(n));
+    try {
+        syncTemplateFile(names, linked.who.project.name);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(pc.yellow(`${TEMPLATE_FILE} not updated: ${msg}`));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getmyenv",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "CLI for getmyenv, an encrypted store for environment variables and secrets. We store ciphertext only.",
   "type": "module",
   "bin": {
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@getmyenv/crypto": "0.5.0",
-    "@getmyenv/shared": "0.9.0",
+    "@getmyenv/shared": "0.10.1",
     "@napi-rs/keyring": "^2.1.0",
     "commander": "^15.0.0",
     "dotenv": "^16.4.7",