getmyenv 0.10.0 → 0.11.0

package/README.md

@@ -32,10 +32,10 @@ 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.
 
 <!-- cli:help -->
-Output of `npx getmyenv --help` (0.10.0):
+Output of `npx getmyenv --help` (0.11.0):
 
 ```text
 Usage: getmyenv [options] [command]

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.0",
   "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.0",
     "@napi-rs/keyring": "^2.1.0",
     "commander": "^15.0.0",
     "dotenv": "^16.4.7",