@notis_ai/cli 0.2.0 → 0.2.2

package/README.md

@@ -1,21 +1,23 @@
 # @notis_ai/cli
 
-Agent-first Notis CLI for apps, databases, and generic tool execution.
+Agent-first Notis CLI for apps and generic tool execution.
 
 ## Install
 
-The Notis CLI is bundled automatically with the Notis desktop app.
+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.
+
+For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>`.
 
 ## Quick Start
 
 ```bash
-notis --help
-notis auth status
-notis apps list
-notis db list
+npx --package @notis_ai/cli@latest -- notis --help
+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"
 ```
 
-If you're using the desktop app, login and logout keep the CLI profile in sync automatically.
+The desktop app owns sign-in and keeps the CLI profile in sync automatically.
 
 The CLI defaults to `json` output in agent or non-TTY contexts and `table` output in interactive terminals.
 
@@ -29,211 +31,163 @@ 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
 
-## Auth
-
-### `notis auth login`
-
-Store credentials for a named CLI profile.
-
-When to use: Use this before authenticated commands, especially in fresh environments or CI profiles.
-
-Options:
-- `--jwt <token>` — JWT token to store for the profile.
-
-Examples:
-- `notis auth login --jwt <token>`
-- `notis auth login --profile staging --api-base http://localhost:3001`
-
-### `notis auth logout`
-
-Remove the stored JWT for the active profile.
-
-When to use: Use this to clear local credentials without touching other profiles.
-
-Examples:
-- `notis auth logout`
-- `notis auth logout --profile staging`
-
-### `notis auth status`
-
-Inspect local auth configuration and optionally verify it against the API.
-
-When to use: Use this before automating commands to confirm the active profile and token health.
-
-Options:
-- `--verify` — Perform a live authenticated roundtrip to the API.
-
-Examples:
-- `notis auth status`
-- `notis auth status --verify --json`
-
-
 ## Apps
 
-### `notis apps list`
+### `npx --package @notis_ai/cli@latest -- notis apps list`
 
 List apps the current profile can access.
 
 When to use: Discover existing apps before linking or deploying.
 
 Examples:
-- `notis apps list`
-- `notis apps list --json`
+- `npx --package @notis_ai/cli@latest -- notis apps list`
+- `npx --package @notis_ai/cli@latest -- notis apps list --json`
 
-### `notis apps init <name> [dir]`
+### `npx --package @notis_ai/cli@latest -- notis apps init <name> [dir]`
 
 Scaffold a new Notis app project.
 
-When to use: Start a new Notis app. Creates a Next.js project with @notis/sdk pre-configured.
-
-Examples:
-- `notis apps init "Mind the Flo"`
-- `notis apps init "My App" ./my-app`
-
-### `notis apps create <name> [dir]`
-
-Create a new remote Notis app and optionally link a local project to it.
-
-When to use: Provision a fresh remote app before the first deploy. Pass a project directory to link it immediately.
+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.
 
 Options:
-- `--description <text>` — Optional app description.
-- `--icon <lucide:icon>` — Optional Lucide icon, for example lucide:dices.
+- `--from <slug>` — Start from a bundled scaffold listed by `notis apps scaffolds list`.
 
 Examples:
-- `notis apps create "My App"`
-- `notis apps create "My App" . --description "Internal tool" --icon lucide:layout-dashboard`
+- `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`
 
-### `notis apps dev [dir]`
+### `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
 
-Run the Next.js dev server for local development.
+List bundled Notis app scaffolds.
 
-When to use: Iterate on app UI with hot reload. SDK hooks return mock data.
+When to use: Discover the fixed scaffold catalog shipped with the CLI before starting a new app.
 
 Examples:
-- `notis apps dev`
-- `notis apps dev ./my-app`
+- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
+- `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from notis-database`
 
-### `notis apps build [dir]`
+### `npx --package @notis_ai/cli@latest -- notis apps create <name> [dir]`
 
-Build and package the app into .notis/output/.
+Create a new remote Notis app and optionally link a local project to it.
 
-When to use: Prepare the app for preview or deployment.
+When to use: Provision a fresh remote app before the first deploy. Pass a project directory to link it immediately.
 
 Examples:
-- `notis apps build`
-- `notis apps build ./my-app`
+- `npx --package @notis_ai/cli@latest -- notis apps create "My App"`
+- `npx --package @notis_ai/cli@latest -- notis apps create "My App" .`
 
-### `notis apps preview [dir]`
+### `npx --package @notis_ai/cli@latest -- notis apps dev [dir]`
 
-Serve the built artifact locally for testing.
+Develop Notis apps inside the Electron desktop Portal with automatic local bundle reloads.
 
-When to use: Smoke-test the exact artifact that will be deployed. Databases use seed data.
+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.
 
 Options:
-- `--port <number>` — Server port (default: 8787).
+- `--port <number>` — Local bundle server port (default: 5173).
+- `--no-open` — Do not auto-open the desktop Portal local development app.
 
 Examples:
-- `notis apps preview`
-- `notis apps preview --port 3000`
+- `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`
 
