notis-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Notis CLI Skill

Notis CLI 技能

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.
当用户需要通过Notis CLI完成工作时,使用本技能。
本技能涵盖两大CLI工作流:
  1. 本地开发Notis应用。
  2. 通过CLI访问Notis、Composio和MCP工具。

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.
在以下场景激活本技能:
  • 用户希望通过CLI初始化、开发、构建、验证、关联、拉取或部署Notis应用
  • 当前Agent的直接工具列表中没有所需工具
  • 用户希望通过Notis直接访问MCP
  • 用户希望通过Notis使用集成支持的功能,而非本地原生工具
  • 任务中直接提及
    notis
    CLI
请始终使用通过注册表解析的已发布npm包:
  • npx --package @notis_ai/cli@latest -- notis ...
请始终使用这种NPX命令形式,确保Agent运行的是当前已发布的CLI版本。在托管Shell中,CLI通过
NOTIS_JWT
预认证。在本地机器上,CLI持有独立的OAuth授权:
notis login
会在浏览器中完成授权,登录Notis桌面应用则会自动为该账号完成授权。无论哪种方式,授权都归CLI所有,无需桌面应用运行即可自动刷新。
@latest
适用于所有账号,包括测试版账号。每个部署都会报告对应的已发布构建版本,
notis login
会在配置文件中固定该版本,若后续运行时发现版本不匹配,会先将调用转交给正确版本再执行操作。请勿手动指定渠道:在生产配置文件中固定
@beta
会导致机器运行API不兼容的构建版本。
notis doctor
会报告当前激活的渠道,
NOTIS_CLI_AUTO_CHANNEL=0
可在单次运行中关闭版本转交功能。
CLI内置了
notis-cli
基础技能,每次启动时都会在
~/.notis/skills/base/
下刷新其标准副本。它独立于账号技能同步、功能标志、目标选择和云删除操作。

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.
一个配置文件对应一个账号和一个API端点。多个配置文件可共存;切换配置文件不会注销任何账号。
  • npx --package @notis_ai/cli@latest -- notis profile list
    — 查看本机上的所有配置文件,包括其端点、用户及登录状态,当前激活的配置文件会被标记。
  • npx --package @notis_ai/cli@latest -- notis profile use <name>
    — 更改后续命令使用的账号。
  • npx --package @notis_ai/cli@latest -- notis --profile <name> <command>
    — 使用其他账号执行单个命令,不更改当前激活的配置文件。
  • npx --package @notis_ai/cli@latest -- notis login --profile <name>
    — 添加新账号,现有配置文件的凭据保持不变。
  • npx --package @notis_ai/cli@latest -- notis logout
    — 仅注销当前激活的配置文件;添加
    --all-profiles
    参数可清除所有配置文件的登录状态。
在处理用户数据前,请先读取配置文件。
notis whoami
会报告命令将访问的账号和端点;若与用户预期不符,请切换配置文件后再继续操作。

Working against a local
./dev.sh
backend

对接本地
./dev.sh
后端

./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.
./dev.sh
会将其测试账号作为基于租赁的配置文件(
dev-<workspace>-<hash>
)暴露,指向本地后端,并在启动时打印配置文件名称。其凭据仅存在于该工作目录中,且是该目录下的自动默认配置,因此
notis ...
无需额外标志即可直接指向本地API和测试用户。这不是存储的账号配置文件,无法在工作目录外选择使用。
基于开发凭据仅作用于本地后端的特性,需遵循以下两条规则:
  • dev-*
    配置文件仅在
    ./dev.sh
    租赁运行期间存在。若租赁停止,CLI会返回
    dev_runtime_unavailable
    错误,而非将测试用户的令牌发送到生产API。
  • 若要从工作目录内访问真实账号(包括本地后端故障时),请显式指定真实配置文件:
    notis --profile <name> ...
    。这是官方支持的应急方案。

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.
若当前工具集中没有所需工具,请不要停止操作,也不要认为任务无法完成。
请将Notis CLI作为 fallback 访问层。
以下场景尤为重要:
  • 需要直接访问MCP工具
  • 需要Composio支持的集成工具
  • 需要Notis工具,但当前环境未将其作为原生命令暴露
  • 需要在执行前发现标准工具名称
