novence 0.1.4 → 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,13 +81,50 @@ 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 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`
+(mode 0600), serves it on the first free `127.0.0.1` port from 8765, and opens the browser at
+that exact URL. Press Ctrl+C to stop; the file (it holds a live `mgmt_` token) is deleted.
+
+- Uses your saved API key. Without one, it signs you in with an email code instead.
+- `--port <n>` first port to try, `--no-open` print the URL only, `--email <email>` skip the prompt.
+- `--ttl <minutes>` session length 5–480 (default 30). Sessions over 30 minutes can view usage
+  and open billing, but cannot manage team members.
+- In the page, **Switch account** signs in with an email code when the session expires.
+
 Every command accepts `--json`. Unknown flags are rejected rather than ignored,
 so a typo like `--nmae` fails loudly instead of silently deploying under the
 default name.
@@ -116,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/dashboard.d.ts

@@ -0,0 +1,2 @@
+import { type ParsedArgs } from "../lib/args.js";
+export declare function dashboardCommand(args: ParsedArgs): Promise<void>;

package/dist/commands/dashboard.js

@@ -0,0 +1,182 @@
+import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { CONSOLE_INJECT_MARKER, Novence, requestSessionOtp, verifySessionOtp, } from "@novence/sdk";
+import { flagBool, flagString } from "../lib/args.js";
+import { openInBrowser } from "../lib/browser.js";
+import { loadApiKey, resolveApiBase } from "../lib/config.js";
+import { explain } from "../lib/errors.js";
+import { fail, isJsonMode, json, prompt, result, step, withSpin } from "../lib/ui.js";
+const DEFAULT_PORT = 8765;
+/** Ports tried after the first before falling back to an ephemeral one. */
+const PORT_SCAN = 20;
+const CONSOLE_FILE = "novence-console.html";
+const CONSOLE_DIR = join(homedir(), ".novence", "console");
+export async function dashboardCommand(args) {
+    const apiBase = resolveApiBase(flagString(args.flags, "api"));
+    const startPort = parsePort(flagString(args.flags, "port"));
+    const ttlMinutes = parseTtl(flagString(args.flags, "ttl"));
+    let loaded;
+    try {
+        loaded = await loadKit(args, apiBase, ttlMinutes);
+    }
+    catch (err) {
+        fail(explain(err, { apiBase }));
+    }
+    const html = injectConsole(loaded.kit, loaded.token);
+    const filePath = writeConsoleFile(html);
+    const server = createServer((req, res) => serveConsole(req, res, html, server));
+    const port = await listenOnFreePort(server, startPort);
+    const url = `http://127.0.0.1:${port}/${CONSOLE_FILE}`;
+    const shutdown = () => {
+        server.close();
+        rmSync(filePath, { force: true });
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    if (isJsonMode()) {
+        json({ ok: true, url, port, file: filePath, expiresAt: loaded.kit.session?.expiresAt ?? null });
+    }
+    else {
+        if (port !== startPort)
+            step(`Port ${startPort} is busy — using ${port}.`);
+        step(`Serving your console on 127.0.0.1:${port}. Press Ctrl+C to stop (deletes ${filePath}).`);
+        result(url);
+    }
+    if (!flagBool(args.flags, "no-open") && !openInBrowser(url)) {
+        step("Could not launch a browser — open the URL above.");
+    }
+}
+async function loadKit(args, apiBase, ttlMinutes) {
+    const apiKey = loadApiKey();
+    if (apiKey) {
+        const keyClient = new Novence({ apiKey, baseUrl: apiBase });
+        if (ttlMinutes === undefined) {
+            const kit = await withSpin("Fetching your console…", () => keyClient.account.consoleKit());
+            if (!kit.session?.token)
+                throw new Error("console-kit did not return a session token");
+            return { kit, token: kit.session.token };
+        }
+        const session = await keyClient.account.createSession({ ttlMinutes });
+        return kitForSession(session.token, apiBase);
+    }
+    if (isJsonMode() || flagBool(args.flags, "no-input")) {
+        fail("No saved API key. Set NOVENCE_API_KEY, run `novence login`, or run `novence dashboard` interactively to sign in with an email code.");
+    }
+    step("No saved API key — sign in with an email code instead.");
+    const email = flagString(args.flags, "email") ?? (await prompt("  Email: "));
+    if (!email.includes("@"))
+        fail(`Not a valid email: ${email}`);
+    await withSpin(`Sending a code to ${email}…`, () => requestSessionOtp(email, apiBase));
+    const code = await prompt("  6-digit code from your email: ");
+    if (!/^[0-9]{6}$/.test(code))
+        fail("Enter the 6-digit code from the email.");
+    const session = await verifySessionOtp(email, code, { ttlMinutes, baseUrl: apiBase });
+    return kitForSession(session.token, apiBase);
+}
+/** console-kit with a mgmt_ token reuses that session instead of minting another. */
+async function kitForSession(token, apiBase) {
+    const mgmtClient = new Novence({ apiKey: token, baseUrl: apiBase });
+    const kit = await withSpin("Fetching your console…", () => mgmtClient.account.consoleKit());
+    return { kit, token };
+}
+function injectConsole(kit, token) {
+    const template = kit.htmlTemplate;
+    if (!template?.includes(CONSOLE_INJECT_MARKER)) {
+        fail("The console template is missing its injection marker. Update the CLI: npm i -g novence@latest");
+    }
+    const payload = `window.__NOVENCE_SNAPSHOT__=${scriptJson(kit.snapshot ?? null)};` +
+        `window.__NOVENCE_MGMT_TOKEN__=${scriptJson(token)};`;
+    return template.replace(CONSOLE_INJECT_MARKER, () => payload);
+}
+/** JSON that cannot close the surrounding <script> tag. */
+function scriptJson(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+/** Outside the working directory (agents commit scratch dirs); holds a live token, so 0600. */
+function writeConsoleFile(html) {
+    mkdirSync(CONSOLE_DIR, { recursive: true, mode: 0o700 });
+    const filePath = join(CONSOLE_DIR, CONSOLE_FILE);
+    writeFileSync(filePath, html, { mode: 0o600 });
+    chmodSync(filePath, 0o600);
+    return filePath;
+}
+function serveConsole(req, res, html, server) {
+    const port = server.address().port;
+    // DNS rebinding: a hostile page can resolve its own name to 127.0.0.1 and read this response.
+    const allowedHosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
+    if (!allowedHosts.has(req.headers.host ?? "")) {
+        res.writeHead(403, { "Content-Type": "text/plain" }).end("Forbidden");
+        return;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        res.writeHead(405, { Allow: "GET, HEAD" }).end();
+        return;
+    }
+    const path = (req.url ?? "/").split("?")[0];
+    if (path === "/") {
+        res.writeHead(302, { Location: `/${CONSOLE_FILE}` }).end();
+        return;
+    }
+    if (path !== `/${CONSOLE_FILE}`) {
+        res.writeHead(404, { "Content-Type": "text/plain" }).end("Not found");
+        return;
+    }
+    res.writeHead(200, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+    });
+    res.end(req.method === "HEAD" ? undefined : html);
+}
+async function listenOnFreePort(server, startPort) {
+    const candidates = Array.from({ length: PORT_SCAN + 1 }, (_, i) => startPort + i).filter((p) => p <= 65535);
+    for (const port of [...candidates, 0]) {
+        try {
+            return await listen(server, port);
+        }
+        catch (err) {
+            if (err.code !== "EADDRINUSE")
+                throw err;
+        }
+    }
+    fail("Could not bind a local port for the console.");
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off("listening", onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve(server.address().port);
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, "127.0.0.1");
+    });
+}
+function parsePort(raw) {
+    if (raw === undefined)
+        return DEFAULT_PORT;
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        fail(`Invalid --port: ${raw}`);
+    return port;
+}
+function parseTtl(raw) {
+    if (raw === undefined)
+        return undefined;
+    const minutes = Number(raw);
+    if (!Number.isInteger(minutes) || minutes < 5 || minutes > 480) {
+        fail(`Invalid --ttl: ${raw} (minutes, 5–480)`);
+    }
+    return minutes;
+}

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/deploy.js

