Notis CLI Skill

Use this skill when the user wants work done through the Notis CLI.

This skill covers two main CLI workflows:

Developing Notis apps locally.
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

. On a local machine the CLI holds its own OAuth grant:

notis login

authorizes one in the browser, and signing in to the Notis desktop app authorizes one automatically for that account. Either way the grant belongs to the CLI, which refreshes it without the desktop app running.

@latest

is correct for every account, including beta ones. Each deployment reports which published build belongs to it,

notis login

pins that on the profile, and a later run that finds itself on the wrong build hands the invocation to the right one before doing anything. Never substitute a channel by hand: pinning

@beta

on a production profile is how a machine ends up running a build its API does not expect.

notis doctor

reports the active channel, and

NOTIS_CLI_AUTO_CHANNEL=0

turns the hand-off off for a run.

The CLI bundles this

notis-cli

base skill and refreshes its canonical copy under

~/.notis/skills/base/

on every launch. It is independent of account-skill sync, feature flags, target selection, and cloud deletion.

Profiles: accounts and endpoints

A profile is one account paired with one API endpoint. Profiles live side by side; switching between them never signs any of them out.

```
npx --package @notis_ai/cli@latest -- notis profile list
```
— every profile on this machine, with its endpoint, user, and whether it is signed in. The active one is marked.

npx --package @notis_ai/cli@latest -- notis profile use <name>

— change which account subsequent commands run as.

```
npx --package @notis_ai/cli@latest -- notis --profile <name> <command>
```
— run a single command as another account without changing the active one.

npx --package @notis_ai/cli@latest -- notis login --profile <name>

— add an account. The existing profiles keep their credentials.

npx --package @notis_ai/cli@latest -- notis logout

— sign out of the active profile only; pass

--all-profiles

to clear every one.

Read the profile before acting on the user's data.

notis whoami

reports the account and endpoint a command will hit; if that is not the account the user meant, switch profiles rather than proceeding.

Working against a local

./dev.sh

backend

./dev.sh

exposes its test account as a lease-backed profile (

dev-<workspace>-<hash>

) pointing at the local backend, and prints the name on startup. Its credential stays in that worktree and it is the automatic default there, so

notis ...

targets the local API and test user with no extra flags. It is not a stored account profile and cannot be selected outside the worktree.

Two rules follow from the dev credential being scoped to that local backend:

A
```
dev-*
```
profile only exists while its
```
./dev.sh
```
lease is running. If it is stopped, the CLI fails with
```
dev_runtime_unavailable
```
instead of sending the test user's token to the live API.
To reach a real account from inside a worktree — including when the local backend is wedged — name a real profile explicitly:
```
notis --profile <name> ...
```
. That is the supported escape hatch.

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 or a hosted sandbox.

Notis apps are Vite + React projects using

@notis/sdk

. After init or pull and editing, choose one terminal branch: local Desktop uses

dev → build → verify → user approval → deploy

; hosted sandbox uses

build → verify → identity/schema reconciliation → deploy

; Store submission is a later, separately confirmed action.

Important:

deploy

only updates the installed app artifact for the current user or team. Store submission is a separate, user-gated step. After the user explicitly confirms that the current App Details page and Store listing are ready,

apps publish --confirm-ready

submits the matching deployed version through the backend review flow.

Choose the execution path before changing the app:

