novence 0.2.0 → 0.3.0

package/README.md

@@ -7,6 +7,12 @@ until you claim.
 npx novence deploy ./dist
 ```
 
+> **Breaking change in 0.3.0:** `novence keys create <name>` no longer prints the
+> secret. It saves it to `~/.novence/keys/<name>` (mode 0600) and prints only the
+> prefix and path. `KEY=$(novence keys create ci)` now fails with a message —
+> use `KEY=$(novence keys create ci --print)` or `--output <path>`. `--json`
+> omits `apiKey` unless `--print` is passed.
+
 ```text
   Created project site (abcd1234)
   Uploaded 12 files
@@ -75,15 +81,38 @@ novence checks [project]      # Lighthouse / axe / link results for the last dep
 novence domains add <host>    # attach a custom domain, prints the DNS records
 novence domains status        # custom domain state
 novence keys list             # API keys on the account
-novence keys create <name>    # extra named key (e.g. ci) that survives login --recover
-novence keys revoke <id>      # revoke a key (--force to revoke the one in use)
+novence keys create <name>    # named key (e.g. ci), saved to ~/.novence/keys/<name>
+novence keys revoke <id>      # revoke a key and delete its ~/.novence/keys file
 novence projects              # list projects and their URLs
-novence login                 # sign in, verify email, or --recover a key
+novence login --email <email> # sign in, or verify your email
 novence claim                 # attach an email to an anonymous deploy
 novence whoami                # plan, verification, usage against quota
 novence dashboard             # local account console (alias: novence console)
 ```
 
+## Lost or revoked key
+
+```bash
+novence login --recover --email you@example.com              # emails a code, reissues the key
+novence login --recover --email you@example.com --revoke-all # also revoke named keys
+```
+
+Recovery never uses the old key, so a revoked `./.novence-key` can't block it, and
+it rewrites `./.novence-key` if one exists. Without a terminal (agents, CI), run it
+once to send the code, then again with `--code <6 digits>`.
+
+## Named keys
+
+`novence keys create ci` saves the key to `~/.novence/keys/ci` (0600) and prints
+only its prefix — the secret never reaches your terminal. Use it with
+`--key-name ci` (or `NOVENCE_KEY_NAME=ci`), or in CI with
+`NOVENCE_API_KEY="$(cat ~/.novence/keys/ci)"`.
+
+| Flag | |
+| --- | --- |
+| `--output <path>` | Save somewhere else (0600). Refuses to overwrite without `--force` |
+| `--print` | Print the secret to stdout instead: `KEY=$(novence keys create ci --print)` |
+
 ## Dashboard
 
 `novence dashboard` fetches your console-kit, writes `~/.novence/console/novence-console.html`
@@ -130,14 +159,14 @@ Full agent brief: [novence.ai/llms-full.txt](https://novence.ai/llms-full.txt).
 
 Set `NOVENCE_API_KEY` and pass `--no-input`.
 
-Key lookup order: `NOVENCE_API_KEY`, then `./.novence-key`, then
-`~/.novence/credentials`. Never commit a key.
+Key lookup order: `--key-name <name>` / `NOVENCE_KEY_NAME`, then `NOVENCE_API_KEY`,
+then `./.novence-key`, then `~/.novence/credentials`. Never commit a key.
 
 ## Checks
 
 Deploys run Lighthouse, axe, and link checks. On unverified accounts checks are
 skipped — `checks.skipped` is `true` and `checks.passed` is `null`, which is not
-a pass. Verify your email with `novence login` (or claim) to enable them.
+a pass. Verify your email with `novence login --email you@example.com` (or claim) to enable them.
 
 ## Docs
 

package/dist/commands/checks.js

@@ -1,5 +1,5 @@
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagString } from "../lib/args.js";
 import { explain } from "../lib/errors.js";
 import { fail, isJsonMode, json, result } from "../lib/ui.js";
@@ -10,7 +10,7 @@ export async function checksCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const wanted = args.positionals[0];
     let projectId = wanted;

package/dist/commands/data.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagString } from "../lib/args.js";
 import { explain } from "../lib/errors.js";
 import { fail, isJsonMode, json, result, step } from "../lib/ui.js";
@@ -35,7 +35,7 @@ export async function dataCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const sub = args.positionals[0] ?? "put";
     const projectFlag = flagString(args.flags, "project");

package/dist/commands/domains.js

@@ -1,5 +1,5 @@
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { explain } from "../lib/errors.js";
 import { fail, isJsonMode, json, result, step } from "../lib/ui.js";
@@ -20,7 +20,7 @@ export async function domainsCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const sub = args.positionals[0] ?? "status";
     const projectFlag = flagString(args.flags, "project");

package/dist/commands/keys.js

@@ -1,13 +1,15 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, namedKeyPath, notSignedInMessage, removeNamedKeyFile, resolveApiBase, saveNamedKey, } from "../lib/config.js";
 import { flagBool, flagString } from "../lib/args.js";
 import { explain } from "../lib/errors.js";
-import { fail, isJsonMode, json, result, step } from "../lib/ui.js";
+import { fail, isJsonMode, json, result, step, warn } from "../lib/ui.js";
 export async function keysCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const sub = args.positionals[0] ?? "list";
     try {
@@ -37,14 +39,42 @@ export async function keysCommand(args) {
             const name = args.positionals[1];
             if (!name)
                 fail("Usage: novence keys create <name> [--project <id>]\n  e.g.  novence keys create ci");
+            const outputFlag = flagString(args.flags, "output");
+            const print = flagBool(args.flags, "print") || outputFlag === "-";
+            const outputPath = outputFlag === "-" ? undefined : outputFlag;
+            const force = flagBool(args.flags, "force");
+            // Checked before the API call so a refused run never mints an orphan key.
+            if (!print && !outputPath && !isJsonMode() && !process.stdout.isTTY) {
+                fail("keys create no longer prints the secret. Capture it with --print:\n" +
+                    `  KEY=$(novence keys create ${name} --print)\n` +
+                    "  or write it to a file:  --output <path>");
+            }
+            let target;
+            if (!print) {
+                target = outputPath ? resolve(outputPath) : namedKeyPath(name);
+                if (existsSync(target) && !force)
+                    fail(`${target} already exists. Pass --force to replace it.`);
+            }
             const res = await client.apiKeys.create({ name, projectId: flagString(args.flags, "project") });
+            if (print) {
+                if (isJsonMode()) {
+                    json({ ok: true, ...res });
+                    return;
+                }
+                result(res.apiKey);
+                step(`Key "${res.key.name}" (${res.key.scope}) — shown once. Store it in a secret manager.`);
+                return;
+            }
+            const savedTo = saveNamedKey(name, res.apiKey, { outputPath, force });
             if (isJsonMode()) {
-                json({ ok: true, ...res });
+                json({ ok: true, key: res.key, savedTo });
                 return;
             }
-            result(res.apiKey);
-            step(`Key "${res.key.name}" (${res.key.scope}) — shown once. Store it in a secret manager or NOVENCE_API_KEY.`);
+            const inCi = `NOVENCE_API_KEY="$(cat ${savedTo})"`;
+            step(`Key "${res.key.name}" (${res.key.scope}) · ${res.key.keyPrefix}… saved to ${savedTo} (0600).`);
+            step(outputPath ? `In CI: ${inCi}` : `Use it here with --key-name ${name}, or in CI with ${inCi}.`);
             step("It keeps working when `novence login --recover` replaces your primary key.");
+            result(savedTo);
             return;
         }
         if (sub === "revoke") {
@@ -52,14 +82,34 @@ export async function keysCommand(args) {
             if (!id)
                 fail("Usage: novence keys revoke <id> [--force]\n  Find ids with:  novence keys list");
             const force = flagBool(args.flags, "force");
+            // Only used to clean up ~/.novence/keys/<name>; never block the revoke on it.
+            const { keys } = await client.apiKeys
+                .list({ projectId: flagString(args.flags, "project"), includeRevoked: true })
+                .catch(() => ({ keys: [] }));
+            const revoked = keys.find((k) => k.id === id);
             const res = await client.apiKeys.revoke(id, { force });
+            const fileOutcome = revoked ? removeNamedKeyFile(revoked.name, revoked.keyPrefix) : "absent";
             if (isJsonMode()) {
-                json({ ok: true, ...res });
+                json({ ok: true, ...res, keyFile: fileOutcome });
                 return;
             }
             result(`Revoked ${id}`);
+            switch (fileOutcome) {
+                case "removed":
+                    step(`Deleted ${namedKeyPath(revoked.name)}.`);
+                    break;
+                case "mismatch":
+                    warn(`Kept ${namedKeyPath(revoked.name)}: it holds a different key than the one revoked.`);
+                    break;
+                case "absent":
+                    break;
+                default: {
+                    const unreachable = fileOutcome;
+                    return unreachable;
+                }
+            }
             if (force)
-                step("That was the key this machine uses — run `novence login` to get a new one.");
+                step("That was the key this machine uses — run `novence login --recover --email you@example.com`.");
             return;
         }
         fail(`Unknown subcommand: ${sub}\n  Usage: novence keys list | novence keys create <name> | novence keys revoke <id>`);

package/dist/commands/login.js

@@ -1,45 +1,102 @@
-import { Novence } from "@novence/sdk";
-import { claimAndMaybeVerify, ensureApiKey } from "../lib/auth.js";
-import { credentialsPath, loadApiKey, resolveApiBase, saveApiKey } from "../lib/config.js";
-import { reissueApiKey, resendVerification, verifyEmail } from "@novence/sdk";
+import { existsSync } from "node:fs";
+import { Novence, NovenceError, reissueApiKey, resendVerification, verifyEmail, } from "@novence/sdk";
+import { claimAndMaybeVerify, ensureApiKey, isAccountExistsError, recoverHint } from "../lib/auth.js";
+import { credentialsPath, keySource, loadApiKey, localKeyPath, resolveApiBase, saveApiKey, } from "../lib/config.js";
 import { flagBool, flagString } from "../lib/args.js";
-import { fail, prompt, result, step, withSpin } from "../lib/ui.js";
+import { fail, isJsonMode, prompt, result, step, warn, withSpin } from "../lib/ui.js";
 export async function loginCommand(args) {
-    const apiBase = resolveApiBase(flagString(args.flags, "api"));
-    const emailFlag = flagString(args.flags, "email");
-    if (!loadApiKey()) {
-        const email = emailFlag ?? (await prompt("  Email: "));
-        await ensureApiKey({ apiBase, email, interactive: true });
-        result(`Signed in. Key stored at ${credentialsPath()}`);
-        return;
+    const recoverFlag = args.flags.recover;
+    // `--recover you@x.com` parses as a value; treat it as the email.
+    const recoverEmail = typeof recoverFlag === "string" && recoverFlag.includes("@") ? recoverFlag : undefined;
+    const ctx = {
+        apiBase: resolveApiBase(flagString(args.flags, "api")),
+        email: flagString(args.flags, "email") ?? recoverEmail,
+        code: flagString(args.flags, "code"),
+        revokeAll: flagBool(args.flags, "revoke-all"),
+        canPrompt: Boolean(process.stdin.isTTY) && !isJsonMode() && !flagBool(args.flags, "no-input"),
+    };
+    if (recoverFlag !== undefined)
+        return recoverKey(ctx);
+    const storedKey = loadApiKey();
+    if (!storedKey)
+        return signInWithEmail(ctx);
+    let snap;
+    try {
+        snap = await new Novence({ apiKey: storedKey, baseUrl: ctx.apiBase }).account.get();
+    }
+    catch (err) {
+        if (!(err instanceof NovenceError && err.status === 401))
+            throw err;
+        const lead = `The stored key (${keySource()}) was rejected — it may be revoked.`;
+        if (!ctx.canPrompt)
+            fail(recoverHint(ctx.email, lead));
+        warn(lead);
+        return recoverKey(ctx);
     }
-    const address = emailFlag ?? (await prompt("  Email: "));
-    if (!address.includes("@"))
-        fail(`Not a valid email: ${address}`);
-    const apiKey = loadApiKey();
-    const client = new Novence({ apiKey, baseUrl: apiBase });
-    const snap = await client.account.get();
+    const address = await requireEmail(ctx);
     if (!snap.email) {
-        await claimAndMaybeVerify({ apiKey, apiBase, email: address, interactive: true });
+        await claimAndMaybeVerify({ apiKey: storedKey, apiBase: ctx.apiBase, email: address, interactive: ctx.canPrompt });
         result(`${address} claimed.`);
         return;
     }
-    const sent = await withSpin(`Sending a code to ${address}…`, () => resendVerification(address, apiBase));
-    const code = sent.verificationCode ?? (await prompt("  6-digit code from your email: "));
+    const code = ctx.code ?? (await sendCode(address, ctx));
+    await verifyEmail(address, code, ctx.apiBase);
+    result(`${address} verified.`);
+}
+async function signInWithEmail(ctx) {
+    const email = await requireEmail(ctx);
+    try {
+        await ensureApiKey({ apiBase: ctx.apiBase, email, interactive: ctx.canPrompt });
+        result(`Signed in. Key stored at ${credentialsPath()}`);
+    }
+    catch (err) {
+        if (!isAccountExistsError(err))
+            throw err;
+        if (!ctx.canPrompt)
+            fail(err.message);
+        step(`${email} already has an account — recovering its key with an email code.`);
+        await recoverKey({ ...ctx, email });
+    }
+}
+/** Email OTP → POST /v1/auth/reissue-key. Never reads or sends the stored key. */
+async function recoverKey(ctx) {
+    const email = await requireEmail(ctx);
+    const code = ctx.code ?? (await sendCode(email, ctx, true));
+    const issued = await withSpin("Reissuing your key…", () => reissueApiKey(email, code, ctx.apiBase, { revokeAll: ctx.revokeAll }));
+    const hadLocalKey = existsSync(localKeyPath());
+    const path = saveApiKey(issued.apiKey);
+    if (hadLocalKey)
+        step(`Also replaced ${localKeyPath()} (it would otherwise shadow the new key).`);
+    if (process.env.NOVENCE_API_KEY?.trim()) {
+        warn("NOVENCE_API_KEY is set and overrides the new key. Update or unset it.");
+    }
+    if (issued.remainingKeys.length) {
+        step(`Still active: ${issued.remainingKeys.map((k) => `${k.name} (${k.keyPrefix})`).join(", ")}. ` +
+            "Use --revoke-all if a key may have leaked.");
+    }
+    result(`Key reissued for account ${issued.accountId} → ${path}`);
+}
+/** Sends an OTP. Without a TTY, stops and says how to finish with --code. */
+async function sendCode(email, ctx, recovering = false) {
+    const sent = await withSpin(`Sending a code to ${email}…`, () => resendVerification(email, ctx.apiBase));
+    if (sent.verificationCode)
+        return sent.verificationCode;
+    if (!ctx.canPrompt) {
+        const rerun = recovering
+            ? `novence login --recover --email ${email}${ctx.revokeAll ? " --revoke-all" : ""} --code <6 digits>`
+            : `novence login --email ${email} --code <6 digits>`;
+        fail(`Code sent to ${email}. Re-run:\n  ${rerun}`);
+    }
+    const code = await prompt("  6-digit code from your email: ");
     if (!code)
         fail("No code entered.");
-    if (flagString(args.flags, "recover") !== undefined || args.flags.recover === true) {
-        const issued = await reissueApiKey(address, code, apiBase, {
-            revokeAll: flagBool(args.flags, "revoke-all"),
-        });
-        saveApiKey(issued.apiKey);
-        result(`Key reissued for account ${issued.accountId} → ${credentialsPath()}`);
-        if (issued.remainingKeys.length) {
-            step(`Still active: ${issued.remainingKeys.map((k) => `${k.name} (${k.keyPrefix})`).join(", ")}. ` +
-                "Use --revoke-all if a key may have leaked.");
-        }
-        return;
-    }
-    await verifyEmail(address, code, apiBase);
-    result(`${address} verified.`);
+    return code;
+}
+async function requireEmail(ctx) {
+    const email = ctx.email ?? (ctx.canPrompt ? await prompt("  Email: ") : undefined);
+    if (!email)
+        fail("Pass --email you@example.com.");
+    if (!email.includes("@"))
+        fail(`Not a valid email: ${email}`);
+    return email;
 }

package/dist/commands/open.js

@@ -1,5 +1,5 @@
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagString } from "../lib/args.js";
 import { openInBrowser } from "../lib/browser.js";
 import { explain } from "../lib/errors.js";
@@ -8,7 +8,7 @@ export async function openCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const wanted = args.positionals[0];
     try {

package/dist/commands/projects.js

@@ -1,12 +1,12 @@
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagString } from "../lib/args.js";
 import { fail, isJsonMode, json, result } from "../lib/ui.js";
 export async function projectsCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const { projects } = await client.projects.list();
     if (isJsonMode()) {

package/dist/commands/rollback.js

@@ -1,5 +1,5 @@
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagString } from "../lib/args.js";
 import { explain } from "../lib/errors.js";
 import { fail, isJsonMode, json, result, siteUrl, step } from "../lib/ui.js";
@@ -7,7 +7,7 @@ export async function rollbackCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const wanted = flagString(args.flags, "project") ?? args.positionals[0];
     const deploymentId = flagString(args.flags, "deployment");

package/dist/commands/site-mcp.js

@@ -1,5 +1,5 @@
 import { Novence } from "@novence/sdk";
-import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagString } from "../lib/args.js";
 import { explain } from "../lib/errors.js";
 import { fail, isJsonMode, json, result, step } from "../lib/ui.js";
@@ -19,7 +19,7 @@ export async function siteMcpCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const sub = (args.positionals[0] ?? "status").toLowerCase();
     const projectFlag = flagString(args.flags, "project");

package/dist/commands/whoami.js

@@ -1,12 +1,12 @@
 import { Novence } from "@novence/sdk";
-import { keySource, loadApiKey, resolveApiBase } from "../lib/config.js";
+import { keySource, loadApiKey, notSignedInMessage, resolveApiBase } from "../lib/config.js";
 import { flagString } from "../lib/args.js";
 import { fail, isJsonMode, json, result } from "../lib/ui.js";
 export async function whoamiCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));
     const apiKey = loadApiKey();
     if (!apiKey)
-        fail("Not signed in. Run `novence login`.");
+        fail(notSignedInMessage());
     const client = new Novence({ apiKey, baseUrl: apiBase });
     const snap = await client.account.get();
     const quotas = await client.billing.quotas();

package/dist/index.js

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { assertKnownFlags, flagBool, flagString, parseArgs } from "./lib/args.js";
-import { resolveApiBase } from "./lib/config.js";
+import { resolveApiBase, setKeyName } from "./lib/config.js";
 import { explain } from "./lib/errors.js";
 import { fail, isJsonMode, result, setJsonMode } from "./lib/ui.js";
 import { deployCommand } from "./commands/deploy.js";
@@ -32,7 +32,7 @@ const HELP = `
     novence domains add <host>  Attach a custom domain (prints DNS records)
     novence domains status      Custom domain state
     novence keys list           API keys on the account
