@notis_ai/cli 0.2.1 → 0.2.2

package/skills/notis-apps/cli.md

@@ -0,0 +1,208 @@
+# Notis CLI — App Development Workflow
+
+When running outside the Notis container, use the `notis` CLI to work with Notis Apps locally.
+
+Notis apps are Vite + React projects using `@notis/sdk`. The workflow is init, dev, build, verify, create/link, pull, deploy, and doctor.
+
+Important: `notis apps deploy` updates the linked installed app. It is not an app-store publishing flow.
+
+## 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.
+
+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.
+
+## Core Workflow
+
+1. Scaffold a new app:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps init
+```
+
+2. Or pull an installed app's saved source snapshot:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps pull <app-id> ./my-app
+cd ./my-app
+npm install
+```
+
+3. Develop locally with live reload:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps dev
+```
+
+4. Build the production artifact:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps build
+```
+
+5. Verify the built artifact headlessly:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps verify
+```
+
+6. Link the project if it was not created or pulled from an app, then deploy:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps link <app-id>
+npx --package @notis_ai/cli@latest -- notis apps deploy
+```
+
+## Commands
+
+### `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:
+- `npx --package @notis_ai/cli@latest -- notis doctor`
+- `npx --package @notis_ai/cli@latest -- notis doctor --json`
+
+### `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:
+- `npx --package @notis_ai/cli@latest -- notis apps list`
+- `npx --package @notis_ai/cli@latest -- notis apps list --json`
+
+### `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. Use --from with a bundled scaffold 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`.
+
+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 scaffolds list`
+
+List bundled Notis app scaffolds.
+
+When to use: Discover the fixed scaffold catalog shipped with the CLI before starting a new app.
+
+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 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.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps create "My App"`
+- `npx --package @notis_ai/cli@latest -- notis apps create "My App" .`
+
+### `npx --package @notis_ai/cli@latest -- notis apps dev [dir]`
+
+Develop Notis apps inside the Electron desktop Portal with automatic local bundle reloads.
+
+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>` — Local bundle server port (default: 5173).
+- `--no-open` — Do not auto-open the desktop Portal local development app.
+
+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 build [dir]`
+
+Build and package the app into .notis/output/.
+
+When to use: Prepare the app for verification or deployment.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps build`
+- `npx --package @notis_ai/cli@latest -- notis apps build ./my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis apps verify [dir]`
+
+Headless render smoke each route in a stub-runtime harness.
+
+When to use: After notis apps build, before deploy. Catches render-time crashes and missing runtime calls that the build step cannot detect.
+
+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.
+- `--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:
+- `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`
+
+### `npx --package @notis_ai/cli@latest -- notis apps link <app-id> [dir]`
+
+Link a local project to a remote Notis app.
+
+When to use: Connect a local project to an existing app for deployment.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps link abc123`
+- `npx --package @notis_ai/cli@latest -- notis apps link abc123 ./my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir]`
+
+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.
+
+Options:
+- `--force` — Overwrite a non-empty target directory.
+- `--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 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.
+
+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.
+
+Examples:
+- `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`
+
+### `npx --package @notis_ai/cli@latest -- notis apps doctor [dir]`
+
+Check project health and readiness.
+
+When to use: Diagnose issues with a Notis app project.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps doctor`
+- `npx --package @notis_ai/cli@latest -- notis apps doctor ./my-app`
+

package/skills/notis-cli/SKILL.md

@@ -0,0 +1,258 @@
+---
+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.
+---
+
+# Notis CLI Skill
+
+Use this skill when the user wants work done through the Notis CLI.
+
+This skill covers two main CLI workflows:
+
+1. Developing Notis apps locally.
+2. Accessing Notis, Composio, and MCP tools through the CLI.
+
+## When to use this skill
+
+Activate this skill when:
+
+- the user wants to init, develop, build, verify, link, pull, or deploy a Notis app through the CLI
+- the current agent does not have the tool it needs in its direct tool list
+- the user wants direct MCP access through Notis
+- the user wants to use an integration-backed capability through Notis rather than a first-class local tool
+- the task mentions the `notis` CLI directly
+
+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.
+
+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.
+
+## Critical rule for missing tools
+
+If the tool you need is not already available in your current tool surface, do not stop and do not assume the task is blocked.
+
+Use the Notis CLI as the fallback access layer.
+
+This is especially important when:
+
+- you need direct MCP tools
+- you need a Composio-backed integration tool
+- you need a Notis tool that is not exposed as a first-class command in your current environment
+- you need to discover the canonical tool name before execution
+
+Treat the Notis CLI the same way you would treat a Composio-style tool router flow: discover what is available first, then execute the right tool through the CLI.
+
+## Section 1: Developing Notis Apps
+
+Use this section when the goal is to create or update a Notis app from a local workspace.
+
+Notis apps are Vite + React projects using `@notis/sdk`. The workflow is init or pull, dev, build, verify, create/link, deploy.
+
+Important: `deploy` means updating the installed app artifact for the current user or team. To list an app in the public Notis App Store, the owner opens the app details page in the Notis Portal, sets visibility to Team or Public, then uses Publish/Update. The CLI does not publish to the store; the backend opens the registry PR using a service token.
+
+### App development workflow
+
+1. Scaffold a new app:
+   - `npx --package @notis_ai/cli@latest -- notis apps init`
+2. Or pull an existing app's source to edit it locally (the project is linked automatically):
+   - `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>`
+   - then run `npm install`, `npx --package @notis_ai/cli@latest -- notis apps dev`, edit, build, and deploy
+3. Develop locally with live reload:
+   - `npx --package @notis_ai/cli@latest -- notis apps dev`
+4. Build the production artifact:
+   - `npx --package @notis_ai/cli@latest -- notis apps build`
+5. Verify the built artifact headlessly:
+   - `npx --package @notis_ai/cli@latest -- notis apps verify`
+6. For a brand-new app, create the remote app and link the project in one step:
+   - `npx --package @notis_ai/cli@latest -- notis apps create "My App" .`
+7. Or link the project to an existing remote app (skip if you used `pull` or `create`):
+   - `npx --package @notis_ai/cli@latest -- notis apps link`
+8. Deploy the artifact to Notis:
+   - `npx --package @notis_ai/cli@latest -- notis apps deploy`
+9. Check project health:
+   - `npx --package @notis_ai/cli@latest -- notis apps doctor`
+
+### App development rules
+
+- Always `build` before `deploy`; run `verify` before deploy when validating an app change.
+- Prefer `npx --package @notis_ai/cli@latest -- notis apps create "Name" .` for the first deploy of a new app.
+- Link before `deploy`, or pass `--app-id <id>` when intentionally deploying without writing local link state.
+- Use `npx --package @notis_ai/cli@latest -- notis apps doctor` to diagnose configuration or dependency issues.
+- Use `npx --package @notis_ai/cli@latest -- notis apps list` to discover existing app IDs before linking.
+- For App Store publishing, do not use the CLI. The user opens the app details page in the Notis Portal, sets visibility to Team or Public, then uses Publish/Update. The backend opens the registry PR on their behalf using a service token. Do not invent any CLI store-publish command.
+
+### App development command reference
+
+- `npx --package @notis_ai/cli@latest -- notis apps list` -- list accessible apps
+- `npx --package @notis_ai/cli@latest -- notis apps init` -- scaffold a new Vite + React + `@notis/sdk` project
+- `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir] [--force] [--version <n>]` -- download the persisted source snapshot for an installed app and link the local directory to that app/version; legacy apps must be redeployed once with the current CLI before they can be pulled
+- `npx --package @notis_ai/cli@latest -- notis apps dev` -- discover local apps, register desktop-local dev sessions, and load them in the Electron Portal Local development sidebar group
+- `npx --package @notis_ai/cli@latest -- notis apps build` -- compile the production artifact
+- `npx --package @notis_ai/cli@latest -- notis apps verify` -- headless render-smoke packaged routes before deploy
+- `npx --package @notis_ai/cli@latest -- notis apps create` -- create a fresh remote app and optionally link the local project
+- `npx --package @notis_ai/cli@latest -- notis apps link` -- associate the project with a remote app
+- `npx --package @notis_ai/cli@latest -- notis apps deploy` -- upload the artifact and editable source snapshot to the linked installed app in Notis
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --direct` -- deploy directly to Supabase storage, bypassing the backend server (auto-fallback when server is down)
+- `npx --package @notis_ai/cli@latest -- notis apps doctor` -- run project diagnostics
+
+App Store publishing is portal-only — there is no CLI publish command.
+
+If the task is specifically about app structure, runtime behavior, or database/view packaging, pair this skill with the `notis-apps` skill. Use `notis-cli` for the command workflow and `notis-apps` for the product/runtime contract.
+
+## IMPORTANT: When NOT to use tool access for app development
+
+When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for any of these operations:
+
+- Creating databases -- declare them in `notis.config.ts` instead
+- Loading or saving app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps deploy`
+- Linting app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` which validates automatically
+- Managing app routes -- write standard Vite + React pages in `app/`, not raw JS files
+
+The only `npx --package @notis_ai/cli@latest -- notis tools exec` calls that are valid during app development are for testing the app's runtime behavior after deployment (e.g., querying a database to verify data was created).
+
+## Section 2: Accessing Tools Through the Notis CLI
+
+Use this section when the current agent does not already have the right tool and needs to reach tools through Notis.
+
+This is the main escape hatch for:
+
+- direct MCP access
+- Composio-backed integrations
+- native Notis tools that are available through the generic CLI tool bridge
+- any task where you need to discover the canonical tool name and schema before execution
+
+### Tool access workflow
+
+1. List available toolkit namespaces:
+   - `npx --package @notis_ai/cli@latest -- notis tools toolkits`
+2. Search for the capability you need using natural language:
+   - `npx --package @notis_ai/cli@latest -- notis tools search "<query>"`
+   - optionally narrow with `--toolkits <csv-or-json>`
+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`
+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:
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'`
+6. If multiple independent calls are needed, use:
+   - `npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'`
+7. If the toolkit is not connected yet, generate the connection URL:
+   - `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>`
+
+### Tool access rules
+
+- Never guess tool names. Discover them with `npx --package @notis_ai/cli@latest -- notis tools search` first.
+- Prefer first-class CLI commands when they exist, but use `npx --package @notis_ai/cli@latest -- notis tools ...` whenever the capability is not covered by a dedicated command.
+- When you know the tool name but not the argument shape, use `npx --package @notis_ai/cli@latest -- notis tools describe` or `--get-schema` before execution.
+- Use `--dry-run` before mutating calls when you want schema validation without execution.
+- If a toolkit is missing, use `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>` to start the connection flow.
+
+### Toolkit mental model
+
+Typical toolkit namespaces include:
+
+- `notis-default` for native Notis tools
+- `composio-*` for Composio-backed integrations
+- `mcp-*` for MCP-backed tools
+
+The pattern is:
+
+1. discover toolkits
+2. search tools
+3. inspect schema if needed
+4. execute the canonical tool
+
+### Tool access examples
+
+Find a tool:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools toolkits
+npx --package @notis_ai/cli@latest -- notis tools search "list today's calendar events"
+```
+
+Inspect a tool before execution:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools describe composio-googlecalendar-default-list_events
+npx --package @notis_ai/cli@latest -- notis tools exec composio-googlecalendar-default-list_events --get-schema
+```
+
+Dry-run a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --dry-run --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --dry-run --arguments '{"database_slug":"tasks"}'
+```
+
+Execute a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --arguments '{"database_slug":"tasks"}'
+```
+
+Connect a missing toolkit:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools link github
+```
+
+## Native database access
+
+Native Notis databases are accessed through the generic tool workflow, not a first-class database command group. Use these canonical tool names:
+
+- `notis-default-list_databases` -- list databases accessible to the current profile
+- `notis-default-get_database` -- inspect read-only metadata and schema detail
+- `notis-default-query` -- query documents from a database
+- `notis-default-upsert_database` -- create or update a database schema
+
+Example workflow before building an app:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-list_databases --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --get-schema
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --arguments '{"database_slug":"social_media_calendar"}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments '{"database_slug":"social_media_calendar","query":{"page_size":1}}'
+```
+
+## 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 describe <command...>` — get the exact command contract for first-class CLI commands
+
+## Summary
+
+Use `notis-cli` for two things:
+
+1. local app development through `npx --package @notis_ai/cli@latest -- notis apps ...`
+2. tool discovery and execution through `npx --package @notis_ai/cli@latest -- notis tools ...`
+
+Most importantly: if you do not currently have the tool you need, especially for direct MCP or integration work, use the Notis CLI instead of treating the task as blocked.
+
+## Troubleshooting
+
+### Deploy fails with "network_error" or "fetch failed"
+
+The backend server at `http://localhost:3001` is not running. Solutions:
+
+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`
+
+### `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.
+
+### Stale bundle in the portal after deploy
+
+The portal caches app bundles by version. If you re-deploy to the same version, the portal may serve the cached old bundle. Solutions:
+
+1. Hard refresh the portal page (Cmd+Shift+R)
+2. Open browser DevTools > Application > Storage > Clear site data
+3. The bundle cache key includes version number -- incrementing the version forces a fresh load

package/skills/notis-query/cli.md

@@ -0,0 +1,40 @@
+# Notis CLI — Database Tool Workflow
+
+Use the generic `notis tools` workflow through NPX for native Notis Database operations from the terminal. The dedicated database command group has been removed.
+
+## 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"`.
+
+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.
+
+## Canonical database tools
+
+- `notis-default-list_databases` — list native databases.
+- `notis-default-get_database` — inspect one database schema.
+- `notis-default-query` — query native database documents.
+- `notis-default-upsert_database` — create or update database schema.
+
+## Workflow
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-list_databases --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --get-schema
+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 --dry-run --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+```
+
+## Supporting command
+
+### `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:
+- `npx --package @notis_ai/cli@latest -- notis doctor`
+- `npx --package @notis_ai/cli@latest -- notis doctor --json`
+

package/src/cli.js

@@ -112,7 +112,7 @@ export function createProgram() {
 
   program
     .name('notis')
-    .description('Agent-first Notis CLI for apps, databases, and generic tool execution')
+    .description('Agent-first Notis CLI for apps and generic tool execution')
     .version(CLI_VERSION)
     .showHelpAfterError()
     .option('--json', 'Shortcut for --output json')