请将Notis CLI视为Composio风格的工具路由流程:先发现可用工具,再通过CLI执行正确的工具。

Section 1: Developing Notis Apps

第一部分:开发Notis应用

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
    .
当目标是从本地工作区或托管沙箱创建或更新Notis应用时,使用本部分内容。
Notis应用是基于Vite + React的项目,使用
@notis/sdk
。完成初始化或拉取并编辑后,选择对应的终端分支:本地桌面端使用
dev → build → verify → 用户批准 → deploy
流程;托管沙箱使用
build → verify → 身份/架构协调 → deploy
流程;商店提交是后续独立确认的操作。
重要提示:
deploy
仅更新当前用户或团队的已安装应用工件。商店提交是独立的、需用户授权的步骤。在用户明确确认当前应用详情页和商店列表已准备就绪后,
apps publish --confirm-ready
会将匹配的已部署版本提交至后端审核流程。
在修改应用前,请选择执行路径:
  • 托管沙箱:沙箱指令或
    /vercel/sandbox
    工作树表明桌面端无法挂载源码。请勿运行
    apps dev
    。创建或编辑请求在
    apps build
    和自动化
    apps verify
    通过后,除非用户明确要求仅预览、只读或不部署,否则将授权
    apps deploy
    ;检查、审核和诊断操作保持只读。
    apps pull <app-id>
    可关联现有应用。在进行任何远程变更前请先测试。若存在退出选项,请停止操作,不进行创建/关联、数据库变更、部署或部署后检查。否则,对于新的未关联应用,将配置文件状态和
    apps list --json
    与标准
    notis.config.ts
    的
    name
    及预期个人/团队范围进行对比:仅在元数据只读(
    include_documents: false
    )的详情读取确认范围后,关联一个精确的可编辑非开发匹配项;若存在歧义/开发冲突/范围不匹配则失败;仅在无精确匹配项时创建应用。默认新应用为个人范围,除非用户明确要求团队范围。需证明配置标题标准化后等于其名称。对于个人创建,仅运行一次
    apps create "<canonical-config-title>" . --json
    。对于明确的团队范围,需发现/描述并试运行
    LOCAL_NOTIS_CREATE_APP
    ,仅执行一次并设置团队可见性和已验证的当前团队范围,验证返回的身份/范围,并关联该精确ID。在全新沙箱中,使用
    npm exec --yes --package agent-browser@latest -- agent-browser install
    安装Agent Browser,并通过
    npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify
    运行验证。通过
    apps list --json
    读取精确的应用ID/版本和门户URL,使用相同的组合命令运行
    apps verify --mode live
    ,并返回精确的门户URL。若测试失败,请在部署前停止;若创建或部署结果未知,请在重试前停止。
  • 本地计算机:运行
    apps dev
    进行实时测试,确认DEV标记的应用和根/挂载验收检查,然后运行
    apps build
    和
    apps verify
    。让用户测试DEV应用,仅在用户明确要求后直接部署该开发身份;请勿在
    apps dev
    后运行
    apps create
    。

App development workflow

