@notis_ai/cli 0.2.9 → 0.2.11

package/README.md

@@ -4,7 +4,7 @@ Agent-first Notis CLI for apps and generic tool execution.
 
 ## Install
 
-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.
+Use the Notis CLI through NPX; do not rely on an installed `notis` command. Run `notis login` once to authorize a scoped, revocable OAuth credential in the browser — that is how the CLI signs in everywhere, including on a machine that also runs Notis Desktop.
 
 For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>`.
 
@@ -18,7 +18,24 @@ npx --package @notis_ai/cli@latest -- notis apps list
 npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
 ```
 
-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.
+Use `notis login --paste-code` for the HTTPS copy-paste fallback on a remote machine.
+
+## Profiles
+
+A profile is one account paired with one API endpoint. Every profile keeps its own credential, so switching between them never signs any of them out.
+
+```bash
+npx --package @notis_ai/cli@latest -- notis login --profile work
+npx --package @notis_ai/cli@latest -- notis profile list
+npx --package @notis_ai/cli@latest -- notis profile use work
+npx --package @notis_ai/cli@latest -- notis --profile default tools search "..."
+```
+
+`notis logout` revokes and removes the OAuth grant for one profile; `--all-profiles` clears every one.
+
+Credential precedence within the selected profile is: an active `./dev.sh` worktree credential, then `NOTIS_JWT`, then the profile's OAuth grant.
+
+`./dev.sh` exposes its test account as a lease-backed `dev-<workspace>-<hash>` profile bound to its loopback backend. The credential stays in the worktree rather than the shared account config. That synthetic profile is the default only inside its active worktree; naming any stored profile with `--profile` runs against that real account instead.
 
 The CLI defaults to `json` output in agent or non-TTY contexts and `table` output in interactive terminals.
 
@@ -27,7 +44,7 @@ The CLI defaults to `json` output in agent or non-TTY contexts and `table` outpu
 - `--json` — Shortcut for `--output json`
 - `--output <table|json|yaml|ndjson>` — Output mode override
 - `--non-interactive` — Disable prompts
-- `--profile <name>` — Select a stored profile
+- `--profile <name>` — Run as a stored profile instead of the active one
 - `--api-base <url>` — Override the API base for one invocation
 - `--timeout-ms <n>` — HTTP timeout in milliseconds
 - `--idempotency-key <key>` — Override the generated idempotency key for mutating commands
@@ -36,37 +53,38 @@ The CLI defaults to `json` output in agent or non-TTY contexts and `table` outpu
 
 ### `npx --package @notis_ai/cli@latest -- notis login`
 
-Authorize the Notis CLI in a browser with scoped OAuth access.
+Authorize a CLI profile 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.
+When to use: Run this once per account you want the CLI to reach. Pass --profile to add a second account without signing the first one out.
 
 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 --profile work`
+- `npx --package @notis_ai/cli@latest -- notis login --profile beta --api-base https://api-beta.notis.ai`
 - `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.
+Revoke and remove the OAuth credential for one CLI profile.
 
-When to use: Use this to disconnect the command line without signing Notis Desktop out.
+When to use: Use this to disconnect a single account. Other profiles keep their credentials unless you pass --all-profiles.
 
 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 --profile work`
 - `npx --package @notis_ai/cli@latest -- notis logout --all-profiles`
 
 
