# 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 screenshot [dir]`

Capture listing screenshots of each route via the headless harness.

When to use: Generate metadata/screenshot-N.png for the App Store listing. Apps are icon-led (like Raycast) — there is no cover image, only these screenshots. Run before notis apps verify / deploy / publish.

Options:
- `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
- `--port <n>` — Loopback port. Default: auto-pick.
- `--width <px>` — Viewport width. Default: 2000.
- `--height <px>` — Viewport height. Default: 1250 (16:10).
- `--output-dir <dir>` — Where to write screenshot-N.png. Default: metadata/.
- `--mode <mode>` — stub | live. Default stub. Live renders against real data via the CLI JWT (requires a linked app), so screenshots show actual content instead of empty states.
- `--skip-build` — Skip notis apps build; reuse existing .notis/output/.

Examples:
- `npx --package @notis_ai/cli@latest -- notis apps screenshot`
- `npx --package @notis_ai/cli@latest -- notis apps screenshot --routes home,history`
- `npx --package @notis_ai/cli@latest -- notis apps screenshot --mode live  # populated screenshots from real data`

### `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`