应用开发工作流

  1. 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>]
  2. 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
  3. 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
    .
  4. 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.
  5. Check project health:
    • npx --package @notis_ai/cli@latest -- notis apps doctor
  6. 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
  1. 搭建新应用(所有已发布的商店应用均为脚手架;
    notis apps scaffolds list [--search <term>]
    可列出公共注册表中的脚手架,
    --from <slug>
    可下载对应应用的源码):
    • npx --package @notis_ai/cli@latest -- notis apps init ["My App"] [--from <slug>]
  2. 或拉取现有应用的源码进行编辑(项目会自动关联):
    • npx --package @notis_ai/cli@latest -- notis apps pull <app-id>
    • 然后运行
      npm install
      ,递增
      notisAppVersion
      并进行编辑
  3. 本地桌面端分支:运行
    apps dev
    进行实时测试,确认DEV应用和根/挂载验收检查,然后运行
    apps build
    和
    apps verify
    。让用户测试DEV应用,等待用户明确批准。获得批准后,仅运行一次
    apps deploy
    以升级现有
    dev_app_id
    (或更新已关联的应用),然后读取返回结果。请勿在
    apps dev
    后运行
    apps create
    。
  4. 托管沙箱分支:按上述步骤引导安装Agent Browser,然后运行
    apps build
    ,接着执行自动化托管
    apps verify
    。若选择退出自动部署,请在测试完成后停止操作,不进行应用创建/关联、数据库变更、部署或部署后检查。否则,对于新的托管应用,将
    .notis/state.json
    和
    apps list --json
    与标准配置
    name
    及预期范围(默认个人;仅在明确要求时使用团队)进行协调。将开发记录视为冲突检查项。仅在元数据只读(
    include_documents: false
    )的精确应用详情确认范围后,关联一个精确的可编辑非开发匹配项;若存在多个匹配/范围不匹配则失败;仅在无匹配项时创建应用。需证明配置标题标准化后等于配置名称。对于个人创建,仅运行一次
    apps create "<canonical-config-title>" . --json
    并验证ID、slug、编辑权限和个人范围。对于明确的团队范围,需发现并描述
    LOCAL_NOTIS_CREATE_APP
    ,试运行后仅执行一次,使用标准标题、团队可见性和已验证的当前团队范围;验证ID/slug/团队范围/编辑权限并运行
    apps link
    关联该精确ID。然后对比声明的数据库,仅对缺失/变更的向后兼容架构进行变更并验证所有权,仅运行一次
    apps deploy
    ,在实时验证前读取返回的ID/版本/门户URL。
  5. 检查项目健康状态:
    • npx --package @notis_ai/cli@latest -- notis apps doctor
  6. 仅在用户明确批准当前商店预览后,提交已部署版本:
    • 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.
  • 部署前必须先执行
    build
    ;验证应用变更时,部署前需执行
    verify
    。
  • 请勿在托管沙箱中运行
    apps dev
    。除非明确要求仅预览、只读或不部署,否则需部署所有验证成功的沙箱应用创建或编辑结果,然后验证远程ID/版本和实时运行环境。其他应用任务不授权变更操作。
  • 部署不会创建数据库。请先对比;仅实例化缺失或变更的托管应用架构,更新前需验证精确所有权。
  • 在托管应用创建或数据库变更前,需先执行build和verify。仅向后兼容的架构扩展可在部署前进行。
  • 在托管沙箱中,需引导安装
    agent-browser
    并将其包添加到验证命令的
    PATH
    中;
    --no-browser
    不是有效的自动化验证通过条件。
  • 请勿部署本地桌面端的编辑内容,直到用户测试DEV应用并提出请求。
  • 对于已运行
    apps dev
    的项目,首次部署优先使用
    npx --package @notis_ai/cli@latest -- notis apps deploy
    ;该命令会直接升级开发中的应用。
  • 部署前需先关联应用,或在有意不写入本地关联状态时传递
    --app-id <id>
    参数。
  • 使用
    npx --package @notis_ai/cli@latest -- notis apps doctor
    诊断配置或依赖问题。
  • 在关联前和部署后,使用
    npx --package @notis_ai/cli@latest -- notis apps list --json
    发现精确的slug、权限、版本和门户链接;使用元数据只读(
    include_documents: false
    )的精确应用详情读取操作确认个人/团队范围,无需实例化数据库。
  • 请勿将部署批准视为商店批准。请先将可见性设置为团队或公开,仅在用户明确确认当前应用详情页和商店列表后,再运行
    apps publish --confirm-ready
    。
  • apps publish --confirm-ready
    会将已部署的快照提交至与应用详情页相同的后端审核流程。若缺少确认、列表媒体不完整、本地/部署版本不匹配、可见性为私有或存在待处理审核,该命令必须拒绝提交。

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.
  • npx --package @notis_ai/cli@latest -- notis apps list
    -- 列出可访问的应用
  • npx --package @notis_ai/cli@latest -- notis apps init
    -- 搭建新的Vite + React +
    @notis/sdk
    项目
  • npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir] [--force] [--source-version <n>]
    -- 下载已安装应用的持久化源码快照,并将本地目录关联到该应用/版本;旧版应用需先使用当前CLI重新部署一次才能被拉取
  • npx --package @notis_ai/cli@latest -- notis apps dev
    -- 发现本地应用,注册桌面端本地开发会话,并在Electron门户中将其加载为带DEV标记的工作区条目
  • npx --package @notis_ai/cli@latest -- notis apps build
    -- 编译生产工件
  • npx --package @notis_ai/cli@latest -- notis apps verify
    -- 在部署前以无头模式渲染打包后的路由进行冒烟测试
  • npx --package @notis_ai/cli@latest -- notis apps create
    -- 创建新的远程应用,并可选择关联本地项目
  • npx --package @notis_ai/cli@latest -- notis apps link
    -- 将本地项目与远程应用关联
  • npx --package @notis_ai/cli@latest -- notis apps deploy
    -- 将工件和可编辑源码快照上传至Notis中已关联的已安装应用
  • npx --package @notis_ai/cli@latest -- notis apps deploy --direct
    -- 直接部署到Supabase存储,绕过后端服务器(服务器宕机时自动 fallback)
  • npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready
    -- 在用户明确确认后,提交匹配的已部署版本进行团队或公开商店审核
  • npx --package @notis_ai/cli@latest -- notis apps doctor
    -- 运行项目诊断