@@ -42,9 +42,12 @@ async function waitUntilLive(client, projectId) {
         let lastStatus = "";
         while (Date.now() - startedAt < POLL_TIMEOUT_MS) {
             const { deployment } = await client.deployments.latest(projectId);
-            if (deployment.status !== lastStatus) {
-                spinner.update(`${deployment.status}…`);
-                lastStatus = deployment.status;
+            const label = deployment.status === "queued" && deployment.queuePosition
+                ? `queued for checks (position ${deployment.queuePosition})`
+                : deployment.status;
+            if (label !== lastStatus) {
+                spinner.update(`${label}…`);
+                lastStatus = label;
             }
             if (deployment.status === "live") {
                 spinner.stop("Live");
@@ -81,6 +84,8 @@ function reportChecks(deployment) {
     else if (checks.passed === true) {
         step("Checks passed");
     }
+    for (const warning of checks.warnings ?? [])
+        warn(warning);
 }
 export async function deployCommand(args) {
     const apiBase = resolveApiBase(flagString(args.flags, "api"));

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 {
@@ -33,22 +35,84 @@ export async function keysCommand(args) {
             }
             return;
         }
+        if (sub === "create") {
+            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, key: res.key, savedTo });
+                return;
+            }
+            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") {
             const id = args.positionals[1];
             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 revoke <id>`);
+        fail(`Unknown subcommand: ${sub}\n  Usage: novence keys list | novence keys create <name> | novence keys revoke <id>`);
     }
     catch (err) {
         fail(explain(err, { apiBase }));

package/dist/commands/login.js

@@ -1,39 +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 { flagString } from "../lib/args.js";
-import { fail, prompt, result, withSpin } from "../lib/ui.js";
+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, 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);
-        saveApiKey(issued.apiKey);
-        result(`Key reissued for account ${issued.accountId} → ${credentialsPath()}`);
-        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,26 +1,14 @@
-import { spawn } from "node:child_process";
 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";
 import { fail, isJsonMode, json, result, siteUrl, step } from "../lib/ui.js";
-/** Platform opener; falls back to printing the URL when there is no GUI. */
-function openInBrowser(url) {
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    try {
-        const child = spawn(cmd, [url], { stdio: "ignore", detached: true });
-        child.unref();
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 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";
@@ -18,6 +18,7 @@ import { checksCommand } from "./commands/checks.js";
 import { rollbackCommand } from "./commands/rollback.js";
 import { dataCommand } from "./commands/data.js";
 import { siteMcpCommand } from "./commands/site-mcp.js";
+import { dashboardCommand } from "./commands/dashboard.js";
 const HELP = `
   novence — deploy a static site to the edge
 
@@ -31,11 +32,32 @@ 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), 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
     novence claim               Attach an email to an anonymous deploy
     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)
+    --no-open                   Print the URL without opening a browser
+    --email <email>             Email for code sign-in when no API key is saved
+    --ttl <minutes>             Session length 5–480 (default 30; >30 drops member management)
 
   Deploy
     novence deploy              Auto-detects dist, build, out, public, _site
@@ -60,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
 
@@ -67,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
@@ -97,14 +121,16 @@ 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"],
+        login: ["email", "recover", "revoke-all", "code"],
         whoami: [],
         rollback: ["project", "deployment"],
         data: ["project"],
         "site-mcp": ["project"],
+        dashboard: ["port", "no-open", "email", "ttl"],
+        console: ["port", "no-open", "email", "ttl"],
     };
     const allowed = ALLOWED[args.command];
     if (allowed) {
@@ -112,6 +138,7 @@ async function main() {
         if (problem)
             fail(problem);
     }
+    setKeyName(flagString(args.flags, "key-name"));
     switch (args.command) {
         case "deploy":
             return deployCommand(args);
@@ -138,6 +165,9 @@ async function main() {
             return dataCommand(args);
         case "site-mcp":
             return siteMcpCommand(args);
+        case "dashboard":
+        case "console":
+            return dashboardCommand(args);
         default:
             fail(`Unknown command: ${args.command}\n  Run \`novence --help\` for usage.`);
     }

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

@@ -0,0 +1,2 @@
+/** Platform opener; falls back to printing the URL when there is no GUI. */
+export declare function openInBrowser(url: string): boolean;

package/dist/lib/browser.js

@@ -0,0 +1,13 @@
+import { spawn } from "node:child_process";
+/** Platform opener; falls back to printing the URL when there is no GUI. */
+export function openInBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(cmd, [url], { stdio: "ignore", detached: true });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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.1.4",
-  "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.2.6"
+    "@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"
   }
-}
+}