@notis_ai/cli 0.2.13 → 0.2.15

package/README.md

@@ -6,6 +6,8 @@ Agent-first Notis CLI for apps and generic tool execution.
 
 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.
 
+After local login, the CLI idempotently adds static Notis guidance to detected Codex and Claude Code user instruction files without changing their hooks. Run `notis agents install` when you explicitly want memory hooks that load the user's profile at session start, recall only new relevant memories before prompts, and save completed turns as automatic cross-session context. Codex then asks you to review and trust those hooks once in `/hooks`.
+
 For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>`.
 
 ## Quick Start
@@ -71,8 +73,9 @@ When to use: Run this once per account you want the CLI to reach. Pass --profile
 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.
-- `--timeout-seconds <n>` — How long to wait for authorization (default 300).
+- `--mode <mode>` — auto (default) hands the browser callback to a background listener when this command cannot wait; browser waits in-process; code shows a one-time code to copy.
+- `--paste-code` — Alias for --mode code.
+- `--timeout-seconds <n>` — Authorization lifetime in seconds (default 300 while waiting in a terminal; 1800 for detached or code hand-offs).
 - `--scope <scope>` — OAuth permission to request (repeatable).
 - `--code <code>` — Redeem the code shown in the browser after a non-interactive login.
 
@@ -81,7 +84,8 @@ Examples:
 - `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 --mode browser`
+- `npx --package @notis_ai/cli@latest -- notis login --mode code`
 - `npx --package @notis_ai/cli@latest -- notis login --code 4f3c2b1a`
 
 ### `npx --package @notis_ai/cli@latest -- notis logout`
@@ -91,7 +95,7 @@ Revoke and remove the OAuth credential for one CLI profile.
 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.
+- `--all-profiles` — Clear OAuth credentials and pending authorizations from every CLI profile.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis logout`
@@ -99,6 +103,42 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis logout --all-profiles`
 
 
+## Coding-agent context
+
+### `npx --package @notis_ai/cli@latest -- notis agents install`
+
+Install Notis instructions and recall/capture hooks for local Codex and Claude Code.
+
+When to use: Run after login to give local coding agents durable Notis CLI guidance, session-start profile context, deduplicated relevant recall, and automatic completed-turn capture. Hosted Notis sandboxes already receive prompt context and are skipped.
+
+Options:
+- `--codex-only` — Configure only Codex.
+- `--claude-only` — Configure only Claude Code.
+- `--no-memory-hooks` — Install static instructions and remove Notis recall/capture hooks.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis agents install`
+- `npx --package @notis_ai/cli@latest -- notis agents install --codex-only`
+- `npx --package @notis_ai/cli@latest -- notis agents install --claude-only`
+- `npx --package @notis_ai/cli@latest -- notis agents install --no-memory-hooks`
+
+
+## Skills
+
+### `npx --package @notis_ai/cli@latest -- notis skills sync`
+
+Synchronize account skills and keep the three Notis base skills current.
+
+When to use: Run manually whenever local agent skills should be reconciled. Manual runs ignore the Desktop automatic-sync preference.
+
+Options:
+- `--electron-repeat` — Honor the automatic Desktop sync preference (used by Notis Desktop).
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis skills sync`
+- `npx --package @notis_ai/cli@latest -- notis skills sync --json`
+
+
 ## Apps
 
 ### `npx --package @notis_ai/cli@latest -- notis apps list`
@@ -115,26 +155,30 @@ Examples:
 
 Scaffold a new Notis app project.
 
-When to use: Start a new Notis app. Use --from with a bundled scaffold when one is close to the desired app; otherwise creates the bare Vite + React project.
+When to use: Start a new Notis app. Use --from with a published Store app when one is close to the desired app; otherwise creates the bare Vite + React project.
 
 Options:
-- `--from <slug>` — Start from a bundled scaffold listed by `notis apps scaffolds list`.
+- `--from <slug>` — Start from a published Store app listed by `notis apps scaffolds list`. Downloads its source from the public app registry.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
 - `npx --package @notis_ai/cli@latest -- notis apps init "Mind the Flo"`
-- `npx --package @notis_ai/cli@latest -- notis apps init "My CRM" --from notis-database`
-- `npx --package @notis_ai/cli@latest -- notis apps init "My App" ./my-app`
+- `npx --package @notis_ai/cli@latest -- notis apps init "My CRM" --from databases`
+- `npx --package @notis_ai/cli@latest -- notis apps init "My App" ~/code/my-app`
 
 ### `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
 