应用详情页仍是可视化审核界面,并提供相同的发布/更新操作。CLI命令适用于Agent完成已获批准的提交;它不会削弱独立的确认环节。
若任务专门涉及应用结构、运行时行为或数据库/视图打包,请将本技能与
notis-apps
技能结合使用。使用
notis-cli
处理命令工作流,使用
notis-apps
处理产品/运行时契约。

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.
构建或部署Notis应用时,请勿使用
npx --package @notis_ai/cli@latest -- notis tools exec
进行应用文件操作:
  • 加载或保存应用文件 -- 使用
    npx --package @notis_ai/cli@latest -- notis apps build
    和
    npx --package @notis_ai/cli@latest -- notis apps deploy
  • 检查应用文件语法 -- 使用
    npx --package @notis_ai/cli@latest -- notis apps build
    ,该命令会自动进行验证
  • 管理应用路由 -- 在
    app/
    目录中编写标准Vite + React页面,而非原始JS文件
数据库架构是例外:在
notis.config.ts
中声明slug不会创建数据库。请使用先发现后操作的原生数据库工具工作流,在部署前创建/更新并读取每个应用所属的架构。工具调用也适用于部署后测试运行时行为。

Section 2: Accessing Tools Through the Notis CLI

第二部分:通过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
当当前Agent没有合适的工具,需要通过Notis访问工具时,使用本部分内容。
这是以下场景的主要应急方案:
  • 直接访问MCP
  • Composio支持的集成
  • 可通过通用CLI工具桥访问的原生Notis工具
  • 任何需要在执行前发现标准工具名称和架构的任务

Tool access workflow