@@ -352,6 +370,52 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis tools link dataforseo --reconnect --credentials - < credentials.json`
 
 
+## Profile Commands
+
+### `npx --package @notis_ai/cli@latest -- notis profile list`
+
+List every CLI profile with its account, API endpoint, and credential state.
+
+When to use: Use this to see which accounts and environments this machine can reach before choosing one.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis profile list`
+- `npx --package @notis_ai/cli@latest -- notis profile list --json`
+
+### `npx --package @notis_ai/cli@latest -- notis profile use <name>`
+
+Switch the default profile without signing any profile out.
+
+When to use: Use this to change which account and API subsequent commands target. Every other profile keeps its credential.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis profile use work`
+- `npx --package @notis_ai/cli@latest -- notis profile use default`
+
+### `npx --package @notis_ai/cli@latest -- notis profile show [name]`
+
+Show one profile in detail, including scopes and credential expiry.
+
+When to use: Use this to inspect exactly which account and endpoint a profile resolves to.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis profile show`
+- `npx --package @notis_ai/cli@latest -- notis profile show work --json`
+
+### `npx --package @notis_ai/cli@latest -- notis profile remove <name>`
+
+Delete a CLI profile from this machine.
+
+When to use: Use this after logging a profile out. Removing a still-authorized profile requires --force and leaves the grant live server-side.
+
+Options:
+- `--force` — Discard a profile that still holds a credential.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis profile remove old-work`
+- `npx --package @notis_ai/cli@latest -- notis profile remove old-work --force`
+
+
 ## Meta Commands
 
 ### `npx --package @notis_ai/cli@latest -- notis doctor`

package/dist/scaffolds.json

@@ -1,5 +1,5 @@
 {
-  "source": "apps/*/notis.config.ts",
+  "source": "scaffolds/*/notis.config.ts",
   "scaffolds": [
     {
       "slug": "notis-database",

package/package.json

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

package/skills/notis-apps/SKILL.md

@@ -7,7 +7,7 @@ description: Design and package Notis apps. Use when users want an app that grou
 
 Use this skill when the user wants a packaged Notis app -- task manager, CRM, dashboard, internal tool, etc. Notis apps are **Vite + React projects** that deploy into the Notis portal as installed apps for the current user or team.
 
-Run the Notis CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`. Notis Desktop keeps the CLI auth profile current. This `notis-apps` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
+Run the Notis CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`. Sign the CLI in once with `notis login`; each account you authorize is a profile you can switch between with `notis profile use`. This `notis-apps` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
 
 ## How Apps Are Built
 
@@ -470,13 +470,13 @@ Runs the real desktop-local development workflow. The CLI should discover all ap
 
 ## Deploy Without Backend Server
 
-If the backend server at `localhost:3001` is not running, use `--direct`:
+If the live API is unreachable, use `--direct`:
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis apps deploy --direct
 ```
 
-This uploads the bundle and editable source snapshot directly to Supabase storage and updates the app manifest in the database, bypassing the backend server entirely. The CLI auto-falls back to direct mode on network errors.
+This uploads the bundle and editable source snapshot directly to Supabase storage and updates the app manifest in the database, bypassing the API server. The CLI auto-falls back to direct mode on network errors. Localhost backends are reserved for `/notis-tests` via `./dev.sh`; do not retarget the personal CLI lane at loopback from this skill.
 
 ## Testing
 

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
 
