@sandbaseai/cli 0.3.8 → 0.3.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,11 +22,17 @@
22
22
 
23
23
  ---
24
24
 
25
- Your AI coding assistant is smart, but it's trapped in a box. It can't search the web, check social media, generate images, or access real-time data — unless you wire up each API yourself.
25
+ ## Start here
26
26
 
27
- **SandBase changes that.** One command connects your agent to 2,000+ AI models and APIs through the [Model Context Protocol](https://modelcontextprotocol.io). No API keys to manage. No configuration headaches.
27
+ Requires **Node.js 20 or newer**. Use CLI / MCP to connect your AI tools, or discover and call APIs directly from your terminal.
28
28
 
29
- Building directly over HTTP instead of MCP? Start with the [SandBase API quickstart](https://www.sandbase.ai/docs/getting-started/)
29
+ - **Website, API or agent setup**: [Quick Start](https://www.sandbase.ai/docs/getting-started/quickstart).
30
+ - **Python, TypeScript, Go and HTTP examples**: [SandBase SDK and catalog repository](https://github.com/sandbaseai/sandbase).
31
+ - **Reusable workflows and browser utilities**: [Skills](https://www.sandbase.ai/skills) · [Tools](https://www.sandbase.ai/tools).
32
+
33
+ Connect your AI assistant to SandBase models and data APIs through the [Model Context Protocol](https://modelcontextprotocol.io). Search, work with social data, and generate media using one SandBase connection, without separate provider accounts.
34
+
35
+ Building directly over HTTP instead of MCP? Start with the [SandBase API quickstart](https://www.sandbase.ai/docs/getting-started/quickstart)
30
36
  or compare the unified [LLM, image, and video API](https://blog.sandbase.ai/unified-ai-api-llm-image-video-2026/)
31
37
  with specialized model gateways.
32
38
 
@@ -106,7 +112,7 @@ AI agents and automated installers can use the concise
106
112
  ## SandBase Open-Source Stack
107
113
 
108
114
  - **[SandBase Harness](https://github.com/sandbaseai/sandbase-harness)** — self-hosted agent runtime with persistent sessions, sandbox isolation, approvals, audit, and replay.
109
- - **[SandBase Agent Skills](https://github.com/sandbaseai/sandbase-skills)** — 88 installable Skills for research, social intelligence, marketing, and business workflows.
115
+ - **[SandBase Agent Skills](https://github.com/sandbaseai/sandbase-skills)** — installable Skills for research, social intelligence, marketing, and business workflows.
110
116
  - **[SandBase for Codex](https://github.com/sandbaseai/sandbase-codex-plugin)** — official Codex plugin packaging the SandBase MCP bridge and guided Agent Skill; its required HOL security scan passes on `main`.
111
117
 
112
118
  Discover the authenticated remote bridge in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.sandbaseai%2Fcli),
@@ -183,8 +189,8 @@ catalog example, read the [GitHub connector discover-and-inspect dogfooding note
183
189
  | **Web Search** | Google, Exa, Tavily, Scholar | Research anything in real-time |
184
190
  | **Social Media** | Twitter/X, YouTube, Reddit, Instagram, TikTok, Xiaohongshu, Weibo, Bilibili | Monitor trends, pull posts, analyze content |
185
191
  | **Scraping** | Firecrawl, Exa Content | Extract data from any public webpage |
186
- | **AI Models** | GPT-4o, Claude, Gemini, DeepSeek, Qwen, Llama | Run any model without managing keys |
187
- | **Image Gen** | Flux, DALL-E, Ideogram, Recraft | Create logos, illustrations, mockups |
192
+ | **AI Models** | GPT, Claude, Gemini, DeepSeek, Qwen, Llama | Run any model without managing keys |
193
+ | **Image Gen** | GPT Image, FLUX, Seedream, Ideogram | Create logos, illustrations, mockups |
188
194
  | **Video Gen** | Kling, MiniMax, Runway, Luma | Generate short clips and animations |
189
195
  | **Audio** | ElevenLabs, Whisper | Text-to-speech, transcription |
190
196
  | **E-commerce** | Taobao, Amazon | Product research, price comparison |
@@ -289,6 +295,21 @@ The integration is independently listed by
289
295
 
290
296
  ---
291
297
 
298
+ ## Install, upgrade and troubleshoot
299
+
300
+ A one-off `npx ... connect` does not permanently install the `sandbase` command. Prefix subsequent commands with `npx -y @sandbaseai/cli@latest`, or install it globally:
301
+
302
+ ```sh
303
+ npm install -g @sandbaseai/cli@latest
304
+ sandbase connect
305
+ sandbase discover -q "Twitter posts" -t api
306
+ sandbase inspect sandbase_twitter_web_search_timeline
307
+ ```
308
+
309
+ Discovery and inspection do not start billable work. Review the inputs and current price before using `sandbase run`. Upgrade through the same method you installed with: npm users can repeat the install command above; Homebrew users run `brew update`, then `brew upgrade sandbaseai/tap/sandbaseai-cli`. Avoid mixing both installation methods.
310
+
311
+ After upgrading, run `sandbase setup` and `sandbase doctor --client <client-id>`, then restart your AI client or open a new session. Complete any requested sign-in in your browser. Without a local AI client, obtain an [API key](https://www.sandbase.ai/console/keys), supply it as `SANDBASE_API_KEY`, and use terminal commands directly. Keep the run ID for async work and resume with `sandbase runs get -r <run_id> -w` instead of submitting it again.
312
+
292
313
  ## Commands
293
314
 
294
315
  ### CLI Commands
@@ -312,7 +333,8 @@ sandbase run sandbase_twitter_web_search_timeline -i '{"keyword":"AI agents"}'
312
333
  sandbase run <video_tool> -i '{"prompt":"..."}' -w -o result.json # wait with backoff, save output to disk
313
334
  sandbase runs get -r <run_id> -w -o result.json # resume a long run instead of re-running it
314
335
  sandbase upload ./photo.png # local image/audio/video -> public URL for tools that take a URL
315
- sandbase runs list | sandbase balance
336
+ sandbase runs list
337
+ sandbase balance
316
338
  ```
317
339
 
318
340
  `-j` prints JSON; errors are `{"error":{"code","message","hint"}}` with the next step in `hint`. Exit codes: `0` success or still running, `1` failure (including a failed run), `2` usage.
@@ -347,7 +369,7 @@ discover → inspect → run
347
369
 
348
370
  ## Security
349
371
 
350
- - **Zero secrets in URLs or CLI args** — OAuth device flow with PKCE
372
+ - **Browser authorization without pasting keys** — The `connect` flow uses PKCE; manual `keys add -k` places the key in shell history, so prefer `connect` or a securely supplied environment variable
351
373
  - **Restricted file permissions** — Credentials stored with `0600`
352
374
  - **Ownership-aware updates** — Existing JSONC comments and user-managed MCP entries are preserved
353
375
  - **Exact rollback** — On failure or `unregister`, only configuration owned by SandBase is removed
package/README.zh-CN.md CHANGED
@@ -22,9 +22,15 @@
22
22
 
23
23
  ---
24
24
 
25
- 你的 AI 编程助手很聪明,但它被困在一个盒子里。它不能搜索网页、查看社交媒体、生成图片、或获取实时数据 — 除非你自己逐个对接每个 API。
25
+ ## 从这里开始
26
26
 
27
- **SandBase 改变了这一切。** 一行命令,通过 [Model Context Protocol](https://modelcontextprotocol.io) 将你的 Agent 连接到 2,000+ AI 模型与 API。不用管理 API Key,不用折腾配置。
27
+ 需要 **Node.js 20 或更新版本**。CLI / MCP 用于把 SandBase 接入本地 AI 工具,也可以直接在终端发现和调用 API。
28
+
29
+ - **平台使用、API 调用、Agent 接入**:[Quick Start](https://www.sandbase.ai/docs/getting-started/quickstart)。
30
+ - **Python、TypeScript、Go 与 HTTP 示例**:[SandBase SDK 与目录仓库](https://github.com/sandbaseai/sandbase)。
31
+ - **可复用工作流与网页工具**:[Skills](https://www.sandbase.ai/skills) · [Tools](https://www.sandbase.ai/tools)。
32
+
33
+ 通过 [Model Context Protocol](https://modelcontextprotocol.io) 将 AI 助手连接到 SandBase 的模型和数据 API。一套连接即可搜索网页、处理社媒数据和生成媒体,无需分别注册上游服务。
28
34
 
29
35
  把这一行发给你的 agent,它会自己读取 Skill、运行 `connect`,只需你在浏览器里确认一次登录:
30
36
 
@@ -68,7 +74,7 @@ npx -y @sandbaseai/cli@latest catalog --json
68
74
  ## SandBase 开源技术栈
69
75
 
70
76
  - **[SandBase Harness](https://github.com/sandbaseai/sandbase-harness)** — 自托管 Agent Runtime,提供持久会话、沙箱隔离、审批、审计与回放。
71
- - **[SandBase Agent Skills](https://github.com/sandbaseai/sandbase-skills)** — 88 个可安装 Skills,覆盖研究、社交情报、营销和商业工作流。
77
+ - **[SandBase Agent Skills](https://github.com/sandbaseai/sandbase-skills)** — 可安装 Skills,覆盖研究、社交情报、营销和商业工作流。
72
78
  - **[SandBase for Codex](https://github.com/sandbaseai/sandbase-codex-plugin)** — 官方 Codex 插件,封装 SandBase MCP 桥接器和引导式 Agent Skill。
73
79
 
74
80
  ---
@@ -99,8 +105,8 @@ npx -y @sandbaseai/cli@latest catalog --json
99
105
  | **网页搜索** | Google、Exa、Tavily、Scholar | 实时搜索任何信息 |
100
106
  | **社交媒体** | Twitter/X、YouTube、Reddit、Instagram、TikTok、小红书、微博、B站 | 监控趋势、获取帖子、分析内容 |
101
107
  | **网页抓取** | Firecrawl、Exa Content | 从任何公开网页提取数据 |
102
- | **AI 模型** | GPT-4o、Claude、Gemini、DeepSeek、Qwen、Llama | 调用任何模型,无需自己管 Key |
103
- | **图像生成** | Flux、DALL-E、Ideogram、Recraft | Logo、插画、原型图 |
108
+ | **AI 模型** | GPT、Claude、Gemini、DeepSeek、Qwen、Llama | 调用任何模型,无需自己管 Key |
109
+ | **图像生成** | GPT Image、FLUX、Seedream、Ideogram | Logo、插画、原型图 |
104
110
  | **视频生成** | Kling、MiniMax、Runway、Luma | 短视频、动画 |
105
111
  | **音频** | ElevenLabs、Whisper | 文字转语音、语音转文字 |
106
112
  | **电商** | 淘宝、Amazon | 选品调研、价格对比 |
@@ -210,6 +216,21 @@ npx -y @sandbaseai/cli@latest unregister --client hermes
210
216
 
211
217
  `sandbase inspect <工具名>` 会显示当前价格,适用每日免费额度的数据 API 会带有 `pricing.free_quota`;`sandbase balance --json` 的 `free_api_quota` 显示今天剩余的免费次数。价格可能变动,请以实时返回为准。
212
218
 
219
+ ## 安装、升级与排错
220
+
221
+ 仅运行一次 `npx ... connect` 不会永久安装 `sandbase` 命令。后续命令也可以加上 `npx -y @sandbaseai/cli@latest` 前缀,或者安装到本地:
222
+
223
+ ```sh
224
+ npm install -g @sandbaseai/cli@latest
225
+ sandbase connect
226
+ sandbase discover -q "Twitter posts" -t api
227
+ sandbase inspect sandbase_twitter_web_search_timeline
228
+ ```
229
+
230
+ 发现和检查不会启动付费任务。确认输入与当前价格后再执行 `sandbase run`。请按安装方式升级:npm 用户重新运行上面的安装命令;Homebrew 用户运行 `brew update` 后执行 `brew upgrade sandbaseai/tap/sandbaseai-cli`,不要混用两种安装方式。
231
+
232
+ 升级后运行 `sandbase setup`、`sandbase doctor --client <client-id>`,再重启 AI 客户端或新开会话。需要登录时由你在浏览器中确认;没有本地 AI 客户端时,可使用 [API Key](https://www.sandbase.ai/console/keys) 配置 `SANDBASE_API_KEY`,直接运行终端命令。异步任务保留 run ID,用 `sandbase runs get -r <run_id> -w` 继续查询,避免重复执行。
233
+
213
234
  ## 命令
214
235
 
215
236
  ### CLI 命令
@@ -232,7 +253,8 @@ sandbase inspect sandbase_twitter_web_search_timeline # 参数、价格、
232
253
  sandbase run sandbase_twitter_web_search_timeline -i '{"keyword":"AI agents"}'
233
254
  sandbase run <视频工具> -i '{"prompt":"..."}' -w -o result.json # 带退避等待完成,结果写入文件
234
255
  sandbase runs get -r <run_id> -w -o result.json # 续查长任务,不要重新运行
235
- sandbase runs list | sandbase balance
256
+ sandbase runs list
257
+ sandbase balance
236
258
  ```
237
259
 
238
260
  `-j` 输出 JSON;错误格式为 `{"error":{"code","message","hint"}}`,`hint` 给出下一步。退出码:`0` 成功或仍在运行,`1` 失败(含任务失败),`2` 参数错误。
package/llms-install.md CHANGED
@@ -8,7 +8,7 @@ requiring separate provider API keys.
8
8
 
9
9
  - Node.js 20 or newer
10
10
  - A graphical browser for the one-time authorization flow
11
- - A supported client from the catalog below
11
+ - A supported AI client for MCP setup, or a SandBase API key for standalone terminal use
12
12
 
13
13
  ## Verify before installing
14
14
 
@@ -34,8 +34,7 @@ SHA-256 before installation.
34
34
 
35
35
  ## Connect a client
36
36
 
37
- Alternatively, run the latest GitHub Release directly while npm
38
- `latest` is being updated:
37
+ Alternatively, run the published npm CLI without a global installation:
39
38
 
40
39
  ```sh
41
40
  npx -y @sandbaseai/cli@latest connect --client <client-id>
@@ -60,9 +59,9 @@ npx -y @sandbaseai/cli@latest doctor --client <client-id>
60
59
  ```
61
60
 
62
61
  Restart the target client after a successful connection so it reloads its MCP
63
- configuration. The client should then expose six SandBase tools:
62
+ configuration. The client should then expose these SandBase tools:
64
63
  `sandbase_discover`, `sandbase_inspect`, `sandbase_run`, `sandbase_run_get`,
65
- `sandbase_runs`, and `sandbase_account`.
64
+ `sandbase_runs`, `sandbase_account`, and `sandbase_run_cancel` (Agent Service runs only).
66
65
 
67
66
  ## Remove the managed entry
68
67
 
@@ -74,3 +73,16 @@ This removes only the SandBase-owned configuration. It leaves unrelated and
74
73
  user-managed MCP entries unchanged.
75
74
 
76
75
  Source: https://github.com/sandbaseai/cli
76
+
77
+ ## Use the terminal directly
78
+
79
+ `npx` does not permanently install the executable. Continue using the full prefix:
80
+
81
+ ```sh
82
+ npx -y @sandbaseai/cli@latest discover -q "Twitter posts" -t api
83
+ npx -y @sandbaseai/cli@latest inspect sandbase_twitter_web_search_timeline
84
+ ```
85
+
86
+ These commands inspect the catalog without starting a run. Review current inputs and prices before executing work. To get a persistent `sandbase` command, install with `npm install -g @sandbaseai/cli@latest` or Homebrew. Do not mix installation methods. After an upgrade, run `sandbase setup`, then `sandbase doctor --client <client-id>` and restart your client.
87
+
88
+ For website, API and agent instructions, use [Quick Start](https://www.sandbase.ai/docs/getting-started/quickstart). SDKs and HTTP examples live in [sandbaseai/sandbase](https://github.com/sandbaseai/sandbase).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sandbaseai/cli",
3
- "version": "0.3.8",
3
+ "version": "0.3.11",
4
4
  "mcpName": "io.github.sandbaseai/cli",
5
5
  "description": "Give 25 AI clients—Claude Code, Codex, Cursor, Hermes, OpenClaw and more—2,000+ models and APIs through one MCP server and an agent-friendly CLI",
6
6
  "type": "module",
@@ -63,7 +63,7 @@
63
63
  },
64
64
  "dependencies": {
65
65
  "jsonc-parser": "3.3.1",
66
- "smol-toml": "1.7.0",
66
+ "smol-toml": "1.9.1",
67
67
  "yaml": "2.9.0"
68
68
  }
69
69
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sandbase
3
- version: 0.3.8
3
+ version: 0.3.11
4
4
  description: >-
5
5
  Discover better ways to complete tasks. Proactively search SandBase (the
6
6
  sandbase_discover MCP tool, or `sandbase discover` in a shell) before writing a
@@ -27,9 +27,54 @@ There are **two transports** with the same capabilities. Pick one before doing a
27
27
 
28
28
  ---
29
29
 
30
+ ## Quick start: from setup to a working feature
31
+
32
+ For a person reading this file: paste `set up https://www.sandbase.ai/SKILL.md` into **your AI assistant's chat**, then describe what you want to build or share the SandBase API page you are looking at. This sentence is not a terminal command. Do not paste your API key into chat. [Quickstart for people and agents](https://www.sandbase.ai/quickstart.md) complements the [existing onboarding guide](https://www.sandbase.ai/docs/getting-started/quickstart).
33
+
34
+ For the agent: use the user's language and carry their requested task through setup, implementation, and verification. A request to set up SandBase alone does not authorize an invented project or a billed demo. If the goal is missing, ask one focused question: “What would you like to build or what data do you need?” Reuse information already supplied.
35
+
36
+ ### Start from the user's current situation
37
+
38
+ | Situation | What to do |
39
+ |---|---|
40
+ | No account yet | Follow §0 for a supported client with a shell; the user completes browser sign-in. First login creates a personal workspace. A team is optional, not a prerequisite. If shell access is unavailable, use the client-specific [setup guide](https://www.sandbase.ai/console/setup). |
41
+ | Account exists, no key | AI-tool browser authorization in §0 does not require a key pasted into chat. For direct HTTP code, guide the user to [API Keys](https://www.sandbase.ai/console/keys) in their intended workspace and store the key locally as `SANDBASE_API_KEY`. |
42
+ | Key already created | Reuse an existing configured environment or credential store without printing its contents. Do not create another key or force a new organization. Creating a key alone does not install tools or implement an integration. |
43
+ | SandBase tools already available | Use §1 to choose the existing MCP or CLI connection. Verify discovery/inspection works before claiming tools are usable; do not reinstall a working connection. A working CLI does not prove MCP is loaded in the client's current session. |
44
+ | An existing app or repository | Inspect its framework, commands, API layer, and local instructions. Add the requested integration using its conventions; do not replace the project with a new template. |
45
+ | A new feature with no project | Establish the intended result and target environment, then build the smallest runnable implementation. If the user only wants a data result, return that result without creating an app. |
46
+ | A specific API page or platform | Preserve that URL and task. Discover the matching tool and inspect its live schema/price. A vendor directory such as Similarweb is a list of choices, not one callable endpoint. Ask only for missing inputs such as domain, period, or desired metric. |
47
+ | Direct HTTP rather than AI tools | Keep that choice. Use the selected endpoint's API documentation for its exact method, path, authentication, parameters, and response. MCP installation is not required for HTTP integration. |
48
+ | Browser-only use or a hosted Agent | Follow the corresponding path in the onboarding guide: try a request on the website, or create a hosted Agent when that is the user's goal. Installing this Skill does not itself create a hosted Agent. |
49
+
50
+ Before authorization or a billed run, establish which workspace the user intends to use. Keys, balance, and usage belong to that workspace. Do not create a team, invite people, change billing, or switch accounts merely to complete setup. If a client cannot execute commands or load tools, explain the limitation and provide its supported setup path; do not claim the feature can run there.
51
+
52
+ ### Continue from connection to development
53
+
54
+ 1. **Clarify the deliverable.** Reuse the user's task and API URL. Ask for information that blocks implementation, not a full onboarding questionnaire. If only setup was requested, verify the connection and report readiness for a chosen task.
55
+ 2. **Connect only when needed.** Use §0–§3. Let the user complete browser authorization; never request passwords or keys in chat. Explain any required new client session. Continue with the working CLI when available rather than claiming unavailable MCP tools work.
56
+ 3. **Select and inspect.** Discover the relevant model/API, then inspect its actual input schema, price, and execution template. Explain the chosen capability and applicable cost. Do not assume every API has free quota, invent a request route, or treat a provider's native fields as SandBase fields.
57
+ 4. **Implement the requested feature.** Put calls behind the existing server/API layer or in a local script, with secrets in the local environment or secret store. Keep keys out of browser bundles, source control, logs, and generated examples. Include input validation, timeouts, and useful error messages. Poll async jobs according to §2–§3 instead of starting duplicate runs.
58
+ 5. **Verify one bounded request when authorized.** Use the user's task and budget; obtain missing paid-call authorization when needed. Discovery and inspection are free and sufficient to check those operations, but are not proof that a data/model call succeeds. If live testing is unavailable, finish useful implementation and offline checks, and identify the remaining live check explicitly.
59
+ 6. **Finish the user flow.** Connect the real response to the requested output: a saved file, script result, or app view. Handle loading, empty results, and failure where applicable. Inspect actual response fields; do not present a guessed schema or mock data as a live result.
60
+ 7. **Hand over something runnable.** Give the start/run command, where to configure credentials without showing their value, the files changed, what was tested, and the next action if anything remains blocked. Deploy or publish only when requested.
61
+
62
+ ### What counts as success
63
+
64
+ Report these states separately:
65
+
66
+ - **Configured:** authorization/configuration completed for the intended client/workspace; a restart or client readback may still be needed.
67
+ - **Tools usable:** a discovery/inspection operation succeeded through the transport actually in use.
68
+ - **First call verified:** the selected business request reached a successful terminal status and its actual output was checked. A run ID, HTTP 200 with an embedded error, or an empty dataset is not proof of the requested result.
69
+ - **Feature working:** the requested script/app path runs with the integration and its relevant error handling checked. If only offline tests passed, say so.
70
+
71
+ For example, when a user says “I have a key and want Similarweb website traffic,” keep that context, establish their domain and desired period/metric, inspect an appropriate Similarweb endpoint, and implement the requested script or app feature. Do not make them create another key, silently run a paid example, or stop at sending them another documentation link.
72
+
73
+ ---
74
+
30
75
  ## 0. Set up
31
76
 
32
- Do this when the user asks you to set up SandBase (for example "set up https://www.sandbase.ai/SKILL.md"), or when §1 finds neither transport. You run the steps yourself; the user only approves a sign-in in their browser.
77
+ Do this when setup is needed after checking the user's existing connection in §1. With shell access, run the steps yourself; the user completes sign-in in their browser. Without a shell, follow the client-specific setup guide instead of attempting terminal commands or claiming installation succeeded.
33
78
 
34
79
  1. Check Node.js 20 or newer: `node --version`. If it is missing or older, ask the user to install it from https://nodejs.org and stop.
35
80
  2. Connect this client. Run in a shell, with your client id:
@@ -38,7 +83,7 @@ Do this when the user asks you to set up SandBase (for example "set up https://w
38
83
  npx -y @sandbaseai/cli@latest connect --client <client-id>
39
84
  ```
40
85
 
41
- Client ids: `claude-code`, `codex`, `cursor`, `windsurf`, `kiro`, `kiro-cli`, `gemini-cli`, `opencode`, `qwen-code`, `warp`, `cursor-cli`, `kimi-cli`, `amp`, `crush`, `hermes`, `openclaw`, `iflow-cli`, `antigravity`, `trae`, `qoder`, `workbuddy`, `pi`, `claude-desktop`, `cowork`, `chatgpt`. If you are not sure which one you are, omit `--client` to configure every installed client.
86
+ Client ids: `claude-code`, `codex`, `cursor`, `windsurf`, `kiro`, `kiro-cli`, `gemini-cli`, `opencode`, `qwen-code`, `warp`, `cursor-cli`, `kimi-cli`, `amp`, `crush`, `hermes`, `openclaw`, `iflow-cli`, `antigravity`, `trae`, `qoder`, `workbuddy`, `pi`, `claude-desktop`, `cowork`, `chatgpt`. If you are not sure which client the user wants to connect, ask which app they are using. Keep `--client` scoped to that app; configure all installed clients only when requested.
42
87
  - It opens the browser for sign-in (new users get an account in the same step). Tell the user to approve it. If there is no browser, it prints a URL — show that URL to the user.
43
88
  - It waits for the approval, so give the command a timeout of at least 5 minutes. If your shell cannot wait that long, ask the user to run the same command in their own terminal.
44
89
  - Never ask the user to paste an API key into the chat.
@@ -108,12 +153,9 @@ sandbase --version || npx -y @sandbaseai/cli@latest --version
108
153
 
109
154
  If `sandbase` is not installed, prefix every command with `npx -y @sandbaseai/cli@latest` (or install it: `npm install -g @sandbaseai/cli@latest`).
110
155
 
111
- **Keep the CLI and this Skill on the same version.** Run `npx -y @sandbaseai/cli@latest setup` (it refreshes the CLI's MCP bridge and this Skill) when any of these is true:
112
-
113
- - The CLI prints "Update available".
114
- - `sandbase --version` does not match the `version` at the top of this file.
156
+ **Update without looping.** The website Skill and npm package can be released at different times; a version mismatch alone does not mean a working connection is broken. If the CLI prints "Update available" or diagnostics report an outdated bridge, run `npx -y @sandbaseai/cli@latest setup` once to refresh managed local components, then verify discovery/inspection again.
115
157
 
116
- Always move both to the latest; never downgrade one to match the other. If they still differ after `setup`, save the latest copy from https://www.sandbase.ai/SKILL.md over this file.
158
+ Do not repeatedly run setup to make version labels match, downgrade a newer Skill, or overwrite user edits. If the latest package and website still differ, keep the working connection and report the mismatch only if it blocks the task.
117
159
 
118
160
  **Authentication** is automatic once the user has run `connect` (it reuses that browser sign-in). Otherwise the CLI reports `AUTH_REQUIRED` with the exact fix; an API key also works via `SANDBASE_API_KEY` or `sandbase keys add -k <key>`. Never ask the user to paste a key into the chat.
119
161