-### `notis apps link <app-id> [dir]`
+### `npx --package @notis_ai/cli@latest -- notis apps build [dir]`
 
-Link a local project to a remote Notis app.
+Build and package the app into .notis/output/.
 
-When to use: Connect a local project to an existing app for deployment.
+When to use: Prepare the app for verification or deployment.
 
 Examples:
-- `notis apps link abc123`
-- `notis apps link abc123 ./my-app`
+- `npx --package @notis_ai/cli@latest -- notis apps build`
+- `npx --package @notis_ai/cli@latest -- notis apps build ./my-app`
 
-### `notis apps deploy [dir]`
+### `npx --package @notis_ai/cli@latest -- notis apps verify [dir]`
 
-Build and upload the app to the linked Notis app.
+Headless render smoke each route in a stub-runtime harness.
 
-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: After notis apps build, before deploy. Catches render-time crashes and missing runtime calls that the build step cannot detect.
 
 Options:
-- `--app-id <id>` — Override linked app ID.
-- `--skip-build` — Skip the build step (use existing .notis/output/).
+- `--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.
+- `--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).
 
 Examples:
-- `notis apps deploy`
-- `notis apps deploy --skip-build`
-- `notis apps deploy --app-id abc123`
+- `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 --no-browser  # start the harness, drive agent-browser yourself`
 
-### `notis apps doctor [dir]`
+### `npx --package @notis_ai/cli@latest -- notis apps link <app-id> [dir]`
 
-Check project health and readiness.
+Link a local project to a remote Notis app.
 
-When to use: Diagnose issues with a Notis app project.
+When to use: Connect a local project to an existing app for deployment.
 
 Examples:
-- `notis apps doctor`
-- `notis apps doctor ./my-app`
-
+- `npx --package @notis_ai/cli@latest -- notis apps link abc123`
+- `npx --package @notis_ai/cli@latest -- notis apps link abc123 ./my-app`
 
-## Databases
+### `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir]`
 
-### `notis db list`
+Download a Notis app source snapshot into a local project folder.
 
-List native Notis databases.
+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: Use this to find database ids and slugs before querying or updating schemas.
+Options:
+- `--force` — Overwrite a non-empty target directory.
+- `--version <n>` — Pull a specific app source version (default: latest).
 
 Examples:
-- `notis db list`
-- `notis db list --json`
+- `npx --package @notis_ai/cli@latest -- notis apps pull abc123`
+- `npx --package @notis_ai/cli@latest -- notis apps pull abc123 ./my-app --force`
 
-### `notis db upsert`
+### `npx --package @notis_ai/cli@latest -- notis apps deploy [dir]`
 
-Create or update a native database schema.
+Build and upload the app to the linked Notis app.
 
-When to use: Use this when you need to provision a new database or adjust an existing schema.
+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.
 
 Options:
-- `--operation <create|update>` — Create a new database or update an existing one.
-- `--database-id <id>` — Database id for update operations.
-- `--title <text>` — Database title.
-- `--description <text>` — Database description.
-- `--icon <lucide-icon-name>` — Database icon (Lucide icon name, e.g. database).
-- `--properties <json>` — JSON array of property definitions.
+- `--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.
 
 Examples:
-- `notis db upsert --operation create --title "Tasks"`
-- `notis db upsert --operation update --database-id db_123 --title "Tasks V2"`
-
-### `notis db query <database-slug>`
+- `npx --package @notis_ai/cli@latest -- notis apps deploy`
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --skip-build`
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --app-id abc123`
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --direct`
 
-Run a structured query against a native Notis database.
+### `npx --package @notis_ai/cli@latest -- notis apps doctor [dir]`
 
-When to use: Use this when the database slug is known and you need direct filters, sorts, or pagination.
+Check project health and readiness.
 
-Options:
-- `--filter <json>` — Structured query filter JSON.
-- `--sort <json>` — Sort JSON object or array.
-- `--page-size <n>` — Page size between 1 and 100.
-- `--offset <n>` — Zero-based offset.
-- `--cursor <value>` — Pagination cursor alias for next_offset.
+When to use: Diagnose issues with a Notis app project.
 
 Examples:
-- `notis db query tasks --page-size 50`
-- `notis db query tasks --filter '{"property":"Status"}'`
+- `npx --package @notis_ai/cli@latest -- notis apps doctor`
+- `npx --package @notis_ai/cli@latest -- notis apps doctor ./my-app`
 
 
 ## Generic Tools
 
-### `notis tools toolkits`
+### `npx --package @notis_ai/cli@latest -- notis tools toolkits`
 
 List toolkit namespaces available to the active user.
 
 When to use: Use this before searching or executing generic tools.
 
 Examples:
-- `notis tools toolkits`
-- `notis tools toolkits --json`
+- `npx --package @notis_ai/cli@latest -- notis tools toolkits`
+- `npx --package @notis_ai/cli@latest -- notis tools toolkits --json`
 
-### `notis tools search <query>`
+### `npx --package @notis_ai/cli@latest -- notis tools search <query>`
 
 Search across toolkit namespaces using natural language.
 