-    novence keys create <name>  Extra named key (e.g. ci) that survives login --recover
+    novence keys create <name>  Extra named key (e.g. ci), saved to ~/.novence/keys/<name>
     novence keys revoke <id>    Revoke a key
     novence projects            List projects and their URLs
     novence login               Sign in, verify email, or recover a key
@@ -40,6 +40,18 @@ const HELP = `
     novence whoami              Plan, verification, and usage
     novence dashboard           Open your local account console (alias: console)
 
+  Login
+    novence login --email <email>       Sign in (new account) or verify your email
+    novence login --recover --email <email>  Lost or revoked key: email code → new key
+    --revoke-all                Also revoke named keys (use if a key may have leaked)
+    --code <6 digits>           Finish without a prompt (agents, --no-input)
+
+  Keys
+    novence keys create ci      Save to ~/.novence/keys/ci (0600); prints only the prefix
+    --output <path>             Save somewhere else (0600; --force to replace)
+    --print                     Print the secret to stdout instead, e.g. KEY=$(novence keys create ci --print)
+    novence keys revoke <id>    Also deletes the matching ~/.novence/keys/<name>
+
   Dashboard
     novence dashboard           Serve the console on the first free 127.0.0.1 port from 8765
     --port <n>                  First port to try (default 8765)
@@ -70,6 +82,7 @@ const HELP = `
     --json                      Machine-readable output (implies --no-input)
     --no-input                  Never prompt; fail instead
     --api <url>                 Control plane (default https://api.novence.ai)
+    --key-name <name>           Use ~/.novence/keys/<name> (or set NOVENCE_KEY_NAME)
     -h, --help                  Show this help
     -v, --version               Show the version
 
@@ -77,7 +90,8 @@ const HELP = `
     URL=$(novence deploy ./dist)
 
   Auth
-    Reads NOVENCE_API_KEY, then ./.novence-key, then ~/.novence/credentials.
+    Reads --key-name / NOVENCE_KEY_NAME, then NOVENCE_API_KEY, then ./.novence-key,
+    then ~/.novence/credentials. Lost key: novence login --recover --email <email>
     NOVENCE_ATTRIBUTION, when set to JSON, is sent with the first signup.
 
   Docs  https://novence.ai/docs
@@ -107,10 +121,10 @@ async function main() {
         open: [],
         checks: [],
         domains: ["project", "primary", "redirect"],
-        keys: ["project", "include-revoked", "force"],
+        keys: ["project", "include-revoked", "force", "output", "print"],
         projects: [],
         ls: [],
-        login: ["email", "recover", "revoke-all"],
+        login: ["email", "recover", "revoke-all", "code"],
         whoami: [],
         rollback: ["project", "deployment"],
         data: ["project"],
@@ -124,6 +138,7 @@ async function main() {
         if (problem)
             fail(problem);
     }
+    setKeyName(flagString(args.flags, "key-name"));
     switch (args.command) {
         case "deploy":
             return deployCommand(args);

package/dist/lib/args.js

@@ -41,7 +41,7 @@ export function flagBool(flags, name) {
     return flags[name] === true || flags[name] === "true";
 }
 /** Flags every command accepts. */
-export const GLOBAL_FLAGS = ["json", "no-input", "api", "help", "version", "quiet"];
+export const GLOBAL_FLAGS = ["json", "no-input", "api", "help", "version", "quiet", "key-name"];
 /**
  * Reject unrecognised flags. Without this a typo like `--nmae "My Site"` is
  * silently dropped and the user gets a differently-named project with no

package/dist/lib/auth.d.ts

@@ -1,3 +1,6 @@
+export declare function isAccountExistsError(err: unknown): boolean;
+/** The one command that restores a lost or revoked key. */
+export declare function recoverHint(email: string | undefined, lead: string): string;
 export interface Credentials {
     apiKey: string;
     /** True when this run created the account, so callers can tailor next steps. */

package/dist/lib/auth.js

@@ -1,6 +1,15 @@
-import { bootstrapAccount, claimAccount, createDemoAccount, verifyEmail, } from "@novence/sdk";
+import { bootstrapAccount, claimAccount, createDemoAccount, NovenceError, verifyEmail, } from "@novence/sdk";
 import { loadApiKey, saveApiKey } from "./config.js";
 import { fail, prompt, step, warn, withSpin } from "./ui.js";
+const ACCOUNT_EXISTS = "ACCOUNT_EXISTS";
+export function isAccountExistsError(err) {
+    return err?.code === ACCOUNT_EXISTS;
+}
+/** The one command that restores a lost or revoked key. */
+export function recoverHint(email, lead) {
+    const who = email ?? "you@example.com";
+    return `${email ? `${email} ` : ""}${lead}\n  Recover the key with an email code:  novence login --recover --email ${who}`;
+}
 function attributionFromEnv() {
     const raw = process.env.NOVENCE_ATTRIBUTION?.trim();
     let parsed = {};
@@ -42,10 +51,11 @@ async function bootstrapWithEmail(email, apiBase, interactive) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        if (/exists|already|409/i.test(message)) {
-            fail(`${email} already has an account. Recover the key with an OTP:\n` +
-                "  novence login --email " +
-                email);
+        const status = err instanceof NovenceError ? err.status : undefined;
+        if (status === 409 || /exists|already/i.test(message)) {
+            throw Object.assign(new Error(recoverHint(email, "already has an account.")), {
+                code: ACCOUNT_EXISTS,
+            });
         }
         throw err;
     }

package/dist/lib/config.d.ts

@@ -1,13 +1,39 @@
 export declare const DEFAULT_API = "https://api.novence.ai";
+/** Project-local key file; wins over ~/.novence/credentials. */
+export declare function localKeyPath(): string;
 /** Explicit flag wins, then env, then the public control plane. */
 export declare function resolveApiBase(flag?: string): string;
+/** Global `--key-name`; falls back to NOVENCE_KEY_NAME. */
+export declare function setKeyName(name: string | undefined): void;
+export declare function isValidKeyFileName(name: string): boolean;
+export declare function namedKeyPath(name: string): string;
 /**
- * Key lookup order: NOVENCE_API_KEY, then a project-local .novence-key (what
- * scripts/launch-site.ts writes), then ~/.novence/credentials.
+ * Key lookup order: --key-name / NOVENCE_KEY_NAME (~/.novence/keys/<name>),
+ * NOVENCE_API_KEY, a project-local .novence-key, then ~/.novence/credentials.
  */
 export declare function loadApiKey(): string | null;
-/** Written 0600 — this is a live credential. */
+/**
+ * Write a credential at mode 0600 from the first byte. Without `overwrite`
+ * an existing file is an error; with it, a temp file is renamed over the
+ * target so a previously looser mode is not inherited.
+ */
+export declare function writeSecretFile(path: string, value: string, opts: {
+    overwrite: boolean;
+}): void;
+/**
+ * Store the primary key in ~/.novence/credentials. An existing ./.novence-key
+ * is replaced too, since it would otherwise shadow the new key.
+ */
 export declare function saveApiKey(apiKey: string): string;
+/** Store a named key at ~/.novence/keys/<name> or `outputPath`. Returns the path written. */
+export declare function saveNamedKey(name: string, apiKey: string, opts?: {
+    outputPath?: string;
+    force?: boolean;
+}): string;
+export type NamedKeyRemoval = "removed" | "mismatch" | "absent";
+/** Delete ~/.novence/keys/<name> only if it holds the key with `keyPrefix`. */
+export declare function removeNamedKeyFile(name: string, keyPrefix: string): NamedKeyRemoval;
 export declare function credentialsPath(): string;
 /** Where loadApiKey() found the key, for display. */
 export declare function keySource(): string;
+export declare function notSignedInMessage(): string;

package/dist/lib/config.js

@@ -1,54 +1,146 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-const CONFIG_DIR = join(homedir(), ".novence");
-const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials");
+import { dirname, join, resolve } from "node:path";
 export const DEFAULT_API = "https://api.novence.ai";
+const KEY_FILE_NAME = /^[A-Za-z0-9_-]+$/;
+let keyNameOverride;
+/** Resolved per call so HOME changes (tests, sudo -E) are honoured. */
+function configDir() {
+    return join(homedir(), ".novence");
+}
+function credentialsFile() {
+    return join(configDir(), "credentials");
+}
+function keysDir() {
+    return join(configDir(), "keys");
+}
+/** Project-local key file; wins over ~/.novence/credentials. */
+export function localKeyPath() {
+    return join(process.cwd(), ".novence-key");
+}
 /** Explicit flag wins, then env, then the public control plane. */
 export function resolveApiBase(flag) {
     const raw = flag ?? process.env.NOVENCE_BASE_URL ?? process.env.API_BASE_URL ?? DEFAULT_API;
     return raw.replace(/\/$/, "");
 }
+/** Global `--key-name`; falls back to NOVENCE_KEY_NAME. */
+export function setKeyName(name) {
+    keyNameOverride = name?.trim() || undefined;
+}
+function selectedKeyName() {
+    return keyNameOverride ?? (process.env.NOVENCE_KEY_NAME?.trim() || undefined);
+}
+export function isValidKeyFileName(name) {
+    return KEY_FILE_NAME.test(name);
+}
+export function namedKeyPath(name) {
+    if (!isValidKeyFileName(name)) {
+        throw new Error(`Key name "${name}" can't be used as a file name (letters, digits, _ and - only). Pass --output <path>.`);
+    }
+    return join(keysDir(), name);
+}
+function readKeyFile(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf8").trim() || null;
+}
 /**
- * Key lookup order: NOVENCE_API_KEY, then a project-local .novence-key (what
- * scripts/launch-site.ts writes), then ~/.novence/credentials.
+ * Key lookup order: --key-name / NOVENCE_KEY_NAME (~/.novence/keys/<name>),
+ * NOVENCE_API_KEY, a project-local .novence-key, then ~/.novence/credentials.
  */
 export function loadApiKey() {
+    const name = selectedKeyName();
+    if (name) {
+        const path = namedKeyPath(name);
+        const key = readKeyFile(path);
+        if (!key) {
+            throw new Error(`No key named "${name}" at ${path}.\n  Create it with:  novence keys create ${name}`);
+        }
+        return key;
+    }
     const fromEnv = process.env.NOVENCE_API_KEY?.trim();
     if (fromEnv)
         return fromEnv;
-    const local = join(process.cwd(), ".novence-key");
-    if (existsSync(local)) {
-        const key = readFileSync(local, "utf8").trim();
-        if (key)
-            return key;
+    return readKeyFile(localKeyPath()) ?? readKeyFile(credentialsFile());
+}
+/**
+ * Write a credential at mode 0600 from the first byte. Without `overwrite`
+ * an existing file is an error; with it, a temp file is renamed over the
+ * target so a previously looser mode is not inherited.
+ */
+export function writeSecretFile(path, value, opts) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const body = value.trim() + "\n";
+    if (!opts.overwrite) {
+        try {
+            writeFileSync(path, body, { mode: 0o600, flag: "wx" });
+        }
+        catch (err) {
+            if (err.code === "EEXIST") {
+                throw new Error(`${path} already exists. Pass --force to replace it.`);
+            }
+            throw err;
+        }
+        return;
     }
-    if (existsSync(CREDENTIALS_FILE)) {
-        const key = readFileSync(CREDENTIALS_FILE, "utf8").trim();
-        if (key)
-            return key;
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, body, { mode: 0o600, flag: "wx" });
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
     }