工具访问工作流

  1. List available toolkit namespaces:
    • npx --package @notis_ai/cli@latest -- notis tools toolkits --timeout-ms 90000
  2. 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>"
  3. 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
  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, 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 -
  1. 列出可用的工具包命名空间:
    • npx --package @notis_ai/cli@latest -- notis tools toolkits --timeout-ms 90000
  2. 使用自然语言搜索所需功能:
    • npx --package @notis_ai/cli@latest -- notis tools search "<query>" --timeout-ms 90000
    • 可选择添加已知字段提示:
      --known-fields "<key:value>"
  3. 若需要,检查精确的工具和参数架构:
    • 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
  4. 若工具会进行变更操作或架构较为复杂,执行前请验证参数:
    • npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --dry-run --arguments '<json>'
  5. 执行工具:
    • npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'
  6. 若需要多次独立调用,使用:
    • npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'
  7. 若工具包尚未连接,启动其连接流程:
    • npx --package @notis_ai/cli@latest -- notis tools link <toolkit>
    • 对于已撤销或无效的基于凭据的连接,通过标准输入传入凭据JSON重新连接:
      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.
首次运行时,发现桥可能会查询多个已连接的MCP服务器,耗时可能超过CLI默认的30秒超时时间。对于
tools toolkits
、
tools search
、
tools describe
和仅查询架构的操作,请始终使用
--timeout-ms 90000
参数。若发现调用返回
network_timeout
,请使用
--timeout-ms 90000
参数重试一次该命令;请勿发起新查询、自行编造工具名称或循环使用默认30秒超时的命令。
发现操作是幂等的,但应加以限制:每个任务运行一次工具包列表查询,每个不同功能运行一次自然语言搜索,并将返回的标准工具名称和架构缓存至当前会话结束。成功获取搜索/架构响应后,请直接调用返回的标准工具(变更操作前先试运行),而非在每次连接服务操作前重复相同的发现请求。

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.
  • 请勿猜测工具名称。请先使用
    npx --package @notis_ai/cli@latest -- notis tools search
    发现工具。
  • 若存在原生CLI命令,请优先使用;但当功能未被专用命令覆盖时,请使用
    npx --package @notis_ai/cli@latest -- notis tools ...
    。
  • 若已知工具名称但不了解参数格式,请在执行前使用
    npx --package @notis_ai/cli@latest -- notis tools describe
    或
    --get-schema
    。
  • 若要进行架构验证而不执行操作,请在变更调用前使用
    --dry-run
    。
  • 若缺少工具包,请使用
    npx --package @notis_ai/cli@latest -- notis tools link <toolkit>
    启动连接流程。
  • 使用
    --reconnect
    替换现有连接。若存在多个账号,请使用
    --connection-id <id>
    选择其中一个。
  • 对于API密钥、基础认证或其他凭据JSON,优先使用
    --credentials -
    并通过管道或重定向标准输入传入。避免在命令中直接输入密钥,因为它们可能会被记录到Shell历史和进程列表中。

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
典型的工具包命名空间包括:
  • notis
    :原生Notis工具
  • composio-*
    :Composio支持的集成
  • mcp-*
    :MCP支持的工具
流程模式为:
  1. 发现工具包
  2. 搜索工具
  3. 若需要,检查架构
  4. 执行标准工具

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
查找工具:
bash
npx --package @notis_ai/cli@latest -- notis tools toolkits
npx --package @notis_ai/cli@latest -- notis tools search "list today's calendar events"
执行前检查工具:
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
试运行工具调用:
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}}'
执行工具调用:
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}}'
连接缺失的工具包:
bash
npx --package @notis_ai/cli@latest -- notis tools link github
重新连接基于凭据的工具包,避免将密钥写入Shell历史:
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
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.
原生Notis数据库通过通用工具工作流访问,而非原生数据库命令组。请使用以下标准工具名称:
  • LOCAL_NOTIS_DATABASE_LIST_DATABASES
    -- 列出当前配置文件可访问的数据库
  • LOCAL_NOTIS_DATABASE_GET_DATABASE
    -- 检查只读元数据和架构细节
  • LOCAL_NOTIS_DATABASE_QUERY
    -- 查询数据库中的文档
  • LOCAL_NOTIS_DATABASE_UPSERT_DATABASE
    -- 创建或更新数据库架构。每个数据库都属于一个Notis应用:创建时需在
    app
    参数中指定所属应用的slug或ID(若需要,请先使用
    LOCAL_NOTIS_CREATE_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}}'