-List bundled Notis app scaffolds.
+List published Store apps available as scaffolds.
+
+When to use: Discover published Store apps to start from before creating a new app. Every app published to the public Store is automatically a scaffold; use --search to narrow the catalog.
 
-When to use: Discover the fixed scaffold catalog shipped with the CLI before starting a new app.
+Options:
+- `--search <term>` — Filter scaffolds by name, tagline, description, or category.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
-- `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from notis-database`
+- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list --search journal`
+- `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from databases`
 
 ### `npx --package @notis_ai/cli@latest -- notis apps create <name> [dir]`
 
@@ -148,18 +192,39 @@ Examples:
 
 ### `npx --package @notis_ai/cli@latest -- notis apps dev [dir]`
 
-Develop Notis apps inside the Electron desktop Portal with automatic local bundle reloads.
+Register a development root and connect its apps to the shared local development host.
 
-When to use: Run this inside a single app or a monorepo root with apps/<name>/notis.config.ts. It discovers every app, starts the local bundle server, registers desktop-local dev sessions, and opens the Electron Portal to the local development app.
+When to use: Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance.
 
 Options:
 - `--port <number>` — Local bundle server port (default: 5173).
-- `--no-open` — Do not auto-open the desktop Portal local development app.
+- `--scratch` — Use isolated empty databases, bundled skills, and bundled automations for this session instead of the installed app's resources. For fixture work and destructive experiments.
+- `--live-data` — Deprecated: using the installed app's real resources is now the default. Accepted as a no-op; use `--scratch` for the old isolated behavior.
+- `--grant-cloud-shell` — Approve a cloudComputer: 'shell' declaration without the interactive prompt. The grant persists for this dev app; authorship alone never grants it.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps dev`
 - `npx --package @notis_ai/cli@latest -- notis apps dev ./my-app`
 - `npx --package @notis_ai/cli@latest -- notis apps dev ./workspace --port 5200`
+- `npx --package @notis_ai/cli@latest -- notis apps dev --scratch  # isolated resources for fixture or schema experiments`
+
+### `npx --package @notis_ai/cli@latest -- notis apps roots list`
+
+List persistent machine-local Notis app development roots.
+
+When to use: See which folders every local Notis Desktop instance watches for development apps.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps roots list`
+
+### `npx --package @notis_ai/cli@latest -- notis apps roots remove <folder>`
+
+Stop watching a registered Notis app development root.
+
+When to use: Remove a persistent development root. The built-in ~/.notis/apps root cannot be removed.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps roots remove ./old-apps`
 
 ### `npx --package @notis_ai/cli@latest -- notis apps build [dir]`
 
@@ -173,15 +238,16 @@ Examples:
 
 ### `npx --package @notis_ai/cli@latest -- notis apps verify [dir]`
 
-Validate every route and the production Store listing contract.
+Validate that every route renders and reports Store listing readiness.
 
-When to use: After notis apps screenshot, before deploy. Catches render-time crashes, missing runtime calls, and incomplete listing media that the build step cannot detect.
+When to use: Any time after notis apps build, and before deploy. Catches render-time crashes and missing runtime calls. Incomplete listing media is reported as a warning; pass --listing to fail on it instead.
 
 Options:
 - `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
 - `--port <n>` — Loopback port. Default: auto-pick.
 - `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
-- `--mode <mode>` — stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT.
+- `--mode <mode>` — stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT and fails routes whose runtime calls all errored.
+- `--listing` — Fail instead of warn when the Store listing (tagline, categories, screenshots, changelog) is incomplete.
 - `--no-browser` — Start the harness server and print URLs; do not drive agent-browser.
 - `--keep-open` — Leave server + browser session running after report (for manual triage).
 