-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`.
+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

@@ -29,9 +29,30 @@ Use the registry-resolved published npm package everywhere:
 
 - `npx --package @notis_ai/cli@latest -- notis ...`
 
-Always use this NPX command form so the agent runs the current published CLI. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`; locally, Notis Desktop keeps the CLI auth profile current for NPX invocations.
+Always use this NPX command form so the agent runs the current published CLI. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`. On a local machine the CLI authorizes itself in the browser with `notis login` — nothing else signs it in, and the Notis desktop app is not involved.
 
-Notis Desktop keeps the CLI auth profile current for NPX runs. This `notis-cli` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
+This `notis-cli` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
+
+## Profiles: accounts and endpoints
+
+A profile is one account paired with one API endpoint. Profiles live side by side; switching between them never signs any of them out.
+
+- `npx --package @notis_ai/cli@latest -- notis profile list` — every profile on this machine, with its endpoint, user, and whether it is signed in. The active one is marked.
+- `npx --package @notis_ai/cli@latest -- notis profile use <name>` — change which account subsequent commands run as.
+- `npx --package @notis_ai/cli@latest -- notis --profile <name> <command>` — run a single command as another account without changing the active one.
+- `npx --package @notis_ai/cli@latest -- notis login --profile <name>` — add an account. The existing profiles keep their credentials.
+- `npx --package @notis_ai/cli@latest -- notis logout` — sign out of the active profile only; pass `--all-profiles` to clear every one.
+
+Read the profile before acting on the user's data. `notis whoami` reports the account and endpoint a command will hit; if that is not the account the user meant, switch profiles rather than proceeding.
+
+### Working against a local `./dev.sh` backend
+
+`./dev.sh` exposes its test account as a lease-backed profile (`dev-<workspace>-<hash>`) pointing at the local backend, and prints the name on startup. Its credential stays in that worktree and it is the automatic default there, so `notis ...` targets the local API and test user with no extra flags. It is not a stored account profile and cannot be selected outside the worktree.
+
+Two rules follow from the dev credential being scoped to that local backend:
+
+- A `dev-*` profile only exists while its `./dev.sh` lease is running. If it is stopped, the CLI fails with `dev_runtime_unavailable` instead of sending the test user's token to the live API.
+- To reach a real account from inside a worktree — including when the local backend is wedged — name a real profile explicitly: `notis --profile <name> ...`. That is the supported escape hatch.
 
 ## Critical rule for missing tools
 
@@ -134,13 +155,13 @@ This is the main escape hatch for:
 ### Tool access workflow
 
 1. List available toolkit namespaces:
-   - `npx --package @notis_ai/cli@latest -- notis tools toolkits`
+   - `npx --package @notis_ai/cli@latest -- notis tools toolkits --timeout-ms 90000`
 2. Search for the capability you need using natural language:
-   - `npx --package @notis_ai/cli@latest -- notis tools search "<query>"`
+   - `npx --package @notis_ai/cli@latest -- notis tools search "<query>" --timeout-ms 90000`
    - optionally add known field hints with `--known-fields "<key:value>"`
 3. If needed, inspect the exact tool and parameter schema:
-   - `npx --package @notis_ai/cli@latest -- notis tools describe <tool-name>`
-   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --get-schema`
+   - `npx --package @notis_ai/cli@latest -- notis tools describe <tool-name> --timeout-ms 90000`
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --get-schema --timeout-ms 90000`
 4. Validate arguments before execution when the tool is mutating or the schema is non-trivial:
    - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --dry-run --arguments '<json>'`
 5. Execute the tool:
@@ -151,6 +172,22 @@ This is the main escape hatch for:
    - `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>`
    - For a revoked or invalid credential-based connection, reconnect with credential JSON on stdin: `npx --package @notis_ai/cli@latest -- notis tools link <toolkit> --reconnect --credentials -`
 
+### Discovery latency and caching
+
+The discovery bridge may query several connected MCP servers on a cold run and
+can legitimately take longer than the CLI's general 30-second timeout. Always
+use `--timeout-ms 90000` for `tools toolkits`, `tools search`, `tools describe`,
+and schema-only discovery calls. If a discovery call returns `network_timeout`,
+retry that same command once with `--timeout-ms 90000`; do not start a new
+query, invent a tool name, or loop on the default 30-second command.
+
+Discovery is idempotent but should be bounded: run the toolkit listing once per
+task, run one natural-language search per distinct capability, and cache the
+returned canonical tool names and schemas for the rest of the current turn.
+After a successful search/schema response, call the returned canonical tool
+directly (with a dry-run before mutations) instead of repeating the same
+discovery request before every connected-service action.
+
 ### Tool access rules
 
 - Never guess tool names. Discover them with `npx --package @notis_ai/cli@latest -- notis tools search` first.