当
LOCAL_NOTIS_DATABASE_LIST_DATABASES
或
LOCAL_NOTIS_DATABASE_GET_DATABASE
返回数据库ID时,在
LOCAL_NOTIS_DATABASE_QUERY
中优先使用
database_id
;
database_slug
仍作为 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
  • npx --package @notis_ai/cli@latest -- notis whoami
    — 确认命令将访问的账号和端点
  • npx --package @notis_ai/cli@latest -- notis doctor
    — 在依赖CLI前验证CLI配置、认证、路由和API可达性
  • npx --package @notis_ai/cli@latest -- notis describe <command...>
    — 获取原生CLI命令的精确命令契约

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.
notis-cli
用于两大场景:
  1. 通过
    npx --package @notis_ai/cli@latest -- notis apps ...
    进行本地应用开发
  2. 通过
    npx --package @notis_ai/cli@latest -- notis tools ...
    进行工具发现与执行
最重要的是:若当前没有所需工具,尤其是在直接使用MCP或集成工作时,请使用Notis CLI,而非认为任务无法完成。

Troubleshooting

故障排除

CLI returns
auth_expired
or
auth_missing

CLI返回
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.
配置文件的浏览器授权已过期或从未授予。运行
notis login
(若失败的配置文件不是当前激活的,请添加
--profile <name>
参数),并让用户在浏览器中批准授权请求。在JSON/Agent模式下,第一个提示就是要运行的精确命令。请勿将刷新令牌复制到命令中,也不要尝试自行生成凭据。
若配置文件是
dev-*
类型,请重启其所属工作目录中的
./dev.sh
,或切换到真实账号配置文件。

Deploy fails with "network_error" or "fetch failed"

部署失败,返回"network_error"或"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:
  1. Run
    npx --package @notis_ai/cli@latest -- notis doctor
    and confirm
    api_base
    is a live Notis host
  2. Use
    --direct
    for app deploys when you only need Supabase storage upload:
    npx --package @notis_ai/cli@latest -- notis apps deploy --direct
  3. 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.
CLI默认指向Notis生产API(
https://api.notis.ai
,若登录用户为测试版用户则指向
https://api-beta.notis.ai
)。解决方案:
  1. 运行
    npx --package @notis_ai/cli@latest -- notis doctor
    ,确认
    api_base
    是有效的Notis主机
  2. 若仅需上传到Supabase存储,请在应用部署时使用
    --direct
    参数:
    npx --package @notis_ai/cli@latest -- notis apps deploy --direct
  3. 若认证信息看起来已过期,请运行
    npx --package @notis_ai/cli@latest -- notis login
    并重试
本地后端仅为Notis开发者测试通道。请勿通过本技能将CLI重定向到回环地址 — 该路径由
./dev.sh
管理,它会暴露自己的基于租赁的
dev-*
配置文件。

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

npx --package @notis_ai/cli@latest -- notis doctor
显示health/tool_roundtrip错误

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.
CLI健康检查会 ping 配置的生产API。
backend_call: local
的应用开发命令(
init
、
build
、
verify
、
link
、
doctor
)可离线工作。
dev
、
pull
、
create
、
list
和常规
deploy
需要生产API;当Supabase凭据可用时,
deploy --direct
可绕过API。

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
门户会按版本缓存应用包。若重新部署到同一版本,门户可能会提供缓存的旧包。解决方案:
  1. 强制刷新门户页面(Cmd+Shift+R)
  2. 打开浏览器开发者工具 > 应用 > 存储 > 清除站点数据
  3. 包缓存键包含版本号 — 递增版本号会强制加载新包