Hosted sandbox: a sandbox instruction or
```
/vercel/sandbox
```
working tree proves that Desktop cannot mount the source. Do not run
```
apps dev
```
. A create or edit request authorizes
```
apps deploy
```
after
```
apps build
```
and automated
```
apps verify
```
pass unless the user explicitly requests preview-only, read-only, or no deployment; inspection, review, and diagnosis stay read-only.
```
apps pull <app-id>
```
links an existing app. Test before any remote mutation. If an opt-out applies, stop there without create/link, database mutation, deploy, or post-deploy checks. Otherwise, for a new unlinked app, compare profile state and
```
apps list --json
```
with the canonical
```
notis.config.ts
```
```
name
```
and intended personal/team scope: link one exact editable non-development match after a metadata-only (
```
include_documents: false
```
) detail read proves scope, fail on any ambiguity/development collision/scope mismatch, or create only on zero exact matches. Default new apps to personal scope unless the user explicitly asks for team scope. Prove canonicalizing the config title yields its name. For personal creation, run
```
apps create "<canonical-config-title>" . --json
```
exactly once. For explicit team scope, discover/describe and dry-run
```
LOCAL_NOTIS_CREATE_APP
```
, execute it exactly once with team visibility and verified current team scope, verify the returned identity/scope, and link that exact id. In a fresh sandbox, install Agent Browser with
```
npm exec --yes --package agent-browser@latest -- agent-browser install
```
and run verification through
```
npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify
```
. Read back the exact app id/version and Portal URL with
```
apps list --json
```
, run the same combined command with
```
apps verify --mode live
```
, and return the exact Portal URL. Stop before deployment on test failure and before retry on an outcome-unknown create or deploy.
Local computer: run
```
apps dev
```
, let the user test the DEV-badged app, and deploy that development identity directly only after the user explicitly asks; never run
```
apps create
```
after
```
apps dev
```
.

App development workflow