@@ -241,7 +278,8 @@ When `LOCAL_NOTIS_DATABASE_LIST_DATABASES` or `LOCAL_NOTIS_DATABASE_GET_DATABASE
 
 ## Supporting commands
 
-- `npx --package @notis_ai/cli@latest -- notis doctor` — verify CLI config, auth, and API reachability before relying on the CLI
+- `npx --package @notis_ai/cli@latest -- notis whoami` — confirm which account and endpoint a command will target
+- `npx --package @notis_ai/cli@latest -- notis doctor` — verify CLI config, auth, routing, and API reachability before relying on the CLI
 - `npx --package @notis_ai/cli@latest -- notis describe <command...>` — get the exact command contract for first-class CLI commands
 
 ## Summary
@@ -255,26 +293,31 @@ Most importantly: if you do not currently have the tool you need, especially for
 
 ## Troubleshooting
 
-### CLI returns `auth_expired`
+### CLI returns `auth_expired` or `auth_missing`
+
+The profile's browser authorization has lapsed or was never granted. Run
+`notis login` (add `--profile <name>` when the failing profile is not the
+active one) and have the user approve the browser prompt. In JSON/agent mode
+the first hint is the exact command to run. Do not copy refresh tokens into
+commands or try to mint a credential yourself.
 
-Local CLI auth is renewed by Notis Desktop. In JSON/agent mode, follow the
-first hint exactly: on macOS it is an executable `open -a 'Notis'` (or
-`open -a 'Notis Beta'`) command when the owning desktop app is not running.
-Wait for the app to restore the signed-in session, then rerun the original
-command. Do not copy refresh tokens into commands or try to refresh the shared
-desktop session yourself.
+If the profile is a `dev-*` one, the fix is to restart `./dev.sh` in the
+workspace it belongs to, or to switch to a real account profile.
 
 ### Deploy fails with "network_error" or "fetch failed"
 
-The backend server at `http://localhost:3001` is not running. Solutions:
+The CLI defaults to the live Notis API (`https://api.notis.ai`, or
+`https://api-beta.notis.ai` when the signed-in user is on beta). Solutions:
+
+1. Run `npx --package @notis_ai/cli@latest -- notis doctor` and confirm `api_base` is a live Notis host
+2. Use `--direct` for app deploys when you only need Supabase storage upload: `npx --package @notis_ai/cli@latest -- notis apps deploy --direct`
+3. If auth looks stale, run `npx --package @notis_ai/cli@latest -- notis login` and retry
 
-1. Use `--direct` flag: `npx --package @notis_ai/cli@latest -- notis apps deploy --direct` uploads to Supabase storage directly
-2. Start the backend server: `cd server && python3 main.py`
-3. Check the API base: `npx --package @notis_ai/cli@latest -- notis doctor` shows the configured `api_base`
+Localhost backends are a Notis-developer test lane only. Do not retarget the CLI at loopback from this skill — that path is owned by `./dev.sh`, which exposes its own lease-backed `dev-*` profile.
 
 ### `npx --package @notis_ai/cli@latest -- notis doctor` shows health/tool_roundtrip errors
 
-The CLI health check pings the backend server. If it's not running, these checks fail. App development commands that are `backend_call: local` (`init`, `build`, `verify`, `link`, `doctor`) work without the server. `dev`, `pull`, `create`, `list`, and normal `deploy` need the backend; `deploy --direct` can bypass it when Supabase credentials are available.
+The CLI health check pings the configured live API. App development commands that are `backend_call: local` (`init`, `build`, `verify`, `link`, `doctor`) work offline. `dev`, `pull`, `create`, `list`, and normal `deploy` need the live API; `deploy --direct` can bypass it when Supabase credentials are available.
 
 ### Stale bundle in the portal after deploy
 

package/skills/notis-onboarding/BRIEF.md

@@ -10,6 +10,22 @@ npx --package @notis_ai/cli@latest -- notis tools exec <TOOL> --arguments '<json
 
 Never invent tool names. `notis tools search "<what you need>"` finds them.
 