-    return null;
 }
-/** Written 0600 — this is a live credential. */
+/**
+ * Store the primary key in ~/.novence/credentials. An existing ./.novence-key
+ * is replaced too, since it would otherwise shadow the new key.
+ */
 export function saveApiKey(apiKey) {
-    mkdirSync(dirname(CREDENTIALS_FILE), { recursive: true, mode: 0o700 });
-    writeFileSync(CREDENTIALS_FILE, apiKey.trim() + "\n", { mode: 0o600 });
-    chmodSync(CREDENTIALS_FILE, 0o600);
-    return CREDENTIALS_FILE;
+    const path = credentialsFile();
+    writeSecretFile(path, apiKey, { overwrite: true });
+    if (existsSync(localKeyPath()))
+        writeSecretFile(localKeyPath(), apiKey, { overwrite: true });
+    return path;
+}
+/** Store a named key at ~/.novence/keys/<name> or `outputPath`. Returns the path written. */
+export function saveNamedKey(name, apiKey, opts = {}) {
+    const path = opts.outputPath ? resolve(opts.outputPath) : namedKeyPath(name);
+    writeSecretFile(path, apiKey, { overwrite: Boolean(opts.force) });
+    return path;
+}
+/** Delete ~/.novence/keys/<name> only if it holds the key with `keyPrefix`. */
+export function removeNamedKeyFile(name, keyPrefix) {
+    if (!isValidKeyFileName(name))
+        return "absent";
+    const path = namedKeyPath(name);
+    const key = readKeyFile(path);
+    if (!key)
+        return "absent";
+    if (!key.startsWith(keyPrefix))
+        return "mismatch";
+    unlinkSync(path);
+    return "removed";
 }
 export function credentialsPath() {
-    return CREDENTIALS_FILE;
+    return credentialsFile();
 }
 /** Where loadApiKey() found the key, for display. */
 export function keySource() {
+    const name = selectedKeyName();
+    if (name)
+        return namedKeyPath(name);
     if (process.env.NOVENCE_API_KEY?.trim())
         return "NOVENCE_API_KEY";
-    const local = join(process.cwd(), ".novence-key");
-    if (existsSync(local) && readFileSync(local, "utf8").trim())
-        return local;
-    if (existsSync(CREDENTIALS_FILE) && readFileSync(CREDENTIALS_FILE, "utf8").trim()) {
-        return CREDENTIALS_FILE;
-    }
+    if (readKeyFile(localKeyPath()))
+        return localKeyPath();
+    if (readKeyFile(credentialsFile()))
+        return credentialsFile();
     return "(none)";
 }