Scaffold a new app (every published Store app is a scaffold;

notis apps scaffolds list [--search <term>]

lists them from the public registry, and

--from <slug>

downloads that app's source):

npx --package @notis_ai/cli@latest -- notis apps init ["My App"] [--from <slug>]

Or pull an existing app's source to edit it (the project is linked automatically):
- ```
npx --package @notis_ai/cli@latest -- notis apps pull <app-id>
```
- then run
```
npm install
```
  , increment
```
notisAppVersion
```
  , and edit
Local Desktop branch: run
```
apps dev
```
for live testing, confirm the DEV app and root/mount acceptance checks, then run
```
apps build
```
and
```
apps verify
```
. Let the user test the DEV app and stop for explicit user approval. When approved, run exactly one
```
apps deploy
```
to promote the existing
```
dev_app_id
```
(or update the already linked app), then read it back. Never run
```
apps create
```
after
```
apps dev
```
.
Hosted sandbox branch: bootstrap Agent Browser as described above, then run
```
apps build
```
followed by the automated hosted
```
apps verify
```
. If automatic deployment is opted out, stop after those tests with no app create/link, database mutation, deploy, or post-deploy check. Otherwise, for a new hosted app, reconcile
```
.notis/state.json
```
and
```
apps list --json
```
against the canonical config
```
name
```
and intended scope (personal by default; team only when explicitly requested). Include development rows as collision checks. Link one exact editable non-dev match only after a metadata-only (
```
include_documents: false
```
) exact app detail proves scope; fail on multiple/scope mismatch, or create only on zero. Prove canonicalize(config title) equals config name. For personal creation, run
```
apps create "<canonical-config-title>" . --json
```
exactly once and verify id, slug, edit permission, and personal scope. For explicit team scope, discover and describe
```
LOCAL_NOTIS_CREATE_APP
```
, dry-run it, then execute it exactly once with the canonical title, team visibility, and verified current team scope; verify id/slug/team scope/edit permission and
```
apps link
```
that exact id. Then compare declared databases, mutate only missing/changed backward-compatible schemas with ownership proof, run exactly one
```
apps deploy
```
, and read back id/version/Portal URL before live verify.

Check project health:

npx --package @notis_ai/cli@latest -- notis apps doctor

Only after the user explicitly approves the current Store preview, submit the deployed version:
- ```
npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready
```

App development rules

Always
```
build
```
before
```
deploy
```
; run
```
verify
```
before deploy when validating an app change.
Never run
```
apps dev
```
in a hosted sandbox. Deploy every successfully verified sandbox app create or edit unless explicitly told preview-only, read-only, or no-deploy, then prove the remote id/version and live runtime. Other app tasks do not authorize mutation.
Deploy does not create databases. Compare first; materialize only missing or changed hosted-app schemas, and verify exact ownership before an update.
Build and verify before hosted app creation or database mutation. Only backward-compatible schema expansion may happen before deployment.
In hosted sandboxes, bootstrap
```
agent-browser
```
and include its package on the verification command's
```
PATH
```
;
```
--no-browser
```
is not a passing automated gate.
Never deploy a local Desktop edit until the user tests the DEV app and asks.
Prefer
```
npx --package @notis_ai/cli@latest -- notis apps deploy
```
for the first deploy of a project already run with
```
apps dev
```
; it promotes the development app in place.
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 --json
```
to discover exact slugs, permissions, versions, and Portal links before linking and after deployment; use a metadata-only (
```
include_documents: false
```
) exact app-detail read to prove personal/team scope without materializing databases.
Never treat deploy approval as Store approval. Set visibility to Team or Public first, then run
```
apps publish --confirm-ready
```
only after the user explicitly confirms the current App Details page and Store listing.
```
apps publish --confirm-ready
```
submits the deployed snapshot through the same backend review flow as App Details. It must reject missing confirmation, incomplete listing media, a local/deployed version mismatch, private visibility, or an existing pending review.

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] [--source-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 as DEV-badged Workspace rows in the Electron Portal

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 publish --confirm-ready
```
-- submit the matching deployed version for Team or Public Store review after explicit user confirmation

npx --package @notis_ai/cli@latest -- notis apps doctor

-- run project diagnostics

App Details remains the visual review surface and offers the same Publish/Update action. The CLI command is for agents completing an already approved submission; it does not weaken the separate confirmation gate.

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 app file operations:

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

Database schemas are the exception: declaring a slug in

notis.config.ts

does not create it. Use the discovery-first native database tool workflow to create/update and read back each app-owned schema before deployment. Tool calls are also valid for testing runtime behavior after deployment.

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

List available toolkit namespaces:

npx --package @notis_ai/cli@latest -- notis tools toolkits --timeout-ms 90000

Search for the capability you need using natural language:

npx --package @notis_ai/cli@latest -- notis tools search "<query>" --timeout-ms 90000

optionally add known field hints with
```
--known-fields "<key:value>"
```

If needed, inspect the exact tool and parameter schema:

npx --package @notis_ai/cli@latest -- notis tools describe <tool-name> --timeout-ms 90000

npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --get-schema --timeout-ms 90000

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>'

Execute the tool:

npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'

If multiple independent calls are needed, use:

npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'

If the toolkit is not connected yet, start its connection flow:
- ```
npx --package @notis_ai/cli@latest -- notis tools link <toolkit>
```
- For a revoked or invalid credential-based connection, reconnect with credential JSON on stdin:
```
npx --package @notis_ai/cli@latest -- notis tools link <toolkit> --reconnect --credentials -
```

Discovery latency and caching

The discovery bridge may query several connected MCP servers on a cold run and can legitimately take longer than the CLI's general 30-second timeout. Always use

--timeout-ms 90000

for

tools toolkits

tools search

tools describe

, and schema-only discovery calls. If a discovery call returns

network_timeout

, retry that same command once with

--timeout-ms 90000

; do not start a new query, invent a tool name, or loop on the default 30-second command.

Discovery is idempotent but should be bounded: run the toolkit listing once per task, run one natural-language search per distinct capability, and cache the returned canonical tool names and schemas for the rest of the current turn. After a successful search/schema response, call the returned canonical tool directly (with a dry-run before mutations) instead of repeating the same discovery request before every connected-service action.

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.

Use
```
--reconnect
```
to replace an existing connection. If multiple accounts exist, select one with
```
--connection-id <id>
```
.
For API keys, basic auth, or other credential JSON, prefer
```
--credentials -
```
and pipe or redirect stdin. Avoid inline secrets because they can enter shell history and process listings.

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:

discover toolkits
search tools
inspect schema if needed
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

Reconnect a credential-based toolkit without putting the secret in shell history:

bash

npx --package @notis_ai/cli@latest -- notis tools link dataforseo --reconnect --credentials - < credentials.json

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. Every database belongs to a Notis app: creation requires the owning app's slug or id in the
```
app
```
argument (create the app first with
```
LOCAL_NOTIS_CREATE_APP
```
if needed)

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

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 whoami
```
— confirm which account and endpoint a command will target
```
npx --package @notis_ai/cli@latest -- notis doctor
```
— verify CLI config, auth, routing, 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:

local app development through

npx --package @notis_ai/cli@latest -- notis apps ...

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

CLI returns

auth_expired

auth_missing

The profile's browser authorization has lapsed or was never granted. Run

notis login

(add

--profile <name>

when the failing profile is not the active one) and have the user approve the browser prompt. In JSON/agent mode the first hint is the exact command to run. Do not copy refresh tokens into commands or try to mint a credential yourself.

If the profile is a

dev-*

one, the fix is to restart

./dev.sh

in the workspace it belongs to, or to switch to a real account profile.

Deploy fails with "network_error" or "fetch failed"

The CLI defaults to the live Notis API (

https://api.notis.ai

, or

https://api-beta.notis.ai

when the signed-in user is on beta). Solutions:

Run

npx --package @notis_ai/cli@latest -- notis doctor

and confirm

api_base

is a live Notis host

Use

--direct

for app deploys when you only need Supabase storage upload:

npx --package @notis_ai/cli@latest -- notis apps deploy --direct

If auth looks stale, run

npx --package @notis_ai/cli@latest -- notis login

and retry

Localhost backends are a Notis-developer test lane only. Do not retarget the CLI at loopback from this skill — that path is owned by

./dev.sh

, which exposes its own lease-backed

dev-*

profile.

npx --package @notis_ai/cli@latest -- notis doctor

shows health/tool_roundtrip errors

The CLI health check pings the configured live API. App development commands that are

backend_call: local

(

init

build

verify

link

doctor

) work offline.

dev

pull

create

list

, and normal

deploy

need the live API;

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:

Hard refresh the portal page (Cmd+Shift+R)
Open browser DevTools > Application > Storage > Clear site data
The bundle cache key includes version number -- incrementing the version forces a fresh load

notis-cli

NPX Install

Tags

SKILL.md Content

Notis CLI Skill

When to use this skill

Profiles: accounts and endpoints

Working against a local
`./dev.sh`
backend

Critical rule for missing tools

Section 1: Developing Notis Apps

App development workflow

App development rules

App development command reference

IMPORTANT: When NOT to use tool access for app development

Section 2: Accessing Tools Through the Notis CLI

Tool access workflow

Discovery latency and caching

Tool access rules

Toolkit mental model

Tool access examples

Native database access

Supporting commands

Summary

Troubleshooting

CLI returns
`auth_expired`
or
`auth_missing`

Deploy fails with "network_error" or "fetch failed"

`npx --package @notis_ai/cli@latest -- notis doctor`
shows health/tool_roundtrip errors

Stale bundle in the portal after deploy

notis-cli

NPX Install

Tags

SKILL.md Content

Notis CLI Skill

When to use this skill

Profiles: accounts and endpoints

Working against a local ./dev.sh backend

Critical rule for missing tools

Section 1: Developing Notis Apps

App development workflow

App development rules

App development command reference

IMPORTANT: When NOT to use tool access for app development

Section 2: Accessing Tools Through the Notis CLI

Tool access workflow

Discovery latency and caching

Tool access rules

Toolkit mental model

Tool access examples

Native database access

Supporting commands

Summary

Troubleshooting

CLI returns auth_expired or auth_missing

Deploy fails with "network_error" or "fetch failed"

npx --package @notis_ai/cli@latest -- notis doctor shows health/tool_roundtrip errors

Stale bundle in the portal after deploy

Working against a local
`./dev.sh`
backend

CLI returns
`auth_expired`
or
`auth_missing`

`npx --package @notis_ai/cli@latest -- notis doctor`
shows health/tool_roundtrip errors