@notis_ai/cli 0.2.1 → 0.2.3

package/skills/notis-cli/SKILL.md

@@ -0,0 +1,260 @@
+---
+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 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`
+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` 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-list_events
+npx --package @notis_ai/cli@latest -- notis tools exec composio-googlecalendar-list_events --get-schema
+```
+
+Dry-run a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --dry-run --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"database_id":"tasks-db-id","query":{"page_size":10}}'
+```
+
+Execute a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"tasks-db-id","query":{"page_size":10}}'
+```
+
+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:
+
+- `LOCAL_NOTIS_DATABASE_LIST_DATABASES` -- list databases accessible to the current profile
+- `LOCAL_NOTIS_DATABASE_GET_DATABASE` -- inspect read-only metadata and schema detail
+- `LOCAL_NOTIS_DATABASE_QUERY` -- query documents from a database
+- `LOCAL_NOTIS_DATABASE_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 LOCAL_NOTIS_DATABASE_LIST_DATABASES --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --get-schema
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"social_media_calendar"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"social-media-calendar-db-id","query":{"page_size":1}}'
+```
+
+When `LOCAL_NOTIS_DATABASE_LIST_DATABASES` or `LOCAL_NOTIS_DATABASE_GET_DATABASE` returns a database ID, prefer `database_id` for `LOCAL_NOTIS_DATABASE_QUERY`; `database_slug` remains supported as a fallback.
+
+## 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,39 @@
+# 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
+
+- `LOCAL_NOTIS_DATABASE_LIST_DATABASES` — list native databases.
+- `LOCAL_NOTIS_DATABASE_GET_DATABASE` — inspect one database schema.
+- `LOCAL_NOTIS_DATABASE_QUERY` — query native database documents.
+- `LOCAL_NOTIS_DATABASE_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 LOCAL_NOTIS_DATABASE_LIST_DATABASES --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --get-schema
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_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

@@ -1,10 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { COMMAND_SPECS, GROUP_SUMMARIES } from './command-specs/index.js';
 import { OutputManager } from './runtime/output.js';
 import { asCliError } from './runtime/errors.js';
 import { resolveRuntimeProfile, workspacePath } from './runtime/profiles.js';
 
-const CLI_VERSION = '0.2.0';
+// Read the version from package.json: the publish pipeline bumps the manifest
+// (scripts/release-utils.js applyVersion), so a hardcoded string here goes
+// stale on every release.
+function readCliVersion() {
+  try {
+    const manifestPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    const version = JSON.parse(readFileSync(manifestPath, 'utf-8')).version;
+    if (typeof version === 'string' && version.trim()) {
+      return version.trim();
+    }
+  } catch {
+    // Fall through to the placeholder below.
+  }
+  return '0.0.0';
+}
+
+const CLI_VERSION = readCliVersion();
 
 function buildHelpFooter(spec) {
   const lines = [
@@ -64,7 +83,16 @@ function attachSpec(program, parentMap, spec, specs) {
   }
 
   for (const option of spec.args_schema?.options || []) {
-    command.option(option.flags, option.description);
+    if (option.collect) {
+      command.option(
+        option.flags,
+        option.description,
+        (value, previous) => [...(previous || []), value],
+        [],
+      );
+    } else {
+      command.option(option.flags, option.description);
+    }
   }
 
   command.action(async (...raw) => {
@@ -112,7 +140,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')