+## 0. Read before you ask
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_GET_USER_SETTINGS --arguments '{}'
+```
+
+This returns `onboarding_complete`, the settings already on file, and
+`missing_settings` — the only fields you still have a reason to ask about.
+
+**If `onboarding_complete` is true, stop. Do not run this plan.** The account is
+already set up; say so and get on with whatever the user actually asked for.
+Running onboarding again re-asks a returning user their own name and tells them
+you connected things that were connected long before you arrived.
+
+Otherwise ask only for what is in `missing_settings`.
+
 ## 1. Collect the basics
 
 The fields onboarding collects, wherever it runs. Both the conversational
@@ -36,7 +52,6 @@ Rules that hold on every surface:
 * Save as soon as you have the basics rather than batching to the end — a user who
   drops out halfway should not lose what they already told you.
 
-
 You are in a terminal, so there is no phone number to infer a country from. Take
 the language and time zone from the shell environment if you can read them, state
 what you inferred, and let the user correct you. Then save:
@@ -74,6 +89,9 @@ If they connect nothing, fall back to installing a public app:
 npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_COMPLETE_TUTORIAL --arguments '{}'
 ```
 
+Only if you actually ran this plan. If step 0 told you onboarding was already
+complete, you skipped the plan and there is nothing to finish.
+
 Until this runs, every message the user sends on every channel is routed to the
 onboarding assistant — so an agent that collects everything and skips this leaves
 them permanently stuck talking to an onboarding bot.
@@ -83,10 +101,11 @@ Verify with `LOCAL_NOTIS_GET_INTEGRATIONS_STATUS` and tell them what is connecte
 ## What this plan does not include
 
 Do **not** call `LOCAL_NOTIS_INSERT_REMINDER` or any automation tool during
-onboarding. Reminders, automations, voice, and the messaging channels are paid
-features; calling them here fails at the worst possible moment. If the user asks
-for a reminder or a recurring task, say plainly that it needs an upgrade and offer
-`LOCAL_NOTIS_GET_SUBSCRIPTION_STATUS` so they can see their plan.
+onboarding: on most plans they fail at the worst possible moment. If the user
+asks for a reminder or a recurring task, check what they actually have with
+`LOCAL_NOTIS_GET_SUBSCRIPTION_STATUS` and answer from that rather than from a
+guess about which tier includes what — the entitlement lives in the product, not
+in this document.
 
 What they *do* have: 1,000+ integrations through this CLI, skills that sync to
 their coding agents, long-term memory, notes and databases, and the ability to

package/skills/notis-query/cli.md

@@ -4,7 +4,7 @@ Use the generic `notis tools` workflow through NPX for native Notis Database ope
 
 ## Setup
 
-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"`.
+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/cli.js

