@cervio/cli 1.0.1 → 1.1.0

package/README.md

@@ -34,11 +34,46 @@ cervio push --changelog "…" --expect-host https://your-instance.cervio.app
 (`cervio push` without `--dev`) so the host creates the plugin. Only then can
 `cervio push --dev` upload a scratch build of it.
 
+## Signing in
+
+`cervio login --host <url>` picks the right method for where it runs. No token is ever
+typed, pasted or printed:
+
+| Where | What happens |
+|---|---|
+| Your computer | Cervio opens in the browser; you sign in (MFA included) and allow **Cervio CLI**. The token comes back to the CLI on a `127.0.0.1` callback (OAuth authorization code + PKCE). |
+| No browser here (containers, Claude Code on the web, SSH; or `--device`) | The CLI prints a link and a code such as `BCDF-GHJK`. Open the link in any browser, phone included, sign in and approve. The CLI waits and receives the token (OAuth device flow, RFC 8628). |
+| CI | A personal access token from standard input: `cervio login --host <url> --with-token < token.txt`, or `CERVIO_TOKEN`. |
+
+The login lasts: the CLI refreshes its one-hour access token by itself, for up to 90 days.
+It is saved in the system keychain (macOS Keychain, Windows Credential Manager, libsecret)
+when there is one, otherwise in `~/.cervio/credentials.json` (mode 0600). Revoke it any time
+in Cervio → Profile → Security; `cervio logout` forgets it locally.
+
+### With an AI agent (Claude Code and others)
+
+Let the agent run the CLI, not see your credentials:
+
+```bash
+cervio login --host https://your-org.cervio.app --dev-only --device --no-wait
+# the agent shows you the link and the code; you approve in your browser, then:
+cervio login --resume
+```
+
+- `--dev-only` asks for `plugin:dev` instead of `plugin:push`: the agent can push and try
+  builds on the dev channel, a release (`cervio push`) is refused by the host. Publish
+  yourself, or from CI.
+- `--no-wait` / `--resume` split the login in two short commands, so an agent with a
+  command timeout does not have to wait for you.
+- The code on screen gives no access by itself: the approval needs your Cervio session.
+  Check that the code in the browser matches the one in the terminal.
+- In Claude Code on the web, allow your Cervio host in the environment's network settings.
+
 ## Configuration
 
 | File | Purpose |
 |---|---|
-| `~/.cervio/credentials.json` | `{ "<host>": { "token": "..." } }` - saved by `cervio login`, one token per host. |
+| `~/.cervio/credentials.json` | One entry per host, saved by `cervio login`: a pointer to the system keychain, or the credential itself (mode 0600) where there is no keychain. |
 | `~/.cervio/state.json` | `{ "lastHost": "<host>" }` - last host successfully pushed to, used for the multi-instance guard. |
 | `./cervio.json` | Per-project config: `{ "host": "...", "plugin_key": "...", "route_slug": "...", "dev_conflict_minutes": 30 }`. |
 
@@ -46,21 +81,24 @@ Env overrides:
 
 - `CERVIO_URL` - host URL (wins over `cervio.json`, loses to an explicit `--host` flag)
 - `CERVIO_TOKEN` - bearer token (wins over `~/.cervio/credentials.json` entirely)
-- `CERVIO_CONFIG_DIR` - folder for `credentials.json` and `state.json` instead of `~/.cervio` (useful on CI runners)
+- `CERVIO_CONFIG_DIR` - folder for `credentials.json` and `state.json` instead of `~/.cervio` (useful on CI runners; the keychain is not used with it)
+- `CERVIO_KEYCHAIN=off` - never use the system keychain
 
 Host resolution order for most commands: `--host` flag → `CERVIO_URL` → `cervio.json` `"host"`.
-Token resolution order: `CERVIO_TOKEN` → `~/.cervio/credentials.json` entry for the resolved host.
+Token resolution order: `CERVIO_TOKEN` → the saved login for the resolved host (refreshed when it is about to expire).
 
 Do not duplicate multi-instance guidance here - use the auth-instances docs (or `cervio whoami` /
 `--expect-host` / `--yes` as documented below).
 
-## PAT scopes
+## Scopes
 
-The plugin admin API is scope-gated. A personal access token used with this CLI needs:
+The plugin admin API is scope-gated. `cervio login` asks for `plugin:read plugin:push`
+(`plugin:read plugin:dev` with `--dev-only`); a personal access token needs:
 
 | Scope | Commands |
 |---|---|
