notis-cli
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseNotis CLI Skill
Notis CLI 技能
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.
当用户需要通过Notis CLI完成工作时,使用本技能。
本技能涵盖两大CLI工作流:
- 本地开发Notis应用。
- 通过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 CLI directly
notis
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 . On a local machine the CLI holds its own OAuth grant: 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.
NOTIS_JWTnotis login@latestnotis login@betanotis doctorNOTIS_CLI_AUTO_CHANNEL=0The CLI bundles this base skill and refreshes its canonical copy under on every launch. It is independent of account-skill sync, feature flags, target selection, and cloud deletion.
notis-cli~/.notis/skills/base/在以下场景激活本技能:
- 用户希望通过CLI初始化、开发、构建、验证、关联、拉取或部署Notis应用
- 当前Agent的直接工具列表中没有所需工具
- 用户希望通过Notis直接访问MCP
- 用户希望通过Notis使用集成支持的功能,而非本地原生工具
- 任务中直接提及CLI
notis
请始终使用通过注册表解析的已发布npm包:
npx --package @notis_ai/cli@latest -- notis ...
请始终使用这种NPX命令形式,确保Agent运行的是当前已发布的CLI版本。在托管Shell中,CLI通过预认证。在本地机器上,CLI持有独立的OAuth授权:会在浏览器中完成授权,登录Notis桌面应用则会自动为该账号完成授权。无论哪种方式,授权都归CLI所有,无需桌面应用运行即可自动刷新。
NOTIS_JWTnotis login@latestnotis login@betanotis doctorNOTIS_CLI_AUTO_CHANNEL=0CLI内置了基础技能,每次启动时都会在下刷新其标准副本。它独立于账号技能同步、功能标志、目标选择和云删除操作。
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.
- — 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 list - — change which account subsequent commands run as.
npx --package @notis_ai/cli@latest -- notis profile use <name> - — run a single command as another account without changing the active one.
npx --package @notis_ai/cli@latest -- notis --profile <name> <command> - — add an account. The existing profiles keep their credentials.
npx --package @notis_ai/cli@latest -- notis login --profile <name> - — sign out of the active profile only; pass
npx --package @notis_ai/cli@latest -- notis logoutto clear every one.--all-profiles
Read the profile before acting on the user's data. reports the account and endpoint a command will hit; if that is not the account the user meant, switch profiles rather than proceeding.
notis whoami一个配置文件对应一个账号和一个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 whoamiWorking against a local ./dev.sh
backend
./dev.sh对接本地./dev.sh
后端
./dev.sh./dev.shdev-<workspace>-<hash>notis ...Two rules follow from the dev credential being scoped to that local backend:
- A profile only exists while its
dev-*lease is running. If it is stopped, the CLI fails with./dev.shinstead of sending the test user's token to the live API.dev_runtime_unavailable - To reach a real account from inside a worktree — including when the local backend is wedged — name a real profile explicitly: . That is the supported escape hatch.
notis --profile <name> ...
./dev.shdev-<workspace>-<hash>notis ...基于开发凭据仅作用于本地后端的特性,需遵循以下两条规则:
- 配置文件仅在
dev-*租赁运行期间存在。若租赁停止,CLI会返回./dev.sh错误,而非将测试用户的令牌发送到生产API。dev_runtime_unavailable - 若要从工作目录内访问真实账号(包括本地后端故障时),请显式指定真实配置文件:。这是官方支持的应急方案。
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 . After init or pull and editing, choose one terminal branch: local Desktop uses ; hosted sandbox uses ; Store submission is a later, separately confirmed action.
@notis/sdkdev → build → verify → user approval → deploybuild → verify → identity/schema reconciliation → deployImportant: 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, submits the matching deployed version through the backend review flow.
deployapps publish --confirm-readyChoose the execution path before changing the app:
- Hosted sandbox: a sandbox instruction or working tree proves that Desktop cannot mount the source. Do not run
/vercel/sandbox. A create or edit request authorizesapps devafterapps deployand automatedapps buildpass unless the user explicitly requests preview-only, read-only, or no deployment; inspection, review, and diagnosis stay read-only.apps verifylinks 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 andapps pull <app-id>with the canonicalapps list --jsonnotis.config.tsand intended personal/team scope: link one exact editable non-development match after a metadata-only (name) 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, runinclude_documents: falseexactly once. For explicit team scope, discover/describe and dry-runapps create "<canonical-config-title>" . --json, 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 withLOCAL_NOTIS_CREATE_APPand run verification throughnpm exec --yes --package agent-browser@latest -- agent-browser install. Read back the exact app id/version and Portal URL withnpx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify, run the same combined command withapps list --json, and return the exact Portal URL. Stop before deployment on test failure and before retry on an outcome-unknown create or deploy.apps verify --mode live - Local computer: run , let the user test the DEV-badged app, and deploy that development identity directly only after the user explicitly asks; never run
apps devafterapps create.apps dev
当目标是从本地工作区或托管沙箱创建或更新Notis应用时,使用本部分内容。
Notis应用是基于Vite + React的项目,使用。完成初始化或拉取并编辑后,选择对应的终端分支:本地桌面端使用流程;托管沙箱使用流程;商店提交是后续独立确认的操作。
@notis/sdkdev → build → verify → 用户批准 → deploybuild → verify → 身份/架构协调 → deploy重要提示:仅更新当前用户或团队的已安装应用工件。商店提交是独立的、需用户授权的步骤。在用户明确确认当前应用详情页和商店列表已准备就绪后,会将匹配的已部署版本提交至后端审核流程。
deployapps 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,仅执行一次并设置团队可见性和已验证的当前团队范围,验证返回的身份/范围,并关联该精确ID。在全新沙箱中,使用LOCAL_NOTIS_CREATE_APP安装Agent Browser,并通过npm exec --yes --package agent-browser@latest -- agent-browser install运行验证。通过npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify读取精确的应用ID/版本和门户URL,使用相同的组合命令运行apps list --json,并返回精确的门户URL。若测试失败,请在部署前停止;若创建或部署结果未知,请在重试前停止。apps verify --mode live - 本地计算机:运行进行实时测试,确认DEV标记的应用和根/挂载验收检查,然后运行
apps dev和apps build。让用户测试DEV应用,仅在用户明确要求后直接部署该开发身份;请勿在apps verify后运行apps dev。apps create
App development workflow
应用开发工作流
- Scaffold a new app (every published Store app is a scaffold; lists them from the public registry, and
notis apps scaffolds list [--search <term>]downloads that app's source):--from <slug>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 , increment
npm install, and editnotisAppVersion
- Local Desktop branch: run for live testing, confirm the DEV app and root/mount acceptance checks, then run
apps devandapps build. Let the user test the DEV app and stop for explicit user approval. When approved, run exactly oneapps verifyto promote the existingapps deploy(or update the already linked app), then read it back. Never rundev_app_idafterapps create.apps dev - Hosted sandbox branch: bootstrap Agent Browser as described above, then
run followed by the automated hosted
apps build. 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, reconcileapps verifyand.notis/state.jsonagainst the canonical configapps list --jsonand 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 (name) 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, runinclude_documents: falseexactly once and verify id, slug, edit permission, and personal scope. For explicit team scope, discover and describeapps create "<canonical-config-title>" . --json, 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 andLOCAL_NOTIS_CREATE_APPthat exact id. Then compare declared databases, mutate only missing/changed backward-compatible schemas with ownership proof, run exactly oneapps link, and read back id/version/Portal URL before live verify.apps deploy - 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
- 搭建新应用(所有已发布的商店应用均为脚手架;可列出公共注册表中的脚手架,
notis apps scaffolds list [--search <term>]可下载对应应用的源码):--from <slug>npx --package @notis_ai/cli@latest -- notis apps init ["My App"] [--from <slug>]
- 或拉取现有应用的源码进行编辑(项目会自动关联):
npx --package @notis_ai/cli@latest -- notis apps pull <app-id>- 然后运行,递增
npm install并进行编辑notisAppVersion
- 本地桌面端分支:运行进行实时测试,确认DEV应用和根/挂载验收检查,然后运行
apps dev和apps build。让用户测试DEV应用,等待用户明确批准。获得批准后,仅运行一次apps verify以升级现有apps deploy(或更新已关联的应用),然后读取返回结果。请勿在dev_app_id后运行apps dev。apps create - 托管沙箱分支:按上述步骤引导安装Agent Browser,然后运行,接着执行自动化托管
apps build。若选择退出自动部署,请在测试完成后停止操作,不进行应用创建/关联、数据库变更、部署或部署后检查。否则,对于新的托管应用,将apps verify和.notis/state.json与标准配置apps list --json及预期范围(默认个人;仅在明确要求时使用团队)进行协调。将开发记录视为冲突检查项。仅在元数据只读(name)的精确应用详情确认范围后,关联一个精确的可编辑非开发匹配项;若存在多个匹配/范围不匹配则失败;仅在无匹配项时创建应用。需证明配置标题标准化后等于配置名称。对于个人创建,仅运行一次include_documents: false并验证ID、slug、编辑权限和个人范围。对于明确的团队范围,需发现并描述apps create "<canonical-config-title>" . --json,试运行后仅执行一次,使用标准标题、团队可见性和已验证的当前团队范围;验证ID/slug/团队范围/编辑权限并运行LOCAL_NOTIS_CREATE_APP关联该精确ID。然后对比声明的数据库,仅对缺失/变更的向后兼容架构进行变更并验证所有权,仅运行一次apps link,在实时验证前读取返回的ID/版本/门户URL。apps deploy - 检查项目健康状态:
npx --package @notis_ai/cli@latest -- notis apps doctor
- 仅在用户明确批准当前商店预览后,提交已部署版本:
npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready
App development rules
应用开发规则
- Always before
build; rundeploybefore deploy when validating an app change.verify - Never run 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.
apps dev - 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 and include its package on the verification command's
agent-browser;PATHis not a passing automated gate.--no-browser - Never deploy a local Desktop edit until the user tests the DEV app and asks.
- Prefer for the first deploy of a project already run with
npx --package @notis_ai/cli@latest -- notis apps deploy; it promotes the development app in place.apps dev - Link before , or pass
deploywhen intentionally deploying without writing local link state.--app-id <id> - Use to diagnose configuration or dependency issues.
npx --package @notis_ai/cli@latest -- notis apps doctor - Use to discover exact slugs, permissions, versions, and Portal links before linking and after deployment; use a metadata-only (
npx --package @notis_ai/cli@latest -- notis apps list --json) exact app-detail read to prove personal/team scope without materializing databases.include_documents: false - Never treat deploy approval as Store approval. Set visibility to Team or Public first, then run 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.
apps publish --confirm-ready
- 部署前必须先执行;验证应用变更时,部署前需执行
build。verify - 请勿在托管沙箱中运行。除非明确要求仅预览、只读或不部署,否则需部署所有验证成功的沙箱应用创建或编辑结果,然后验证远程ID/版本和实时运行环境。其他应用任务不授权变更操作。
apps dev - 部署不会创建数据库。请先对比;仅实例化缺失或变更的托管应用架构,更新前需验证精确所有权。
- 在托管应用创建或数据库变更前,需先执行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 - 在关联前和部署后,使用发现精确的slug、权限、版本和门户链接;使用元数据只读(
npx --package @notis_ai/cli@latest -- notis apps list --json)的精确应用详情读取操作确认个人/团队范围,无需实例化数据库。include_documents: false - 请勿将部署批准视为商店批准。请先将可见性设置为团队或公开,仅在用户明确确认当前应用详情页和商店列表后,再运行。
apps publish --confirm-ready - 会将已部署的快照提交至与应用详情页相同的后端审核流程。若缺少确认、列表媒体不完整、本地/部署版本不匹配、可见性为私有或存在待处理审核,该命令必须拒绝提交。
apps publish --confirm-ready
App development command reference
应用开发命令参考
- -- list accessible apps
npx --package @notis_ai/cli@latest -- notis apps list - -- scaffold a new Vite + React +
npx --package @notis_ai/cli@latest -- notis apps initproject@notis/sdk - -- 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 pull <app-id> [dir] [--force] [--source-version <n>] - -- 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 dev - -- compile the production artifact
npx --package @notis_ai/cli@latest -- notis apps build - -- headless render-smoke packaged routes before deploy
npx --package @notis_ai/cli@latest -- notis apps verify - -- create a fresh remote app and optionally link the local project
npx --package @notis_ai/cli@latest -- notis apps create - -- associate the project with a remote app
npx --package @notis_ai/cli@latest -- notis apps link - -- upload the artifact and editable source snapshot to the linked installed app in Notis
npx --package @notis_ai/cli@latest -- notis apps deploy - -- deploy directly to Supabase storage, bypassing the backend server (auto-fallback when server is down)
npx --package @notis_ai/cli@latest -- notis apps deploy --direct - -- submit the matching deployed version for Team or Public Store review after explicit user confirmation
npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready - -- run project diagnostics
npx --package @notis_ai/cli@latest -- notis apps doctor
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 skill. Use for the command workflow and for the product/runtime contract.
notis-appsnotis-clinotis-apps- -- 列出可访问的应用
npx --package @notis_ai/cli@latest -- notis apps list - -- 搭建新的Vite + React +
npx --package @notis_ai/cli@latest -- notis apps init项目@notis/sdk - -- 下载已安装应用的持久化源码快照,并将本地目录关联到该应用/版本;旧版应用需先使用当前CLI重新部署一次才能被拉取
npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir] [--force] [--source-version <n>] - -- 发现本地应用,注册桌面端本地开发会话,并在Electron门户中将其加载为带DEV标记的工作区条目
npx --package @notis_ai/cli@latest -- notis apps 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 - -- 将工件和可编辑源码快照上传至Notis中已关联的已安装应用
npx --package @notis_ai/cli@latest -- notis apps deploy - -- 直接部署到Supabase存储,绕过后端服务器(服务器宕机时自动 fallback)
npx --package @notis_ai/cli@latest -- notis apps deploy --direct - -- 在用户明确确认后,提交匹配的已部署版本进行团队或公开商店审核
npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready - -- 运行项目诊断
npx --package @notis_ai/cli@latest -- notis apps doctor
应用详情页仍是可视化审核界面,并提供相同的发布/更新操作。CLI命令适用于Agent完成已获批准的提交;它不会削弱独立的确认环节。
若任务专门涉及应用结构、运行时行为或数据库/视图打包,请将本技能与技能结合使用。使用处理命令工作流,使用处理产品/运行时契约。
notis-appsnotis-clinotis-appsIMPORTANT: When NOT to use tool access for app development
重要提示:应用开发时请勿使用的工具访问方式
When building or deploying a Notis app, do NOT use for app file operations:
npx --package @notis_ai/cli@latest -- notis tools exec- Loading or saving app files -- use and
npx --package @notis_ai/cli@latest -- notis apps buildnpx --package @notis_ai/cli@latest -- notis apps deploy - Linting app files -- use which validates automatically
npx --package @notis_ai/cli@latest -- notis apps build - Managing app routes -- write standard Vite + React pages in , not raw JS files
app/
Database schemas are the exception: declaring a slug in 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.config.ts构建或部署Notis应用时,请勿使用进行应用文件操作:
npx --package @notis_ai/cli@latest -- notis tools exec- 加载或保存应用文件 -- 使用和
npx --package @notis_ai/cli@latest -- notis apps buildnpx --package @notis_ai/cli@latest -- notis apps deploy - 检查应用文件语法 -- 使用,该命令会自动进行验证
npx --package @notis_ai/cli@latest -- notis apps build - 管理应用路由 -- 在目录中编写标准Vite + React页面,而非原始JS文件
app/
数据库架构是例外:在中声明slug不会创建数据库。请使用先发现后操作的原生数据库工具工作流,在部署前创建/更新并读取每个应用所属的架构。工具调用也适用于部署后测试运行时行为。
notis.config.tsSection 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
工具访问工作流
- 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 90000npx --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 -
- 列出可用的工具包命名空间:
npx --package @notis_ai/cli@latest -- notis tools toolkits --timeout-ms 90000
- 使用自然语言搜索所需功能:
npx --package @notis_ai/cli@latest -- notis tools search "<query>" --timeout-ms 90000- 可选择添加已知字段提示:
--known-fields "<key:value>"
- 若需要,检查精确的工具和参数架构:
npx --package @notis_ai/cli@latest -- notis tools describe <tool-name> --timeout-ms 90000npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --get-schema --timeout-ms 90000
- 若工具会进行变更操作或架构较为复杂,执行前请验证参数:
npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --dry-run --arguments '<json>'
- 执行工具:
npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'
- 若需要多次独立调用,使用:
npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'
- 若工具包尚未连接,启动其连接流程:
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 for , , ,
and schema-only discovery calls. If a discovery call returns ,
retry that same command once with ; do not start a new
query, invent a tool name, or loop on the default 30-second command.
--timeout-ms 90000tools toolkitstools searchtools describenetwork_timeout--timeout-ms 90000Discovery 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秒超时时间。对于、、和仅查询架构的操作,请始终使用参数。若发现调用返回,请使用参数重试一次该命令;请勿发起新查询、自行编造工具名称或循环使用默认30秒超时的命令。
tools toolkitstools searchtools describe--timeout-ms 90000network_timeout--timeout-ms 90000发现操作是幂等的,但应加以限制:每个任务运行一次工具包列表查询,每个不同功能运行一次自然语言搜索,并将返回的标准工具名称和架构缓存至当前会话结束。成功获取搜索/架构响应后,请直接调用返回的标准工具(变更操作前先试运行),而非在每次连接服务操作前重复相同的发现请求。
Tool access rules
工具访问规则
- Never guess tool names. Discover them with first.
npx --package @notis_ai/cli@latest -- notis tools search - Prefer first-class CLI commands when they exist, but use whenever the capability is not covered by a dedicated command.
npx --package @notis_ai/cli@latest -- notis tools ... - When you know the tool name but not the argument shape, use or
npx --package @notis_ai/cli@latest -- notis tools describebefore execution.--get-schema - Use before mutating calls when you want schema validation without execution.
--dry-run - If a toolkit is missing, use to start the connection flow.
npx --package @notis_ai/cli@latest -- notis tools link <toolkit> - Use to replace an existing connection. If multiple accounts exist, select one with
--reconnect.--connection-id <id> - For API keys, basic auth, or other credential JSON, prefer and pipe or redirect stdin. Avoid inline secrets because they can enter shell history and process listings.
--credentials -
- 请勿猜测工具名称。请先使用发现工具。
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,优先使用并通过管道或重定向标准输入传入。避免在命令中直接输入密钥,因为它们可能会被记录到Shell历史和进程列表中。
--credentials -
Toolkit mental model
工具包思维模型
Typical toolkit namespaces include:
- for native Notis tools
notis - for Composio-backed integrations
composio-* - for MCP-backed tools
mcp-*
The pattern is:
- discover toolkits
- search tools
- inspect schema if needed
- execute the canonical tool
典型的工具包命名空间包括:
- :原生Notis工具
notis - :Composio支持的集成
composio-* - :MCP支持的工具
mcp-*
流程模式为:
- 发现工具包
- 搜索工具
- 若需要,检查架构
- 执行标准工具
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-schemaDry-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 githubReconnect 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.jsonNative database access
原生数据库访问
Native Notis databases are accessed through the generic tool workflow, not a first-class database command group. Use these canonical tool names:
- -- list databases accessible to the current profile
LOCAL_NOTIS_DATABASE_LIST_DATABASES - -- inspect read-only metadata and schema detail
LOCAL_NOTIS_DATABASE_GET_DATABASE - -- query documents from a database
LOCAL_NOTIS_DATABASE_QUERY - -- create or update a database schema. Every database belongs to a Notis app: creation requires the owning app's slug or id in the
LOCAL_NOTIS_DATABASE_UPSERT_DATABASEargument (create the app first withappif needed)LOCAL_NOTIS_CREATE_APP
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 or returns a database ID, prefer for ; remains supported as a fallback.
LOCAL_NOTIS_DATABASE_LIST_DATABASESLOCAL_NOTIS_DATABASE_GET_DATABASEdatabase_idLOCAL_NOTIS_DATABASE_QUERYdatabase_slug原生Notis数据库通过通用工具工作流访问,而非原生数据库命令组。请使用以下标准工具名称:
- -- 列出当前配置文件可访问的数据库
LOCAL_NOTIS_DATABASE_LIST_DATABASES - -- 检查只读元数据和架构细节
LOCAL_NOTIS_DATABASE_GET_DATABASE - -- 查询数据库中的文档
LOCAL_NOTIS_DATABASE_QUERY - -- 创建或更新数据库架构。每个数据库都属于一个Notis应用:创建时需在
LOCAL_NOTIS_DATABASE_UPSERT_DATABASE参数中指定所属应用的slug或ID(若需要,请先使用app创建应用)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}}'当或返回数据库ID时,在中优先使用;仍作为 fallback 被支持。
LOCAL_NOTIS_DATABASE_LIST_DATABASESLOCAL_NOTIS_DATABASE_GET_DATABASELOCAL_NOTIS_DATABASE_QUERYdatabase_iddatabase_slugSupporting commands
支持命令
- — confirm which account and endpoint a command will target
npx --package @notis_ai/cli@latest -- notis whoami - — verify CLI config, auth, routing, and API reachability before relying on the CLI
npx --package @notis_ai/cli@latest -- notis doctor - — get the exact command contract for first-class CLI commands
npx --package @notis_ai/cli@latest -- notis describe <command...>
- — 确认命令将访问的账号和端点
npx --package @notis_ai/cli@latest -- notis whoami - — 在依赖CLI前验证CLI配置、认证、路由和API可达性
npx --package @notis_ai/cli@latest -- notis doctor - — 获取原生CLI命令的精确命令契约
npx --package @notis_ai/cli@latest -- notis describe <command...>
Summary
总结
Use for two things:
notis-cli- 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.
notis-cli- 通过进行本地应用开发
npx --package @notis_ai/cli@latest -- notis apps ... - 通过进行工具发现与执行
npx --package @notis_ai/cli@latest -- notis tools ...
最重要的是:若当前没有所需工具,尤其是在直接使用MCP或集成工作时,请使用Notis CLI,而非认为任务无法完成。
Troubleshooting
故障排除
CLI returns auth_expired
or auth_missing
auth_expiredauth_missingCLI返回auth_expired
或auth_missing
auth_expiredauth_missingThe profile's browser authorization has lapsed or was never granted. Run
(add 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.
notis login--profile <name>If the profile is a one, the fix is to restart in the
workspace it belongs to, or to switch to a real account profile.
dev-*./dev.sh配置文件的浏览器授权已过期或从未授予。运行(若失败的配置文件不是当前激活的,请添加参数),并让用户在浏览器中批准授权请求。在JSON/Agent模式下,第一个提示就是要运行的精确命令。请勿将刷新令牌复制到命令中,也不要尝试自行生成凭据。
notis login--profile <name>若配置文件是类型,请重启其所属工作目录中的,或切换到真实账号配置文件。
dev-*./dev.shDeploy fails with "network_error" or "fetch failed"
部署失败,返回"network_error"或"fetch failed"
The CLI defaults to the live Notis API (, or
when the signed-in user is on beta). Solutions:
https://api.notis.aihttps://api-beta.notis.ai- Run and confirm
npx --package @notis_ai/cli@latest -- notis doctoris a live Notis hostapi_base - Use for app deploys when you only need Supabase storage upload:
--directnpx --package @notis_ai/cli@latest -- notis apps deploy --direct - If auth looks stale, run and retry
npx --package @notis_ai/cli@latest -- notis login
Localhost backends are a Notis-developer test lane only. Do not retarget the CLI at loopback from this skill — that path is owned by , which exposes its own lease-backed profile.
./dev.shdev-*CLI默认指向Notis生产API(,若登录用户为测试版用户则指向)。解决方案:
https://api.notis.aihttps://api-beta.notis.ai- 运行,确认
npx --package @notis_ai/cli@latest -- notis doctor是有效的Notis主机api_base - 若仅需上传到Supabase存储,请在应用部署时使用参数:
--directnpx --package @notis_ai/cli@latest -- notis apps deploy --direct - 若认证信息看起来已过期,请运行并重试
npx --package @notis_ai/cli@latest -- notis login
本地后端仅为Notis开发者测试通道。请勿通过本技能将CLI重定向到回环地址 — 该路径由管理,它会暴露自己的基于租赁的配置文件。
./dev.shdev-*npx --package @notis_ai/cli@latest -- notis doctor
shows health/tool_roundtrip errors
npx --package @notis_ai/cli@latest -- notis doctornpx --package @notis_ai/cli@latest -- notis doctor
显示health/tool_roundtrip错误
npx --package @notis_ai/cli@latest -- notis doctorThe CLI health check pings the configured live API. App development commands that are (, , , , ) work offline. , , , , and normal need the live API; can bypass it when Supabase credentials are available.
backend_call: localinitbuildverifylinkdoctordevpullcreatelistdeploydeploy --directCLI健康检查会 ping 配置的生产API。的应用开发命令(、、、、)可离线工作。、、、和常规需要生产API;当Supabase凭据可用时,可绕过API。
backend_call: localinitbuildverifylinkdoctordevpullcreatelistdeploydeploy --directStale 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
门户会按版本缓存应用包。若重新部署到同一版本,门户可能会提供缓存的旧包。解决方案:
- 强制刷新门户页面(Cmd+Shift+R)
- 打开浏览器开发者工具 > 应用 > 存储 > 清除站点数据
- 包缓存键包含版本号 — 递增版本号会强制加载新包