@@ -69,7 +69,28 @@ function ensureParentCommand(program, parentMap, parentPath) {
 }
 
 function buildRuntime(globalOptions, spec) {
-  const runtime = resolveRuntimeProfile(globalOptions, { requireAuth: spec.require_auth !== false });
+  const localBackendTypes = new Set(['local', 'local_config', 'local_registry']);
+  const commandName = spec.command_path.join(' ');
+  const liveAppHarness = (
+    commandName === 'apps verify' || commandName === 'apps screenshot'
+  ) && globalOptions.mode === 'live';
+  const runtime = resolveRuntimeProfile(globalOptions, {
+    requireAuth: spec.require_auth !== false,
+    allowUnknownProfile: spec.allow_unknown_profile === true,
+    allowUnavailableWorktree:
+      localBackendTypes.has(spec.backend_call?.type) && !liveAppHarness,
+  });
+  // A stopped local-only worktree may keep executing commands whose backend is
+  // entirely local, but it must not carry a shared live credential into those
+  // handlers or their post-command telemetry. Naming --profile explicitly is
+  // the deliberate escape hatch from the worktree boundary.
+  if (runtime.worktreeRuntimeUnavailable && runtime.profileSource !== 'explicit') {
+    runtime.jwt = undefined;
+    runtime.credentialKind = undefined;
+    runtime.credentialSource = undefined;
+    runtime.oauthAccessToken = undefined;
+    runtime.oauthRefreshToken = undefined;
+  }
   return {
     ...runtime,
     cliVersion: CLI_VERSION,
@@ -86,6 +107,7 @@ function buildErrorRuntime(globalOptions) {
       ...resolveRuntimeProfile(globalOptions, {
         requireAuth: false,
         includeDebugEntitlementOverride: false,
+        allowUnknownProfile: true,
       }),
       cliVersion: CLI_VERSION,
       color: globalOptions.color !== false,
@@ -194,7 +216,10 @@ export function createProgram() {
     .option('--quiet', 'Suppress non-essential human output')
     .option('--verbose', 'Show extra human-readable diagnostics')
     .option('--no-color', 'Disable ANSI color output')
-    .option('--profile <name>', 'CLI profile name', 'default')
+    // No default value: commander cannot tell a default apart from an explicit
+    // flag, and a defaulted "default" here silently overrode every
+    // `notis profile use`, pinning all commands to the default profile.
+    .option('--profile <name>', 'CLI profile to run as (defaults to the active profile)')
     .option('--api-base <url>', 'Override the API base URL for this invocation')
     .option('--timeout-ms <n>', 'HTTP timeout in milliseconds')
     .option('--idempotency-key <key>', 'Override the generated idempotency key for mutating commands');

package/src/command-specs/apps.js

@@ -239,11 +239,7 @@ export function resolveDevelopmentDesktopScheme(env = process.env, worktreeRunti
 }
 
 export function resolveDevelopmentDesktopAppName(runtime = {}) {
-  const explicit = String(
-    runtime.desktopAppName
-    || runtime.worktreeRuntime?.desktop_app_name
-    || '',
-  ).trim();
+  const explicit = String(runtime.worktreeRuntime?.desktop_app_name || '').trim();
   if (explicit) {
     return explicit;
   }
@@ -561,6 +557,14 @@ export async function ensureDevInstall({
   const skills = resolveConfiguredAppSkills(appConfig, projectDir);
   let linkedState = readLinkedState(projectDir);
   let linkedApp = null;
+  if (linkedState?.dev_app_id) {
+    const devApp = await getAccessibleApp(ctx.runtime, linkedState.dev_app_id, runTool);
+    if (!devApp || devApp.manifest?.is_dev !== true) {
+      const { dev_app_id: _devAppId, dev_linked_at: _devLinkedAt, ...rest } = linkedState;
+      linkedState = rest;
+      writeLinkedState(projectDir, linkedState);
+    }
+  }
   if (linkedState?.app_id) {
     linkedApp = await getAccessibleApp(ctx.runtime, linkedState.app_id, runTool);
     if (linkedApp?.manifest?.is_dev === true) {
@@ -631,7 +635,7 @@ async function getAccessibleApp(runtime, appId, runTool = runToolCommand) {
   const result = await runTool({
     runtime,
     toolName: GET_APP_TOOL,
-    arguments_: { app_id: appId },
+    arguments_: { app_id: appId, include_documents: false },
   });
   if (result.payload?.app) {
     return {
@@ -640,7 +644,11 @@ async function getAccessibleApp(runtime, appId, runTool = runToolCommand) {
     };
   }
   const message = typeof result.payload?.message === 'string' ? result.payload.message : '';
-  if (result.payload?.status === 'error' && /PGRST116|0 rows|no rows|not found/i.test(message)) {
+  const errorCode = result.payload?.code || result.payload?.error?.code;
+  if (
+    result.payload?.status === 'error'
+    && (errorCode === 'app_not_found' || /^App not found\.?$/i.test(message.trim()))
+  ) {
     return null;
   }
   throw usageError(`Could not verify access to app ${appId}${message ? `: ${message}` : '.'}`);
@@ -786,7 +794,7 @@ async function appsDevHandler(ctx) {
   const mode = getCliMode();
   const identity = decodeJwtSub(ctx.runtime.jwt);
   if (!identity) {
-    throw usageError('Could not determine the current user from the CLI auth token. Open the Notis desktop app, sign in, and retry.');
+    throw usageError('Could not determine the current user from the CLI credential. Run notis login and retry.');
   }
   const apiBase = String(ctx.runtime.apiBase || '').replace(/\/$/, '');
   const sessionsFilePath = getAppDevSessionsFile(
@@ -1095,7 +1103,7 @@ async function appsVerifyHandler(ctx) {
       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.');
+      throw usageError('Live verify mode requires CLI auth. Run notis login and retry.');
     }
     linkedState = readLinkedState(projectDir);
     if (!linkedState?.app_id) {
@@ -1315,7 +1323,7 @@ async function appsScreenshotHandler(ctx) {
       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.');
+      throw usageError('Live mode requires CLI auth. Run notis login and retry.');
     }
     linkedState = readLinkedState(projectDir);
     if (!linkedState?.app_id) {

package/src/command-specs/auth.js

@@ -2,16 +2,6 @@ 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',
@@ -25,12 +15,16 @@ async function loginHandler(ctx) {
       authenticated: true,
       credential_source: 'oauth',
       profile: ctx.runtime.profileName,
+      api_base: result.profile.api_base || ctx.runtime.apiBase,
       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}".`,
+    hints: [
+      { command: 'notis profile list', reason: 'See every account this machine can switch between' },
+    ],
   });
 }
 
@@ -53,16 +47,15 @@ async function logoutHandler(ctx) {
 export const authCommandSpecs = [
   {
     command_path: ['login'],
-    summary: 'Authorize the Notis CLI in a browser with scoped OAuth access.',
+    summary: 'Authorize a CLI profile 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.',
+      'Run this once per account you want the CLI to reach. Pass --profile to add a second account without signing the first one out.',
     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.' },
@@ -70,37 +63,39 @@ export const authCommandSpecs = [
     },
     examples: [
       'notis login',
+      'notis login --profile work',
+      'notis login --profile beta --api-base https://api-beta.notis.ai',
       '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.',
+      'Returns credential_source, profile, api_base, 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'],
+    allow_unknown_profile: true,
+    related_commands: ['notis profile list', 'notis profile use', 'notis logout', 'notis doctor'],
     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.',
+    summary: 'Revoke and remove the OAuth credential for one CLI profile.',
     when_to_use:
-      'Use this to disconnect the command line without signing Notis Desktop out.',
+      'Use this to disconnect a single account. Other profiles keep their credentials unless you pass --all-profiles.',
     args_schema: {
       arguments: [],
       options: [
         { flags: '--all-profiles', description: 'Remove OAuth credentials from every CLI profile.' },
       ],
     },
-    examples: ['notis logout', 'notis logout --all-profiles'],
+    examples: ['notis logout', 'notis logout --profile work', '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'],
+    related_commands: ['notis login', 'notis profile list'],
     backend_call: { type: 'oauth', name: 'revocation' },
     handler: logoutHandler,
   },

package/src/command-specs/diagnostics.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { usageError } from '../runtime/errors.js';
 import {
@@ -178,6 +178,11 @@ async function executeReadOnlySql(ctx, query, phase) {
       tools: [{ tool_slug: toolName, arguments: { query } }],
     },
     mutating: false,
+    // Always a fresh key, never the operator's --idempotency-key: a diagnostic
+    // must observe current state rather than replay a cached response, and two
+    // different queries under one reused key would collide on the request hash.
+    idempotencyKey: randomUUID(),
+    sendIdempotencyKeyWhenReading: true,
   });
   if (result.payload?.successful === false || result.payload?.error) {
     throw usageError(