-| **`plugin:push`** | `push`, `rollback`, `route set` (implies `plugin:read`) |
+| **`plugin:push`** | `push`, `rollback`, `route set` (implies `plugin:dev` and `plugin:read`) |
+| **`plugin:dev`** | `push --dev` only, for agents and automation (implies `plugin:read`) |
 | **`plugin:read`** | `status`, `versions`, `download`, `doctor` entity check (`GET /api/v1/entities`), `route set` slug lookup |
 | **`admin:read` / `admin:write`** | Admin REST (`/api/v1/admin/**`) - not needed for CLI plugin commands |
 | **`records:read` / `records:write`** | Entity records/documents API - not needed for CLI plugin commands |
@@ -73,7 +111,8 @@ declares scopes. Use **`plugin:read` + `plugin:push`** for this CLI.
 
 | Command | Flags |
 |---|---|
-| `login` | `--host <url>`, `--token <pat>` |
+| `login` | `--host <url>`, `--device`, `--dev-only`, `--no-wait`, `--resume`, `--with-token`, `--token <pat>`, `--json` |
+| `logout` | `--host <url>` |
 | `whoami` | `--host <url>`, `--json` |
 | `build` | _(none)_ |
 | `validate` | `--json` |
@@ -94,10 +133,25 @@ structured errors such as `host_changed` / `dev_channel_conflict`).
 
 ## Commands
 