@@ -189,6 +255,7 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps verify`
 - `npx --package @notis_ai/cli@latest -- notis apps verify --routes notes`
 - `npx --package @notis_ai/cli@latest -- notis apps verify --mode live`
+- `npx --package @notis_ai/cli@latest -- notis apps verify --listing  # gate on Store listing readiness before publish`
 - `npx --package @notis_ai/cli@latest -- notis apps verify --no-browser  # start the harness, drive agent-browser yourself`
 
 ### `npx --package @notis_ai/cli@latest -- notis apps screenshot [dir]`
@@ -231,22 +298,22 @@ When to use: Edit an installed app locally. Pulls the persisted source, links th
 
 Options:
 - `--force` — Overwrite a non-empty target directory.
-- `--version <n>` — Pull a specific app source version (default: latest).
+- `--source-version <n>` — Pull a specific app source version (default: latest).
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps pull abc123`
-- `npx --package @notis_ai/cli@latest -- notis apps pull abc123 ./my-app --force`
+- `npx --package @notis_ai/cli@latest -- notis apps pull abc123 ./my-app --force --source-version 3`
 
 ### `npx --package @notis_ai/cli@latest -- notis apps deploy [dir]`
 
 Build and upload the app to the linked Notis app.
 
-When to use: Ship the installed app to production for the linked user/team app. Requires a linked app (notis apps link). This command does not publish to the app store.
+When to use: Ship the installed app to production for the linked user/team app. A project that has only a development app is promoted in place on first deploy: same app id, same databases, dev markers removed. This command does not publish to the app store.
 
 Options:
 - `--app-id <id>` — Override linked app ID.
 - `--skip-build` — Skip the build step (use existing .notis/output/).
-- `--direct` — Upload directly to Supabase storage, bypassing the backend server. Auto-fallback on network errors.
+- `--direct` — Explicitly upload to Supabase storage, bypassing the backend server.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps deploy`
@@ -294,6 +361,43 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps doctor ./my-app`
 
 
+## Hand-over
+
+Give the branch you are on to a Notis agent, which continues the work in a git worktree on the Notis cloud computer. `--route` picks the agent: the hosted Notis agent, or the user's own Codex/Claude Code in the cloud sandbox or on their Mac. `--branch-mode same` makes the agent commit onto your branch; the default cuts a new branch from it.
+
+### `npx --package @notis_ai/cli@latest -- notis handover start <task>`
+
+Hand the current branch to a Notis agent and keep working.
+
+When to use: Use this when you want Notis to continue work on the branch you are on -- long refactors, test fixing, or anything that should keep running after you close the laptop. Pick the agent with --route.
+
+Options:
+- `--branch-mode <mode>` — same = the agent commits onto your branch. new = the agent cuts a new branch from it (default).
+- `--route <target>` — Which agent runs it: notis (hosted, default), codex_cloud, claude_cloud, codex_local, claude_local, or auto.
+- `--repo <slug>` — Configured repository slug on the cloud computer, when you know it.
+- `--no-wip` — Refuse on a dirty tree instead of committing the changes first.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis handover start "fix the failing auth tests"`
+- `npx --package @notis_ai/cli@latest -- notis handover start "finish the migration" --branch-mode same --route codex_cloud`
+- `npx --package @notis_ai/cli@latest -- notis handover start "add integration tests" --route claude_cloud`
+- `npx --package @notis_ai/cli@latest -- notis handover start "review and clean up this branch" --route claude_local`
+
+### `npx --package @notis_ai/cli@latest -- notis handover status`
+
+Show the coding-agent threads Notis is running for you.
+
+When to use: Use this after a hand-over to see whether the agent is still working.
+
+Options:
+- `--provider <provider>` — Filter to codex or claude_code.
+- `--refresh` — Force a live refresh instead of cached state.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis handover status`
+- `npx --package @notis_ai/cli@latest -- notis handover status --provider codex --refresh`
+
+
 ## Generic Tools
 
 ### `npx --package @notis_ai/cli@latest -- notis tools toolkits`