@notis_ai/cli 0.2.0-beta.116.1 → 0.2.0-beta.118.1

package/README.md

@@ -4,7 +4,7 @@ Agent-first Notis CLI for apps and generic tool execution.
 
 ## Install
 
-Use the Notis CLI through NPX. Install and sign into Notis Desktop to keep the local CLI auth profile current; do not rely on an installed `notis` command. Related skills such as `notis-cli` and `notis-apps` are delivered through normal Notis skill sync for the signed-in user.
+Use the Notis CLI through NPX; do not rely on an installed `notis` command. When Notis Desktop is signed in, its local credential remains the fastest path. On a server, container, or machine without Desktop, run `notis login` to authorize a scoped, revocable OAuth credential in the browser.
 
 For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>`.
 
@@ -12,12 +12,13 @@ For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOT
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis --help
+npx --package @notis_ai/cli@latest -- notis login
 npx --package @notis_ai/cli@latest -- notis doctor
 npx --package @notis_ai/cli@latest -- notis apps list
 npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
 ```
 
-The desktop app owns sign-in and keeps the CLI profile in sync automatically.
+Credential precedence is worktree runtime, `NOTIS_JWT`, a valid Desktop credential, then OAuth. `notis logout` revokes and removes OAuth without signing Desktop out. Use `notis login --paste-code` for the HTTPS copy-paste fallback on a remote machine.
 
 The CLI defaults to `json` output in agent or non-TTY contexts and `table` output in interactive terminals.
 
@@ -31,6 +32,44 @@ The CLI defaults to `json` output in agent or non-TTY contexts and `table` outpu
 - `--timeout-ms <n>` — HTTP timeout in milliseconds
 - `--idempotency-key <key>` — Override the generated idempotency key for mutating commands
 
+## Authentication
+
+### `npx --package @notis_ai/cli@latest -- notis login`
+
+Authorize the Notis CLI in a browser with scoped OAuth access.
+
+When to use: Use this on a machine where Notis Desktop is unavailable, signed out, or should not own CLI authentication.
+
+Options:
+- `--no-browser` — Print the authorization URL without opening a browser.
+- `--print-url` — Print the authorization URL even when opening a browser.
+- `--paste-code` — Use the copy-paste callback for SSH and headless machines.
+- `--force` — Create an independent OAuth grant even when Desktop is signed in.
+- `--timeout-seconds <n>` — How long to wait for authorization (default 300).
+- `--scope <scope>` — OAuth permission to request (repeatable).
+- `--code <code>` — Redeem the code shown in the browser after a non-interactive login.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis login`
+- `npx --package @notis_ai/cli@latest -- notis login --no-browser --print-url`
+- `npx --package @notis_ai/cli@latest -- notis login --paste-code`
+- `npx --package @notis_ai/cli@latest -- notis login --code 4f3c2b1a`
+- `npx --package @notis_ai/cli@latest -- notis login --force`
+
+### `npx --package @notis_ai/cli@latest -- notis logout`
+
+Revoke and remove the scoped OAuth credential for the active CLI profile.
+
+When to use: Use this to disconnect the command line without signing Notis Desktop out.
+
+Options:
+- `--all-profiles` — Remove OAuth credentials from every CLI profile.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis logout`
+- `npx --package @notis_ai/cli@latest -- notis logout --all-profiles`
+
+
 ## Apps
 
 ### `npx --package @notis_ai/cli@latest -- notis apps list`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.0-beta.116.1",