-### `cervio login --host <url> [--token <pat>]`
+### `cervio login --host <url> [options]`
+
+Signs in (see [Signing in](#signing-in)), confirms the identity with `GET /api/v1/me`,
+saves the login and fills an empty `host` in `cervio.json`.
 
-Prompts for a personal access token (or use `--token`), saves it to `~/.cervio/credentials.json`
-keyed by host, then calls `GET /api/v1/me` to confirm it works and prints the identity.
+| Option | Effect |
+|---|---|
+| `--device` | Code to approve from any browser, even where one could open here |
+| `--dev-only` | Ask for `plugin:dev`: dev-channel pushes only |
+| `--no-wait` | With the device code: print it and exit; `cervio login --resume` finishes |
+| `--resume` | Finish a device login started with `--no-wait` |
+| `--with-token` | Read a personal access token from standard input |
+| `--token <pat>` | A token as an argument: it ends up in the shell history, prefer `--with-token` |
+| `--json` | Machine-readable output (the device code too) |
+
+### `cervio logout [--host <url>]`
+
+Removes the saved login for the host (default: `host` in `cervio.json`). To end it on the
+server as well, revoke it in Cervio → Profile → Security.
 
 ### `cervio whoami [--host <url>] [--json]`
 

package/dist/cli.js

@@ -7,8 +7,10 @@ import { promises, openAsBlob, watch } from 'fs';
 import path from 'path';
 import { validatePluginDir, validatePluginZipBuffer, parseManifestObject, packPlugin, PLUGIN_ARTIFACT_SOFT_STRONG_WARN_BYTES, PLUGIN_ARTIFACT_SOFT_WARN_BYTES } from '@cervio/plugin-core';
 import os from 'os';
+import { randomBytes, createHash } from 'crypto';
+import { createServer } from 'http';
 import { createPlugin } from '@cervio/create-plugin';
-import prompts2 from 'prompts';
+import prompts from 'prompts';
 
 var CLI_VERSION = createRequire(import.meta.url)("../package.json").version;
 var USER_AGENT = `cervio-cli/${CLI_VERSION} node/${process.versions.node}`;
@@ -190,8 +192,8 @@ function runCommand(command, args, opts = {}) {
 }
 async function detectPackageManager(cwd) {
   const { existsSync } = await import('fs');
-  const path7 = await import('path');
-  if (existsSync(path7.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  const path9 = await import('path');
+  if (existsSync(path9.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
   return "npm";
 }
 function formatBytes(bytes) {
@@ -235,7 +237,6 @@ async function buildCommand() {
 function cervioConfigDir() {
   return process.env.CERVIO_CONFIG_DIR || path.join(os.homedir(), ".cervio");
 }
-var credentialsPath = () => path.join(cervioConfigDir(), "credentials.json");
 var statePath = () => path.join(cervioConfigDir(), "state.json");
 var PROJECT_CONFIG_FILENAME = "cervio.json";
 async function ensureCervioDir() {
@@ -258,18 +259,6 @@ async function writeJsonFile(filePath, data) {
 function normalizeHost(host) {
   return host.trim().replace(/\/+$/, "");
 }
-async function readCredentials() {
-  return readJsonFile(credentialsPath(), {});
-}
-async function getToken(host) {
-  const creds = await readCredentials();
-  return creds[normalizeHost(host)]?.token;
-}
-async function saveToken(host, token) {
-  const creds = await readCredentials();
-  creds[normalizeHost(host)] = { token };
-  await writeJsonFile(credentialsPath(), creds);
-}
 async function readState() {
   return readJsonFile(statePath(), {});
 }
@@ -297,13 +286,334 @@ async function readProjectConfig(cwd = process.cwd()) {
     throw err;
   }
 }
+async function writeProjectConfig(config, cwd = process.cwd()) {
+  await promises.writeFile(projectConfigPath(cwd), `${JSON.stringify(config, null, 2)}
+`);
+}
 function resolveHost(opts) {
   const host = opts.cliHost || process.env.CERVIO_URL || opts.projectConfig?.host;
   return host ? normalizeHost(host) : void 0;
 }
+
+// src/credentials.ts
+var KEYCHAIN_SERVICE = "cervio-cli";
+var credentialsPath = () => path.join(cervioConfigDir(), "credentials.json");
+async function readFileEntries() {
+  try {
+    return JSON.parse(await promises.readFile(credentialsPath(), "utf8"));
+  } catch (err) {
+    if (err?.code === "ENOENT") return {};
+    throw err;
+  }
+}
+async function writeFileEntries(entries) {
+  await promises.mkdir(cervioConfigDir(), { recursive: true, mode: 448 });
+  await promises.writeFile(credentialsPath(), `${JSON.stringify(entries, null, 2)}
+`, { mode: 384 });
+}
+async function keychain() {
+  if (process.env.CERVIO_CONFIG_DIR || process.env.CERVIO_KEYCHAIN === "off") return null;
+  try {
+    const { Entry } = await import('@napi-rs/keyring');
+    return {
+      get: (account) => new Entry(KEYCHAIN_SERVICE, account).getPassword() ?? null,
+      set: (account, secret) => new Entry(KEYCHAIN_SERVICE, account).setPassword(secret),
+      remove: (account) => {
+        new Entry(KEYCHAIN_SERVICE, account).deletePassword();
+      }
+    };
+  } catch {
+    return null;
+  }
+}
+function fromFileEntry(entry) {
+  if (!entry) return void 0;
+  if ("kind" in entry) return entry.kind === "keychain" ? "keychain" : entry;
+  return typeof entry.token === "string" ? { kind: "pat", token: entry.token } : void 0;
+}
+async function readCredential(host) {
+  const key = normalizeHost(host);
+  const entry = fromFileEntry((await readFileEntries())[key]);
+  if (entry !== "keychain") return entry;
+  const kc = await keychain();
+  try {
+    const raw = kc?.get(key);
+    return raw ? JSON.parse(raw) : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function saveCredential(host, credential) {
+  const key = normalizeHost(host);
+  const entries = await readFileEntries();
+  const kc = await keychain();
+  if (kc) {
+    try {
+      kc.set(key, JSON.stringify(credential));
+      entries[key] = { kind: "keychain" };
+      await writeFileEntries(entries);
+      return "keychain";
+    } catch {
+    }
+  }
+  entries[key] = credential;
+  await writeFileEntries(entries);
+  return "file";
+}
+async function removeCredential(host) {
+  const key = normalizeHost(host);
+  const entries = await readFileEntries();
+  const had = key in entries;
+  if (fromFileEntry(entries[key]) === "keychain") {
+    try {
+      ;
+      (await keychain())?.remove(key);
+    } catch {
+    }
+  }
+  delete entries[key];
+  await writeFileEntries(entries);
+  return had;
+}
+var CLI_SCOPES = "plugin:read plugin:push";
+var CLI_DEV_SCOPES = "plugin:read plugin:dev";
+var CLIENT_NAME = "Cervio CLI";
+var DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+var BROWSER_TIMEOUT_MS = 5 * 60 * 1e3;
+var EXPIRY_MARGIN_MS = 60 * 1e3;
+var OAuthError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+};
+async function postForm(url, body) {
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+        "User-Agent": USER_AGENT
+      },
+      body: new URLSearchParams(body)
+    });
+  } catch (err) {
+    throw new CliError(`Could not reach ${url}: ${err.message}`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const code = typeof data.error === "string" ? data.error : `http_${res.status}`;
+    const description = typeof data.error_description === "string" ? data.error_description : code;
+    throw new OAuthError(code, description);
+  }
+  return data;
+}
+function toCredential(data, clientId) {
+  const token = data;
+  if (typeof token.access_token !== "string" || typeof token.refresh_token !== "string") {
+    throw new CliError("The host returned an incomplete token response.");
+  }
+  return {
+    kind: "oauth",
+    access_token: token.access_token,
+    refresh_token: token.refresh_token,
+    expires_at: Date.now() + (typeof token.expires_in === "number" ? token.expires_in : 3600) * 1e3,
+    client_id: clientId,
+    ...typeof token.scope === "string" ? { scope: token.scope } : {}
+  };
+}
+async function assertHostSupportsLogin(host) {
+  let metadata = {};
+  try {
+    const res = await fetch(`${host}/.well-known/oauth-authorization-server`, {
+      headers: { Accept: "application/json", "User-Agent": USER_AGENT }
+    });
+    if (res.ok) metadata = await res.json();
+  } catch (err) {
+    throw new CliError(`Could not reach ${host}: ${err.message}`);
+  }
+  if (typeof metadata.device_authorization_endpoint !== "string") {
+    throw new CliError(
+      `${host} does not support signing in from the CLI yet. Create a personal access token (Integrations & API \u2192 Personal tokens, scope plugin push) and run: cervio login --host ${host} --with-token < token.txt`
+    );
+  }
+}
+async function registerClient(host, redirectUri, scopes) {
+  let res;
+  try {
+    res = await fetch(`${host}/api/oauth/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json", "User-Agent": USER_AGENT },
+      body: JSON.stringify({ client_name: CLIENT_NAME, redirect_uris: [redirectUri], scope: scopes })
+    });
+  } catch (err) {
+    throw new CliError(`Could not reach ${host}: ${err.message}`);
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || typeof data.client_id !== "string") {
+    throw new CliError(
+      `This host does not accept the CLI login (${res.status}${typeof data.error_description === "string" ? `: ${data.error_description}` : ""}). Use a personal access token: cervio login --with-token.`
+    );
+  }
+  return data.client_id;
+}
+function canOpenBrowser(env = process.env, platform = process.platform) {
+  if (env.CI || env.SSH_CONNECTION || env.SSH_TTY) return false;
+  if (platform === "darwin" || platform === "win32") return true;
+  return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+}
+function openBrowser(url) {
+  const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", '""', url.replace(/&/g, "^&")]] : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => {
+    }).unref();
+  } catch {
+  }
+}
+var b64url = (buf) => buf.toString("base64url");
+async function browserLogin(host, print, scopes = CLI_SCOPES) {
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  const state = b64url(randomBytes(16));
+  await assertHostSupportsLogin(host);
+  const server = createServer();
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = server.address().port;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+  try {
+    const clientId = await registerClient(host, redirectUri, scopes);
+    const authorizeUrl = new URL("/authorize", host);
+    authorizeUrl.search = new URLSearchParams({
+      response_type: "code",
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      scope: scopes,
+      state,
+      resource: host
+    }).toString();
+    const code = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new CliError("Login timed out: no answer from the browser in 5 minutes.")), BROWSER_TIMEOUT_MS);
+      server.on("request", (req, res) => {
+        const url = new URL(req.url ?? "/", redirectUri);
+        if (url.pathname !== "/callback") {
+          res.writeHead(404).end();
+          return;
+        }
+        const finish2 = (ok, message) => {
+          res.writeHead(ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(
+            `<!doctype html><meta charset="utf-8"><title>Cervio CLI</title><body style="font-family:system-ui;padding:3rem;text-align:center"><p>${message}</p></body>`
+          );
+        };
+        if (url.searchParams.get("state") !== state) {
+          finish2(false, "This login request does not match. Run cervio login again.");
+          return;
+        }
+        clearTimeout(timer);
+        const error = url.searchParams.get("error");
+        const value = url.searchParams.get("code");
+        if (error || !value) {
+          finish2(false, "Login cancelled. You can close this tab.");
+          reject(new CliError(error === "access_denied" ? "Login cancelled in the browser." : `Login failed: ${error ?? "no code"}.`));
+          return;
+        }
+        finish2(true, "You are signed in to the Cervio CLI. You can close this tab.");
+        resolve(value);
+      });
+      print(`Opening the browser to sign in. If it does not open, visit:
+  ${authorizeUrl.toString()}`);
+      openBrowser(authorizeUrl.toString());
+    });
+    const data = await postForm(`${host}/api/oauth/token`, {
+      grant_type: "authorization_code",
+      code,
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+      resource: host
+    });
+    return toCredential(data, clientId);
+  } finally {
+    server.close();
+  }
+}
+async function startDeviceLogin(host, scopes = CLI_SCOPES) {
+  await assertHostSupportsLogin(host);
+  const clientId = await registerClient(host, "http://127.0.0.1/cervio-cli-device", scopes);
+  let data;
+  try {
+    data = await postForm(`${host}/api/oauth/device_authorization`, {
+      client_id: clientId,
+      scope: scopes,
+      resource: host
+    });
+  } catch (err) {
+    if (err instanceof OAuthError && err.code === "http_404") {
+      throw new CliError("This host does not support device login yet. Use cervio login in a browser, or --with-token.");
+    }
+    throw err instanceof OAuthError ? new CliError(`Device login failed: ${err.message}`) : err;
+  }
+  return { ...data, client_id: clientId };
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function pollDeviceLogin(host, request, deadline) {
+  let interval = Math.max(1, request.interval || 5) * 1e3;
+  const end = deadline ?? Date.now() + request.expires_in * 1e3;
+  while (Date.now() < end) {
+    await sleep(interval);
+    try {
+      const data = await postForm(`${host}/api/oauth/token`, {
+        grant_type: DEVICE_GRANT_TYPE,
+        device_code: request.device_code,
+        client_id: request.client_id
+      });
+      return toCredential(data, request.client_id);
+    } catch (err) {
+      if (!(err instanceof OAuthError)) throw err;
+      if (err.code === "authorization_pending") continue;
+      if (err.code === "slow_down") {
+        interval += 5e3;
+        continue;
+      }
+      if (err.code === "access_denied") throw new CliError("The request was denied in the browser.");
+      if (err.code === "expired_token") break;
+      throw new CliError(`Device login failed: ${err.message}`);
+    }
+  }
+  throw new CliError("The code expired before it was approved. Run cervio login --device again.");
+}
+async function freshAccessToken(host, credential, save) {
+  if (credential.expires_at - EXPIRY_MARGIN_MS > Date.now()) return credential.access_token;
+  let data;
+  try {
+    data = await postForm(`${host}/api/oauth/token`, {
+      grant_type: "refresh_token",
+      refresh_token: credential.refresh_token,
+      client_id: credential.client_id
+    });
+  } catch (err) {
+    if (err instanceof OAuthError) {
+      throw new CliError(`Your Cervio login for ${host} has expired or was revoked. Run "cervio login --host ${host}".`);
+    }
+    throw err;
+  }
+  const next = toCredential(data, credential.client_id);
+  await save(next);
+  return next.access_token;
+}
+
+// src/auth.ts
 async function resolveToken(host) {
   if (process.env.CERVIO_TOKEN) return process.env.CERVIO_TOKEN;
-  return getToken(host);
+  const credential = await readCredential(host);
+  if (!credential) return void 0;
+  if (credential.kind === "pat") return credential.token;
+  return freshAccessToken(host, credential, (next) => saveCredential(host, next));
 }
 
 // src/context.ts
@@ -505,30 +815,120 @@ async function initCommand(name) {
   log.step("Scaffolding a new Cervio plugin...");
   await createPlugin(name ? [name] : []);
 }
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    throw new CliError("--with-token reads the token from standard input, e.g. cervio login --with-token < token.txt");
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+function printDeviceInstructions(request, json) {
+  const url = request.verification_uri_complete ?? request.verification_uri;
+  if (json) {
+    console.log(
+      JSON.stringify({
+        status: "pending",
+        verification_uri: request.verification_uri,
+        verification_uri_complete: request.verification_uri_complete,
+        user_code: request.user_code,
+        expires_in: request.expires_in
+      })
+    );
+    return;
+  }
+  log.info(`To sign in, open this page in any browser and approve the code:`);
+  log.info(`  ${url}`);
+  log.info(`  code: ${request.user_code}`);
+  log.dim(`  (expires in ${Math.round(request.expires_in / 60)} minutes; the code alone gives no access)`);
+}
 async function loginCommand(opts) {
+  const state = await readState();
+  if (opts.resume) {
+    const pending = state.pendingDevice;
+    if (!pending || opts.host && normalizeHost(opts.host) !== pending.host) {
+      throw new CliError("No device login is waiting. Run cervio login --device first.");
+    }
+    if (pending.expires_at < Date.now()) {
+      await writeState({ ...state, pendingDevice: void 0 });
+      throw new CliError("The code expired before it was approved. Run cervio login --device again.");
+    }
+    const credential2 = await pollDeviceLogin(pending.host, pending.request, pending.expires_at);
+    await writeState({ ...await readState(), pendingDevice: void 0 });
+    return finish(pending.host, credential2, !!opts.json);
+  }
   if (!opts.host) {
-    throw new CliError("--host <url> is required, e.g. cervio login --host https://app.example.com");
+    throw new CliError("--host <url> is required, e.g. cervio login --host https://your-org.cervio.app");
   }
   const host = normalizeHost(opts.host);
-  let token = opts.token;
-  if (!token) {
-    const response = await prompts2({
-      type: "password",
-      name: "token",
-      message: `Personal access token for ${host}`
+  if (opts.token || opts.withToken) {
+    if (opts.token) {
+      log.warn("--token puts the token in your shell history and process list: prefer --with-token (stdin) or a browser login.");
+    }
+    const token = opts.token ?? await readStdin();
+    if (!token) throw new CliError("No token provided.");
+    return finish(host, { kind: "pat", token }, !!opts.json);
+  }
+  const scopes = opts.devOnly ? CLI_DEV_SCOPES : CLI_SCOPES;
+  const useDevice = opts.device || !canOpenBrowser();
+  if (!useDevice) {
+    const credential2 = await browserLogin(host, (msg) => log.info(msg), scopes);
+    return finish(host, credential2, !!opts.json);
+  }
+  const request = await startDeviceLogin(host, scopes);
+  printDeviceInstructions(request, !!opts.json);
+  if (opts.wait === false) {
+    await writeState({
+      ...state,
+      pendingDevice: { host, request, expires_at: Date.now() + request.expires_in * 1e3 }
     });
-    token = typeof response.token === "string" ? response.token.trim() : "";
+    if (!opts.json) log.dim("  then run: cervio login --resume");
+    return;
   }
-  if (!token) {
-    throw new CliError("No token provided.");
+  if (!opts.json) log.dim("  waiting for approval\u2026");
+  const credential = await pollDeviceLogin(host, request);
+  return finish(host, credential, !!opts.json);
+}
+async function finish(host, credential, json) {
+  const token = credential.kind === "pat" ? credential.token : credential.access_token;
+  const me = await createApiClient({ host, token }).getMe();
+  const store = await saveCredential(host, credential);
+  const project = await readProjectConfig().catch(() => null);
+  const fillProjectHost = !!project && !project.host?.trim();
+  if (project && fillProjectHost) await writeProjectConfig({ ...project, host });
+  if (json) {
+    console.log(
+      JSON.stringify({
+        status: "logged_in",
+        host,
+        user: me.email ?? me.user_id,
+        organization: me.organization_name ?? me.organization_id,
+        auth: me.auth_method,
+        stored_in: store
+      })
+    );
+    return;
   }
-  const client = createApiClient({ host, token });
-  const me = await client.getMe();
-  await saveToken(host, token);
   log.success(`Logged in to ${host}`);
   log.info(`  user:  ${me.email ?? me.user_id}`);
   log.info(`  org:   ${me.organization_name ?? me.organization_id}`);
   log.info(`  auth:  ${me.auth_method}`);
+  if (credential.kind === "oauth" && credential.scope) log.info(`  scope: ${credential.scope}`);
+  log.dim(
+    store === "keychain" ? "  saved in the system keychain" : `  saved in ${path.join(cervioConfigDir(), "credentials.json")} (readable only by you)`
+  );
+  if (fillProjectHost) log.dim(`  cervio.json host set to ${host}`);
+}
+async function logoutCommand(opts) {
+  const host = opts.host ? normalizeHost(opts.host) : (await readProjectConfig().catch(() => null))?.host;
+  if (!host) throw new CliError('--host <url> is required (or run it in a project with "host" in cervio.json).');
+  const removed = await removeCredential(host);
+  if (removed) {
+    log.success(`Logged out of ${normalizeHost(host)}`);
+    log.dim("  To revoke the login on the server too: Cervio \u2192 Profile \u2192 Security.");
+  } else {
+    log.info(`No saved login for ${normalizeHost(host)}.`);
+  }
 }
 
 // src/commands/open.ts
@@ -621,7 +1021,7 @@ async function pushCommand(opts) {
         return;
       }
     } else if (!opts.yes) {
-      const response = await prompts2({
+      const response = await prompts({
         type: "confirm",
         name: "proceed",
         message: `Last push was to ${lastHost}. Continue publishing to ${host}?`,
@@ -649,7 +1049,7 @@ async function pushCommand(opts) {
         return;
       }
       if (!opts.force) {
-        const response = await prompts2({
+        const response = await prompts({
           type: "confirm",
           name: "proceed",
           message: `Dev channel was last updated by ${conflict.updated_by_email ?? "someone else"} ${conflict.minutes_ago.toFixed(0)}m ago. Overwrite anyway?`,
@@ -731,6 +1131,16 @@ async function pushCommand(opts) {
     log.info(`  content_sha256: ${upload.version.content_sha256 ?? "(n/a)"}`);
     if (upload.reason) log.dim(`  ${upload.reason}`);
   }
+  if (upload.plugin.plugin_type === "route") await hintMissingRouteConfig(client, upload.plugin.id);
+}
+async function hintMissingRouteConfig(client, pluginId) {
+  try {
+    const { route_config } = await client.getRouteConfig(pluginId);
+    if (route_config) return;
+  } catch {
+    return;
+  }
+  log.step('Not reachable yet: run "cervio route set" to publish it at /r/<route_slug> (or set it in Admin \u2192 Plugins).');
 }
 async function safeMe(client) {
   try {
@@ -1030,7 +1440,8 @@ function action(fn) {
 }
 var program = new Command();
 program.name("cervio").description("Cervio plugin developer CLI").version(CLI_VERSION);
-program.command("login").description("Authenticate with a Cervio host and save the token").option("--host <url>", "Cervio host, e.g. https://app.example.com").option("--token <token>", "Personal access token (prompted if omitted)").action(action(loginCommand));
+program.command("login").description("Sign in to a Cervio host: in the browser, or with a code to approve from any device").option("--host <url>", "Cervio host, e.g. https://your-org.cervio.app").option("--device", "Print a code to approve from any browser (default when no browser can open here)").option("--dev-only", "Ask only for dev-channel pushes (plugin:dev): for AI agents and automation").option("--no-wait", 'With --device: print the code and exit; finish with "cervio login --resume"').option("--resume", "Finish a device login started with --no-wait").option("--with-token", "Read a personal access token from standard input (CI)").option("--token <token>", "Personal access token as an argument (ends up in shell history: prefer --with-token)").option("--json", "Output JSON").action(action(loginCommand));
+program.command("logout").description("Remove the saved login for a host").option("--host <url>", 'Cervio host (default: "host" in cervio.json)').action(action(logoutCommand));
 program.command("whoami").description("Print the current host and identity").option("--host <url>", "Override the resolved host").option("--json", "Output JSON").action(action(whoamiCommand));
 program.command("build").description("Run the project build script (pnpm/npm run build)").action(action(buildCommand));
 program.command("validate").description("Validate the plugin in the current directory").option("--json", "Output JSON").action(action(validateCommand));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cervio/cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Developer CLI for Cervio plugins: login, validate, pack, push and manage releases.",
   "keywords": [
     "cervio",
@@ -30,9 +30,12 @@
   "dependencies": {
     "commander": "^15.0.0",
     "prompts": "^2.4.2",
-    "@cervio/create-plugin": "^1.1.0",
+    "@cervio/create-plugin": "^1.1.1",
     "@cervio/plugin-core": "^1.0.1"
   },
+  "optionalDependencies": {
+    "@napi-rs/keyring": "2.1.2"
+  },
   "devDependencies": {
     "@types/node": "^26.0.0",
     "@types/prompts": "^2.4.9",