@notis_ai/cli 0.2.14 → 0.2.16

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,21 +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. A linked app substitutes its online bundle only when local notisAppVersion is strictly greater than the installed release.
 
 Options:
 - `--port <number>` — Local bundle server port (default: 5173).
-- `--no-open` — Do not auto-open the desktop Portal local development app.
-- `--live-data` — Read and write the installed app's real databases instead of empty dev copies. Applies to this session only; warns and falls back when the app is not installed yet.
+- `--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 --live-data  # iterate on a view over the installed app's real rows`
+- `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]`
 
@@ -232,26 +294,26 @@ Examples:
 
 Download a Notis app source snapshot into a local project folder.
 
-When to use: Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.
+When to use: Edit an installed app locally. Preserve any local edits, pull and link the latest persisted source, then increment package.json notisAppVersion above that release before notis apps dev; continue with build and deploy.
 
 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`