getmyenv 0.9.9 → 0.11.0

package/README.md

@@ -23,7 +23,7 @@ npx getmyenv run staging -- npm start # or pick one
 - `export [-o file | --stdout] [--yes]`: for tools that need a file. The file is added to `.gitignore` and gets owner-only permissions on macOS and Linux.
 - `guest [--name <name>]`: a project without an account. It works for 30 days. Claim it within 60.
 - `claim`: claim a guest project. Reads `.getmyenv/claim.json`, or asks for the claim code and guest passphrase that `guest` printed once at a terminal.
-- `backup [-o file]`: encrypted backup of open contexts (default `<project>.getmyenv-backup`). It opens with the Vault password in effect when it was made.
+- `backup [-o file]`: encrypted backup of open contexts (default `<project>.getmyenv-backup`). It opens with the Vault password or the recovery code in effect when it was made.
 - `restore <file> [--dry-run] [--yes]`: restore a backup into this folder's project. Values go into open contexts with the same slug and replace values with the same name. Read-only and missing contexts are skipped.
 - `start`: same as bare `getmyenv`. `start --template <id or link>` adds a template's variable names and asks for each value.
 - `lock`: forget every unlocked context key on this machine. `unlink [--yes]`, `help [command]`
@@ -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.9.9):
+Output of `npx getmyenv --help` (0.11.0):
 
 ```text
 Usage: getmyenv [options] [command]

package/dist/commands/backup.d.ts

@@ -2,6 +2,6 @@ type BackupOpts = {
     output?: string;
     apiUrl?: string;
 };
-/** Encrypted backup of open contexts. Opens offline with the current Vault password. */
+/** Encrypted backup of open contexts. Opens offline with the current Vault password or recovery code. */
 export declare function backupCommand(opts: BackupOpts): Promise<void>;
 export {};

package/dist/commands/backup.js

@@ -4,7 +4,7 @@ import { createBackupEnvelope, parsePayload, parseWrappedKey, serializeBackup, }
 import { slugify } from "@getmyenv/shared";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { writePrivateFile } from "../lib/fs.js";
-/** Encrypted backup of open contexts. Opens offline with the current Vault password. */
+/** Encrypted backup of open contexts. Opens offline with the current Vault password or recovery code. */
 export async function backupCommand(opts) {
     const { client } = await ensureTokenAndLink({ apiUrl: opts.apiUrl });
     const data = await client.request("GET", "/api/cli/backup");
@@ -15,6 +15,9 @@ export async function backupCommand(opts) {
         projectName: data.projectName,
         publicKey: data.publicKey,
         wrappedPrivateKey: parseWrappedKey(JSON.stringify(data.wrappedPrivateKey)),
+        recoveryWrappedKey: data.recoveryWrappedKey
+            ? parseWrappedKey(JSON.stringify(data.recoveryWrappedKey))
+            : null,
         contexts: data.contexts,
         keys: data.keys,
         tags: data.tags,
@@ -29,5 +32,7 @@ export async function backupCommand(opts) {
         path.join(process.cwd(), `${slugify(data.projectName) || "project"}.getmyenv-backup`);
     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("It opens with your current Vault password. Read-only contexts are backed up from the dashboard."));
+    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."));
 }

package/dist/commands/claim.js

@@ -1,15 +1,14 @@
 import pc from "picocolors";
 import { GUEST_GRACE_DAYS } from "@getmyenv/shared";
-import { createUserKeys, openSealedKey, sealContextKey, unwrapPrivateKey, wipe, } from "@getmyenv/crypto";
+import { openSealedKey, sealContextKey, unwrapPrivateKey, wipe, } from "@getmyenv/crypto";
 import { clearClaimFile, ensureGitignoreHasEnv, promptHidden, readClaimFile, readLine, readProjectMeta, writeClaimFile, writeProjectMeta, } from "../lib/fs.js";
 import { readFolderToken, writeFolderToken } from "../lib/credentials.js";
 import { ApiClient, ApiError, resolveApiUrl } from "../lib/api.js";
 import { authorizeFolder, openBrowser, sleep } from "../lib/authorize.js";
-import { promptNewVaultPassword } from "../lib/guest-key.js";
-async function askNewVaultPassword() {
-    console.error(pc.dim("Choose a Vault password. It stays on this machine. We store an encrypted key blob only.\n"));
+import { createAccountKeys } from "../lib/recovery-code.js";
+async function askNewAccountKeys() {
     try {
-        return await promptNewVaultPassword();
+        return await createAccountKeys();
     }
     catch (err) {
         throw new Error(`${err instanceof Error ? err.message : "Vault password required."} Run claim again.`);
@@ -38,10 +37,10 @@ async function finishClaim(owned, claim) {
     let keys;
     try {
         if (!ownerPublicKey) {
-            const created = await createUserKeys(await askNewVaultPassword());
+            const created = await askNewAccountKeys();
             wipe(created.privateKey);
             ownerPublicKey = created.publicKey;
-            keys = { publicKey: created.publicKey, wrappedPrivateKey: created.wrapped };
+            keys = created.keys;
         }
         const shares = vault.claim.shares.map((s) => {
             const key = openSealedKey(s.sealedKey, guestKey, s.contextId);
@@ -63,7 +62,7 @@ async function finishClaim(owned, claim) {
     }
     clearClaimFile();
     ensureGitignoreHasEnv();
-    console.error(`\n${pc.green("✓")} Claimed ${pc.bold(claim.projectName)}. ${keys ? "Vault password set." : "It opens with your Vault password."}`);
+    console.error(`\n${pc.green("✓")} Claimed ${pc.bold(claim.projectName)}. ${keys ? "Vault password and recovery code set." : "It opens with your Vault password."}`);
     console.error(pc.dim("claim.json was removed. Read-only contexts like Production are now available in the dashboard.\n"));
 }
 /** A signed-in folder token for the claimed project: reuse this folder's, or sign in. */

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.d.ts

@@ -5,7 +5,7 @@ type RestoreOpts = {
 };
 /**
  * Restore a backup into this folder's project. The backup opens locally with
- * the Vault password it was made with. Values are encrypted again with this
+ * the Vault password or recovery code it was made with. Values are encrypted again with this
  * project's context keys. Read-only and unknown contexts are skipped.
  */
 export declare function restoreCommand(file: string, opts: RestoreOpts): Promise<void>;

package/dist/commands/restore.js

@@ -5,10 +5,11 @@ 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
- * the Vault password it was made with. Values are encrypted again with this
+ * the Vault password or recovery code it was made with. Values are encrypted again with this
  * project's context keys. Read-only and unknown contexts are skipped.
  */
 export async function restoreCommand(file, opts) {
@@ -32,16 +33,23 @@ export async function restoreCommand(file, opts) {
     if (who.token.kind !== "folder") {
         throw new Error("Restore needs a signed-in folder token. Guest and server tokens cannot restore.");
     }
-    const password = await resolveVaultPassword({
+    const secret = await resolveVaultPassword({
         isGuest: false,
-        prompt: "Vault password for this backup (hidden): ",
+        prompt: envelope.recoveryWrappedKey
+            ? "Vault password or recovery code for this backup (hidden): "
+            : "Vault password for this backup (hidden): ",
     });
     let opened;
     try {
-        opened = await restoreValuesFromBackup(password, envelope);
+        opened = await restoreValuesFromBackup(secret, envelope);
     }
-    catch {
-        throw new Error("Could not open the backup. Check the Vault password.");
+    catch (err) {
+        const msg = err instanceof Error ? err.message : "";
+        if (/^(That recovery code|This backup|A recovery code)/.test(msg))
+            throw new Error(msg);
+        throw new Error(envelope.recoveryWrappedKey
+            ? "Could not open the backup. Check the Vault password or recovery code."
+            : "Could not open the backup. Check the Vault password.");
     }
     console.error(`Backup checked: ${opened.values.length} values in ${envelope.contexts.length} contexts.\n`);
     const targets = new Map();
@@ -93,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/recovery-code.d.ts

@@ -0,0 +1,19 @@
+import { type WrappedPrivateKey } from "@getmyenv/crypto";
+export declare const NO_TTY_FOR_VAULT = "No terminal to set a Vault password. Set it in the dashboard, Settings, or run this command in a terminal.";
+export type NewAccountKeys = {
+    publicKey: string;
+    /** Caller wipes it. */
+    privateKey: Uint8Array;
+    keys: {
+        publicKey: string;
+        wrappedPrivateKey: WrappedPrivateKey;
+        recoveryWrappedKey: WrappedPrivateKey;
+    };
+};
+/** The user types the code back. Nothing is saved until it matches. */
+export declare function confirmRecoveryCode(code: string, ask?: (question: string) => Promise<string>): Promise<void>;
+/**
+ * New account keys: a Vault password typed twice, then a recovery code shown
+ * once and typed back. Needs a terminal. Checks both wraps open the same key.
+ */
+export declare function createAccountKeys(): Promise<NewAccountKeys>;

package/dist/lib/recovery-code.js

@@ -0,0 +1,57 @@
+import pc from "picocolors";
+import { assertRecoveryWrap, createRecoveryWrap, createUserKeys, formatRecoveryCode, recoveryCodesMatch, wipe, } from "@getmyenv/crypto";
+import { FACTS } from "@getmyenv/shared";
+import { readLine } from "./fs.js";
+import { promptNewVaultPassword } from "./guest-key.js";
+export const NO_TTY_FOR_VAULT = "No terminal to set a Vault password. Set it in the dashboard, Settings, or run this command in a terminal.";
+const TYPE_BACK_ATTEMPTS = 3;
+function printRecoveryCode(code) {
+    const shown = formatRecoveryCode(code);
+    const width = shown.length + 4;
+    console.error("");
+    console.error(pc.bold("Your recovery code"));
+    console.error(`┌${"─".repeat(width)}┐`);
+    console.error(`│  ${pc.bold(shown)}  │`);
+    console.error(`└${"─".repeat(width)}┘`);
+    console.error(pc.dim(`${FACTS.recoveryCode} Write it down or save it in a password manager.\n`));
+}
+/** The user types the code back. Nothing is saved until it matches. */
+export async function confirmRecoveryCode(code, ask = readLine) {
+    for (let attempt = 1; attempt <= TYPE_BACK_ATTEMPTS; attempt++) {
+        const typed = await ask("Type the recovery code to confirm: ");
+        if (recoveryCodesMatch(code, typed))
+            return;
+        if (attempt < TYPE_BACK_ATTEMPTS)
+            console.error(pc.red("That does not match. Try again.\n"));
+    }
+    throw new Error("The recovery code did not match. Nothing was saved. Run the command again.");
+}
+/**
+ * New account keys: a Vault password typed twice, then a recovery code shown
+ * once and typed back. Needs a terminal. Checks both wraps open the same key.
+ */
+export async function createAccountKeys() {
+    if (!process.stdin.isTTY)
+        throw new Error(NO_TTY_FOR_VAULT);
+    console.error(pc.dim("Choose a Vault password. It stays on this machine. We store an encrypted key blob only.\n"));
+    const created = await createUserKeys(await promptNewVaultPassword());
+    try {
+        const recovery = await createRecoveryWrap(created.privateKey);
+        printRecoveryCode(recovery.code);
+        await confirmRecoveryCode(recovery.code);
+        await assertRecoveryWrap(recovery.code, recovery.wrapped, created.publicKey);
+        return {
+            publicKey: created.publicKey,
+            privateKey: created.privateKey,
+            keys: {
+                publicKey: created.publicKey,
+                wrappedPrivateKey: created.wrapped,
+                recoveryWrappedKey: recovery.wrapped,
+            },
+        };
+    }
+    catch (err) {
+        wipe(created.privateKey);
+        throw err;
+    }
+}

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/dist/lib/vault.js

@@ -4,6 +4,7 @@ import { VAULT_UNLOCK_DURATION } from "@getmyenv/shared";
 import { ApiError } from "./api.js";
 import { resolveVaultPassword } from "./guest-key.js";
 import { keychainAccount, keychainEnabled, readCachedContextKey, storeCachedContextKeys, } from "./keychain.js";
+import { createAccountKeys } from "./recovery-code.js";
 /** One unlock per process: several contexts in one command prompt once. */
 const memo = new Map();
 /** Key version of each memo entry opened from the vault response. Keys from the keychain have none. */
@@ -152,22 +153,16 @@ async function holderPrivateKey(linked, vault, opts) {
         if (!opts.create) {
             throw new Error("No Vault password yet. Set it in the dashboard, or set a value: npx getmyenv set KEY");
         }
-        if (!isGuest) {
-            console.error(pc.dim("Choose a Vault password. It stays on this machine. We store an encrypted key blob only.\n"));
-        }
-        const password = await resolveVaultPassword({ isGuest, create: true });
-        const created = await createUserKeys(password);
+        const created = isGuest ? await createGuestKeys() : await createAccountKeys();
         try {
-            await linked.client.request("POST", "/api/cli/vault", {
-                keys: { publicKey: created.publicKey, wrappedPrivateKey: created.wrapped },
-            });
+            await linked.client.request("POST", "/api/cli/vault", { keys: created.keys });
         }
         catch (err) {
             wipe(created.privateKey);
             throw err;
         }
         vault.publicKey = created.publicKey;
-        vault.wrappedPrivateKey = created.wrapped;
+        vault.wrappedPrivateKey = created.keys.wrappedPrivateKey;
         return created.privateKey;
     }
     const interactive = process.stdin.isTTY && !isGuest;
@@ -185,10 +180,19 @@ async function holderPrivateKey(linked, vault, opts) {
                 console.error(pc.red("Wrong Vault password. Try again.\n"));
                 continue;
             }
-            throw new Error("Could not unlock. Check your Vault password. Forgot it? Reset the vault in the dashboard, Settings.");
+            throw new Error("Could not unlock. Check your Vault password. Forgot it? Use your recovery code in the dashboard, Settings.");
         }
     }
 }
+/** Guest keys wrap with the claim.json passphrase. No recovery code. */
+async function createGuestKeys() {
+    const created = await createUserKeys(await resolveVaultPassword({ isGuest: true, create: true }));
+    return {
+        publicKey: created.publicKey,
+        privateKey: created.privateKey,
+        keys: { publicKey: created.publicKey, wrappedPrivateKey: created.wrapped },
+    };
+}
 /** Unlock with the Vault password and return the private key. Caller wipes it. */
 export async function unlockPrivateKey(linked, opts = {}) {
     const vault = await fetchVault(linked);

package/package.json

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