+  "version": "0.2.0-beta.118.1",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {

package/skills/notis-apps/cli.md

@@ -8,7 +8,7 @@ Important: `notis apps deploy` updates the linked installed app. It is not an ap
 
 ## Setup
 
-Install and sign into Notis Desktop to keep the CLI profile current. Run the CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`. Related skills such as `notis-cli` and `notis-apps` are delivered through normal Notis skill sync for the signed-in user.
+Sign into Notis Desktop or run `npx --package @notis_ai/cli@latest -- notis login` to authorize the CLI. Run commands through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`.
 
 For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>` and use `--api-base <server-url>` when targeting a non-default server.
 

package/skills/notis-cli/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: notis-cli
 description: Use when agents should work through the Notis CLI, especially to develop Notis apps locally or to access Notis, Composio, or MCP tools they do not currently have loaded directly.
+feature_flag: cli_access
+mcp_resource: true
+mcp_tool_patterns: []
 ---
 
 # Notis CLI Skill

package/skills/notis-query/cli.md

@@ -4,7 +4,7 @@ Use the generic `notis tools` workflow through NPX for native Notis Database ope
 
 ## Setup
 
-Install and sign into Notis Desktop to keep the CLI profile current. Run the CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"`.
+Sign into Notis Desktop or run `npx --package @notis_ai/cli@latest -- notis login` to authorize the CLI. Run commands through NPX, for example `npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"`.
 
 For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>` and use `--api-base <server-url>` when targeting a non-default server.
 

package/src/command-specs/apps.js

@@ -55,6 +55,7 @@ import { getAvailablePort } from '../runtime/ports.js';
 import { getCliMode } from '../runtime/cli-mode.js';
 import { composeStoreScreenshot } from '../runtime/store-screenshot.js';
 import { httpRequest } from '../runtime/transport.js';
+import { ensureFreshOAuthCredential } from '../runtime/oauth.js';
 import {
   localNotisToolSlug,
   nextIdempotencyKey,
@@ -1087,6 +1088,12 @@ async function appsVerifyHandler(ctx) {
 
   let linkedState = null;
   if (mode === 'live') {
+    if (
+      ctx.runtime.credentialKind === 'oauth'
+      && !await ensureFreshOAuthCredential(ctx.runtime)
+    ) {
+      throw usageError('Live verify mode requires a current OAuth grant. Run `notis login` and retry.');
+    }
     if (!ctx.runtime.jwt) {
       throw usageError('Live verify mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
     }
@@ -1301,6 +1308,12 @@ async function appsScreenshotHandler(ctx) {
 
   let linkedState = null;
   if (mode === 'live') {
+    if (
+      ctx.runtime.credentialKind === 'oauth'
+      && !await ensureFreshOAuthCredential(ctx.runtime)
+    ) {
+      throw usageError('Live mode requires a current OAuth grant. Run `notis login` and retry.');
+    }
     if (!ctx.runtime.jwt) {
       throw usageError('Live mode requires CLI auth. Open the Notis desktop app, sign in, and retry.');
     }
@@ -1539,6 +1552,12 @@ async function appsPullHandler(ctx) {
     toolName: GET_APP_TOOL,
     arguments_: { app_id: appId },
   });
+  if (
+    ctx.runtime.credentialKind === 'oauth'
+    && !await ensureFreshOAuthCredential(ctx.runtime)
+  ) {
+    throw usageError('Pulling app source requires a current OAuth grant. Run `notis login` and retry.');
+  }
   const app = result.payload?.app || {};
   const defaultDir = app.slug || slugify(app.name) || appId;
   const targetDir = resolveProjectDir(ctx.args.dir || defaultDir);

package/src/command-specs/auth.js

@@ -0,0 +1,107 @@
+import { loginWithOAuth, logoutOAuth } from '../runtime/oauth.js';
+
+async function loginHandler(ctx) {
+  const result = await loginWithOAuth(ctx.runtime, ctx.options, ctx.output);
+  if (result.desktopFastPath) {
+    return ctx.output.emitSuccess({
+      command: 'login',
+      data: {
+        authenticated: true,
+        credential_source: result.credentialSource || 'desktop',
+      },
+      humanSummary: 'Notis Desktop already provides a valid CLI credential.',
+    });
+  }
+  if (result.agentAuthorization) {
+    return ctx.output.emitSuccess({
+      command: 'login',
+      data: result.agentAuthorization,
+      humanSummary: 'Open the authorization URL in a browser to continue.',
+    });
+  }
+  return ctx.output.emitSuccess({
+    command: 'login',
+    data: {
+      authenticated: true,
+      credential_source: 'oauth',
+      profile: ctx.runtime.profileName,
+      user_id: result.profile.oauth_user_id,
+      scopes: result.profile.oauth_scopes,
+      access_expires_at: result.profile.oauth_access_expires_at,
+      refresh_expires_at: result.profile.oauth_refresh_expires_at,
+    },
+    humanSummary: `Notis CLI is authorized for profile "${ctx.runtime.profileName}".`,
+  });
+}
+
+async function logoutHandler(ctx) {
+  const result = await logoutOAuth(ctx.runtime, {
+    allProfiles: Boolean(ctx.options.allProfiles),
+  });
+  return ctx.output.emitSuccess({
+    command: 'logout',
+    data: {
+      oauth_connected: false,
+      cleared_profiles: result.profiles,
+    },
+    humanSummary: ctx.options.allProfiles
+      ? 'OAuth credentials were removed from all CLI profiles.'
+      : `OAuth credentials were removed from profile "${ctx.runtime.profileName}".`,
+  });
+}
+
+export const authCommandSpecs = [
+  {
+    command_path: ['login'],
+    summary: 'Authorize the Notis CLI in a browser with scoped OAuth access.',
+    when_to_use:
+      'Use this on a machine where Notis Desktop is unavailable, signed out, or should not own CLI authentication.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--no-browser', description: 'Print the authorization URL without opening a browser.' },
+        { flags: '--print-url', description: 'Print the authorization URL even when opening a browser.' },
+        { flags: '--paste-code', description: 'Use the copy-paste callback for SSH and headless machines.' },
+        { flags: '--force', description: 'Create an independent OAuth grant even when Desktop is signed in.' },
+        { flags: '--timeout-seconds <n>', description: 'How long to wait for authorization (default 300).' },
+        { flags: '--scope <scope>', description: 'OAuth permission to request (repeatable).', collect: true },
+        { flags: '--code <code>', description: 'Redeem the code shown in the browser after a non-interactive login.' },
+      ],
+    },
+    examples: [
+      'notis login',
+      'notis login --no-browser --print-url',
+      'notis login --paste-code',
+      'notis login --code 4f3c2b1a',
+      'notis login --force',
+    ],
+    output_schema:
+      'Returns credential_source, profile, user_id, scopes, and credential expiries; agent mode returns authorize_url and expires_in.',
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis logout', 'notis doctor', 'notis whoami'],
+    backend_call: { type: 'oauth', name: 'authorization_code+pkce' },
+    handler: loginHandler,
+  },
+  {
+    command_path: ['logout'],
+    summary: 'Revoke and remove the scoped OAuth credential for the active CLI profile.',
+    when_to_use:
+      'Use this to disconnect the command line without signing Notis Desktop out.',
+    args_schema: {
+      arguments: [],
+      options: [
+        { flags: '--all-profiles', description: 'Remove OAuth credentials from every CLI profile.' },
+      ],
+    },
+    examples: ['notis logout', 'notis logout --all-profiles'],
+    output_schema: 'Returns oauth_connected=false and the profiles whose OAuth credentials were removed.',
+    mutates: true,
+    idempotent: true,
+    require_auth: false,
+    related_commands: ['notis login', 'notis doctor'],
+    backend_call: { type: 'oauth', name: 'revocation' },
+    handler: logoutHandler,
+  },
+];

package/src/command-specs/index.js

@@ -4,6 +4,7 @@ import { metaCommandSpecs } from './meta.js';
 import { onboardingCommandSpecs } from './onboarding.js';
 import { diagnosticCommandSpecs } from './diagnostics.js';
 import { smokeCommandSpecs } from './smoke.js';
+import { authCommandSpecs } from './auth.js';
 
 export const GROUP_SUMMARIES = {
   apps: 'Develop, deploy, and submit Notis Apps.',
@@ -13,6 +14,7 @@ export const GROUP_SUMMARIES = {
 };
 
 export const COMMAND_SPECS = [
+  ...authCommandSpecs,
   ...onboardingCommandSpecs,
   ...appsCommandSpecs,
   ...toolsCommandSpecs,

package/src/command-specs/meta.js

@@ -1,19 +1,52 @@
 import { COMPOSIO_SEARCH_TOOLS, healthCheck, probeAuth } from './helpers.js';
 import { findCommandSpec, formatDescribe } from '../runtime/help.js';
-import { createExpiredAuthError } from '../runtime/desktop-auth.js';
-import { isJwtExpired } from '../runtime/profiles.js';
+import { createExpiredAuthError, getDesktopAuthRecovery } from '../runtime/desktop-auth.js';
+import {
+  credentialIsExpired,
+  getJwtCanonicalUserId,
+  getProfile,
+  loadConfig,
+} from '../runtime/profiles.js';
+import { ensureFreshOAuthCredential } from '../runtime/oauth.js';
+
+export const DOCTOR_TOOL_ROUNDTRIP_TIMEOUT_MS = 90_000;
+
+export function doctorToolRoundtripRuntime(runtime) {
+  return {
+    ...runtime,
+    timeoutMs: Math.max(runtime.timeoutMs || 0, DOCTOR_TOOL_ROUNDTRIP_TIMEOUT_MS),
+  };
+}
 
 async function doctorHandler(ctx) {
   const checks = {
     config: 'ok',
     auth: 'missing',
+    identity: 'ok',
     health: 'unknown',
     tool_roundtrip: 'unknown',
   };
 
+  if (ctx.runtime.credentialKind === 'oauth') {
+    try {
+      await ensureFreshOAuthCredential(ctx.runtime);
+    } catch {
+      // Doctor still reports the remaining health and recovery checks when a
+      // refresh endpoint is unavailable or rejects the stored credential.
+    }
+  }
+  let profile = getProfile(loadConfig(ctx.runtime.worktreeRuntime), ctx.runtime.profileName);
   checks.auth = ctx.runtime.jwt
-    ? (isJwtExpired(ctx.runtime.jwt) ? 'expired' : 'configured')
+    ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
     : 'missing';
+  const desktopUserId = getJwtCanonicalUserId(profile.jwt);
+  if (
+    desktopUserId
+    && profile.oauth_user_id
+    && desktopUserId !== profile.oauth_user_id
+  ) {
+    checks.identity = 'error';
+  }
 
   try {
     await healthCheck(ctx.runtime);
@@ -24,8 +57,15 @@ async function doctorHandler(ctx) {
 
   if (ctx.runtime.jwt) {
     try {
-      const payload = await probeAuth(ctx.runtime);
+      // Tool discovery may have to query several connected MCP servers on a
+      // cold local backend. A diagnostic must not report a false failure just
+      // because that legitimate roundtrip exceeds the general 30s default.
+      const payload = await probeAuth(doctorToolRoundtripRuntime(ctx.runtime));
       checks.tool_roundtrip = Array.isArray(payload.toolkit_connection_statuses) ? 'ok' : 'error';
+      profile = getProfile(loadConfig(ctx.runtime.worktreeRuntime), ctx.runtime.profileName);
+      checks.auth = ctx.runtime.jwt
+        ? (credentialIsExpired(ctx.runtime, profile) ? 'expired' : 'configured')
+        : 'missing';
     } catch {
       checks.tool_roundtrip = 'error';
     }
@@ -33,7 +73,7 @@ async function doctorHandler(ctx) {
 
   const hints = [];
   if (checks.auth === 'missing') {
-    hints.push({ command: 'Open the Notis desktop app and sign in', reason: 'Configure CLI credentials' });
+    hints.push(...getDesktopAuthRecovery(ctx.runtime, { mode: 'missing' }).hints);
   } else if (checks.auth === 'expired') {
     hints.push(...createExpiredAuthError(ctx.runtime).hints);
   }
@@ -43,12 +83,27 @@ async function doctorHandler(ctx) {
   if (checks.tool_roundtrip === 'error') {
     hints.push({ command: 'notis whoami', reason: 'Verify your account and permissions' });
   }
+  if (checks.identity === 'error') {
+    hints.push({
+      command: 'notis logout',
+      reason: 'Desktop and OAuth credentials identify different accounts; remove the independent OAuth grant or sign Desktop back into the same account',
+    });
+  }
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
       profile: ctx.runtime.profileName,
       api_base: ctx.runtime.apiBase,
+      credential_source: ctx.runtime.credentialKind || null,
+      ...(ctx.runtime.credentialKind === 'oauth'
+        ? {
+            oauth_client_id: profile.oauth_client_id || null,
+            oauth_scopes: profile.oauth_scopes || [],
+            oauth_access_expires_at: profile.oauth_access_expires_at || null,
+            oauth_refresh_expires_at: profile.oauth_refresh_expires_at || null,
+          }
+        : {}),
       checks,
     },
     humanSummary: `Doctor checks completed for profile ${ctx.runtime.profileName}`,
@@ -72,16 +127,23 @@ function decodeJwtUserId(jwt) {
   }
 }
 
+export function activeRuntimeUserId(runtime) {
+  return runtime.credentialKind === 'oauth'
+    ? runtime.oauthUserId
+    : decodeJwtUserId(runtime.jwt);
+}
+
 async function whoamiHandler(ctx) {
   const payload = await probeAuth(ctx.runtime);
   const toolkits = payload.toolkit_connection_statuses || [];
-  const userId = decodeJwtUserId(ctx.runtime.jwt);
+  const userId = activeRuntimeUserId(ctx.runtime);
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
       profile: ctx.runtime.profileName,
       api_base: ctx.runtime.apiBase,
+      credential_source: ctx.runtime.credentialKind || null,
       user_id: userId,
       toolkit_count: toolkits.length,
       toolkits: toolkits.map((t) => t.toolkit),

package/src/command-specs/onboarding.js

@@ -4,7 +4,12 @@ import { fileURLToPath } from 'node:url';
 
 import { CliError, EXIT_CODES } from '../runtime/errors.js';
 import { getDesktopAuthRecovery, waitForDesktopAuth } from '../runtime/desktop-auth.js';
-import { getJwt, isJwtExpired, loadConfig } from '../runtime/profiles.js';
+import {
+  credentialIsExpired,
+  getProfile,
+  loadConfig,
+} from '../runtime/profiles.js';
+import { ensureFreshOAuthCredential, loginWithOAuth } from '../runtime/oauth.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const BUNDLED_BRIEF_PATH = join(HERE, '..', '..', 'skills', 'notis-onboarding', 'BRIEF.md');
@@ -85,7 +90,20 @@ async function requestSignupLink(apiBase, { email, useCases }) {
 async function startHandler(ctx) {
   const { runtime, options, output } = ctx;
   const apiBase = runtime.apiBase;
-  const authenticated = Boolean(runtime.jwt) && !isJwtExpired(runtime.jwt);
+  if (runtime.credentialKind === 'oauth') {
+    try {
+      await ensureFreshOAuthCredential(runtime);
+    } catch {
+      // A failed refresh is equivalent to no usable session here. Interactive
+      // starts may still authorize again; brief-only and agent runs surface
+      // the normal authentication recovery below.
+    }
+  }
+  let authenticated = Boolean(runtime.jwt)
+    && !credentialIsExpired(
+      runtime,
+      getProfile(loadConfig(runtime.worktreeRuntime), runtime.profileName),
+    );
 
   // Safe to re-run: an already-authenticated machine skips straight to the brief.
   // Agents retry commands, and a second signup would invalidate the first email.
@@ -108,6 +126,54 @@ async function startHandler(ctx) {
     });
   }
 
+  if (
+    !options.email
+    && !runtime.agentMode
+    && !runtime.nonInteractive
+    && options.wait !== false
+  ) {
+    let authorization;
+    let authorizationError;
+    try {
+      authorization = await loginWithOAuth(runtime, { browser: true }, output);
+    } catch (error) {
+      // Keep the original OAuth failure while checking whether another process
+      // completed authentication before this attempt failed.
+      authorizationError = error;
+      authorization = null;
+    }
+    if (authorization?.agentAuthorization) {
+      return output.emitSuccess({
+        command: 'start',
+        data: { authenticated: false, ...authorization.agentAuthorization },
+        humanSummary: 'Open the authorization URL to finish signing in.',
+        renderHuman: () => `Authorize Notis CLI: ${authorization.agentAuthorization.authorize_url}`,
+      });
+    }
+    // A failed authorization leaves the stale credential that got us here in
+    // place, so re-apply the same expiry test used above rather than reporting
+    // a machine as signed in on the strength of a dead token.
+    authenticated = Boolean(runtime.jwt)
+      && !credentialIsExpired(runtime, getProfile(loadConfig(runtime.worktreeRuntime), runtime.profileName));
+    if (authenticated) {
+      const brief = await fetchBrief(apiBase, runtime.timeoutMs);
+      return output.emitSuccess({
+        command: 'start',
+        data: {
+          authenticated: true,
+          credential_source: runtime.credentialKind,
+          brief: brief.markdown,
+          brief_source: brief.source,
+        },
+        humanSummary: 'Notis CLI is authenticated. Follow the onboarding brief below.',
+        renderHuman: () => brief.markdown || 'Notis CLI is authenticated.',
+      });
+    }
+    if (authorizationError) {
+      throw authorizationError;
+    }
+  }
+
   if (!options.email) {
     // The one point in the flow that has to stop and talk to the human.
     throw new CliError({
@@ -143,8 +209,29 @@ async function startHandler(ctx) {
   const timeoutMs = Number(options.waitTimeoutMs) > 0 ? Number(options.waitTimeoutMs) : 300_000;
   const jwt = await waitForDesktopAuth({
     loadConfig,
-    getJwt,
-    isJwtExpired,
+    getJwt: (config, profileName) => {
+      const profile = getProfile(config, profileName);
+      if (
+        profile.jwt
+        && !credentialIsExpired(
+          { credentialKind: 'desktop', jwt: profile.jwt },
+          profile,
+        )
+      ) {
+        return profile.jwt;
+      }
+      if (
+        profile.oauth_access_token
+        && !credentialIsExpired(
+          { credentialKind: 'oauth', jwt: profile.oauth_access_token },
+          profile,
+        )
+      ) {
+        return profile.oauth_access_token;
+      }
+      return undefined;
+    },
+    isJwtExpired: () => false,
     profileName: runtime.profileName,
     timeoutMs,
     onTick: (remaining) => {
@@ -165,7 +252,8 @@ async function startHandler(ctx) {
           command: `Install Notis Desktop: ${signup.desktop_download_url || 'https://notis.ai/channels/desktop-app'}`,
           reason: 'The desktop app is what writes the CLI credential',
         },
-        { command: 'notis start --brief-only', reason: 'Resume once the desktop app is signed in' },
+        { command: 'notis login', reason: 'Authorize this machine directly in a browser' },
+        { command: 'notis start --brief-only', reason: 'Resume once authentication is complete' },
         { command: 'notis doctor', reason: 'Re-check config, auth, and API reachability' },
       ],
     });
@@ -183,7 +271,7 @@ async function startHandler(ctx) {
 export const onboardingCommandSpecs = [
   {
     command_path: ['start'],
-    summary: 'Create or access a Notis account and wait for the desktop app to sign the CLI in.',
+    summary: 'Create or access a Notis account and authorize the CLI.',
     when_to_use:
       'Run this first on a new machine, before anything that needs auth. Safe to re-run: an already-signed-in machine just reprints the onboarding brief.',
     args_schema: {

package/src/runtime/desktop-auth.js

@@ -56,8 +56,8 @@ export function getDesktopAuthRecovery(runtime, { mode = 'expired' } = {}) {
     // Leads the list: a machine that was never signed in may not even have an
     // account yet, and `notis start` covers both cases.
     hints.unshift({
-      command: 'notis start --email <address>',
-      reason: 'Create or access a Notis account and sign this machine in',
+      command: 'notis login',
+      reason: 'Sign in or create an account in the browser and authorize this machine',
     });
   }
   hints.push({
@@ -100,6 +100,18 @@ export async function waitForDesktopAuth({
 }
 
 export function createExpiredAuthError(runtime) {
+  if (runtime.credentialKind === 'oauth') {
+    return new CliError({
+      code: 'auth_expired',
+      message: 'Notis CLI OAuth authentication has expired',
+      exitCode: EXIT_CODES.auth,
+      details: { credential_source: 'oauth' },
+      hints: [
+        { command: 'notis login', reason: 'Authorize a new scoped CLI credential' },
+        { command: 'notis doctor', reason: 'Inspect the active credential state' },
+      ],
+    });
+  }
   if (runtime.credentialSource === 'env') {
     return new CliError({
       code: 'auth_expired',
@@ -130,6 +142,14 @@ export function createExpiredAuthError(runtime) {
 }
 
 export function createInvalidAuthHints(runtime) {
+  if (runtime?.credentialKind === 'oauth') {
+    return [
+      {
+        command: 'notis login',
+        reason: 'Authorize a new scoped CLI credential',
+      },
+    ];
+  }
   if (runtime?.credentialSource === 'env') {
     return [
       {