@@ -243,10 +197,10 @@ Options:
 - `--toolkits <csv-or-json>` — Optional subset of toolkit ids to search.
 
 Examples:
-- `notis tools search "send an email"`
-- `notis tools search "update framer page" --toolkits mcp-framer`
+- `npx --package @notis_ai/cli@latest -- notis tools search "send an email"`
+- `npx --package @notis_ai/cli@latest -- notis tools search "update framer page" --toolkits mcp-framer`
 
-### `notis tools describe <tool-name>`
+### `npx --package @notis_ai/cli@latest -- notis tools describe <tool-name>`
 
 Describe a generic tool by name.
 
@@ -256,10 +210,10 @@ Options:
 - `--toolkits <csv-or-json>` — Optional subset of toolkit ids to search.
 
 Examples:
-- `notis tools describe composio-gmail-default-send_email`
-- `notis tools describe notis-default-query --toolkits notis-default`
+- `npx --package @notis_ai/cli@latest -- notis tools describe composio-gmail-default-send_email`
+- `npx --package @notis_ai/cli@latest -- notis tools describe notis-default-query --toolkits notis-default`
 
-### `notis tools exec <tool-name>`
+### `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name>`
 
 Execute a generic tool by canonical tool name.
 
@@ -269,63 +223,73 @@ Options:
 - `--arguments <json>` — JSON object, @file path, or - for stdin.
 - `--get-schema` — Display the tool parameter schema without executing.
 - `--dry-run` — Validate arguments against the tool schema without executing.
-- `--watch <seconds>` — Re-execute on an interval and stream results.
+- `--toolkits <csv-or-json>` — Optional toolkit namespace(s) to use when resolving the tool.
 
 Examples:
-- `notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{}}'`
-- `notis tools exec notis-default-query --get-schema`
-- `notis tools exec notis-default-query --dry-run --arguments '{"database_slug":"tasks","query":{}}'`
-- `notis tools exec notis-default-query --arguments @query.json`
-- `notis tools exec notis-default-query --arguments - < query.json`
-- `notis tools exec notis-default-query --watch 10 --arguments '{"database_slug":"tasks","query":{}}'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{}}'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --arguments '{"database_slug":"tasks"}'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --get-schema`
+- `npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --dry-run --arguments '{"database_slug":"tasks","query":{}}'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments @query.json`
+- `npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments - < query.json`
 
-### `notis tools exec-parallel <calls>`
+### `npx --package @notis_ai/cli@latest -- notis tools exec-parallel <calls>`
 
 Execute multiple tools concurrently.
 
 When to use: Use this when you need to run independent tool calls simultaneously for speed.
 
 Examples:
-- `notis tools exec-parallel '[{"tool_name":"notis-default-query","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"notis-default-list_databases","arguments":{}}]'`
+- `npx --package @notis_ai/cli@latest -- notis tools exec-parallel '[{"tool_name":"notis-default-query","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"notis-default-list_databases","arguments":{}}]'`
 
-### `notis tools link <toolkit>`
+### `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>`
 
 Get the URL to connect an integration toolkit.
 
 When to use: Use this when a tool requires authentication with an external service.
 
 Examples:
-- `notis tools link github`
-- `notis tools link gmail --json`
+- `npx --package @notis_ai/cli@latest -- notis tools link github`
+- `npx --package @notis_ai/cli@latest -- notis tools link gmail --json`
 
 
 ## Meta Commands
 
-### `notis doctor`
+### `npx --package @notis_ai/cli@latest -- notis doctor`
 
 Run a quick CLI health check for config, auth, and API reachability.
 
 When to use: Use this before relying on the CLI in automation or after changing environments.
 
 Examples:
-- `notis doctor`
-- `notis doctor --json`
+- `npx --package @notis_ai/cli@latest -- notis doctor`
+- `npx --package @notis_ai/cli@latest -- notis doctor --json`
+
+### `npx --package @notis_ai/cli@latest -- notis whoami`
+
+Display the active profile, user, and available toolkits.
+
+When to use: Use this to quickly confirm which account and environment a command will target.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis whoami`
+- `npx --package @notis_ai/cli@latest -- notis whoami --json`
 
-### `notis describe <command...>`
+### `npx --package @notis_ai/cli@latest -- notis describe <command...>`
 
 Describe a first-class CLI command in detail.
 
 When to use: Use this when an agent or human needs the exact shape, examples, and semantics of a command.
 
 Examples:
-- `notis describe apps push`
-- `notis describe db query`
+- `npx --package @notis_ai/cli@latest -- notis describe apps deploy`
+- `npx --package @notis_ai/cli@latest -- notis describe tools exec`
 
 
 ## Local Development
 
 ```bash
-cd cli/npm
+cd packages/cli
 npm install
 node ./bin/notis.js --help
 npm run docs:generate

package/dist/scaffolds/notes/app/globals.css

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

package/dist/scaffolds/notes/app/layout.tsx

@@ -0,0 +1,6 @@
+import '@notis/sdk/styles.css';
+import './globals.css';
+
+export default function AppShell({ children }: { children: React.ReactNode }) {
+  return children;
+}