+export function notSignedInMessage() {
+    return (`Not signed in. Looked in NOVENCE_API_KEY, ${localKeyPath()}, ${credentialsFile()}.\n` +
+        "  New account:  novence login --email you@example.com\n" +
+        "  Lost key:     novence login --recover --email you@example.com");
+}

package/dist/lib/errors.js

@@ -27,10 +27,13 @@ export function explain(err, ctx) {
         const { message: detail, status } = err;
         switch (status) {
             case 401:
-            case 403:
                 return (`${detail}\n` +
                     "  Your API key was rejected. It may be revoked, or from another environment.\n" +
-                    "  Sign in again:  novence login");
+                    "  Lost or revoked key:  novence login --recover --email you@example.com");
+            case 403:
+                return (`${detail}\n` +
+                    "  This key lacks permission for that action (project or member keys are limited).\n" +
+                    "  Check which key is in use:  novence whoami");
             case 402:
                 return (`${detail}\n` +
                     "  Redeploy an existing project instead:  novence deploy --project <id>\n" +

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "novence",
-  "version": "0.2.0",
-  "description": "CLI for Novence — deploy a static site to the edge in one command.",
+  "version": "0.3.0",
+  "description": "CLI for Novence \u2014 deploy a static site to the edge in one command.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -39,15 +39,18 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test src/commands/login.test.ts src/commands/keys.test.ts",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
     "@novence/sdk": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
     "typescript": "^5.7.2"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
-}
+}