@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 +30 -8
- package/README.zh-CN.md +28 -6
- package/llms-install.md +17 -5
- package/package.json +2 -2
- package/skills/sandbase/SKILL.md +50 -8
package/README.md
CHANGED
|
@@ -22,11 +22,17 @@
|
|
|
22
22
|
|
|
23
23
|
---
|
|
24
24
|
|
|
25
|
-
|
|
25
|
+
## Start here
|
|
26
26
|
|
|
27
|
-
**
|
|
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
|
-
|
|
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)** —
|
|
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
|
|
187
|
-
| **Image Gen** |
|
|
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
|
|
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
|
-
- **
|
|
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
|
-
|
|
25
|
+
## 从这里开始
|
|
26
26
|
|
|
27
|
-
**
|
|
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)** —
|
|
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
|
|
103
|
-
| **图像生成** |
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 `
|
|
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.
|
|
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.
|
|
66
|
+
"smol-toml": "1.9.1",
|
|
67
67
|
"yaml": "2.9.0"
|
|
68
68
|
}
|
|
69
69
|
}
|
package/skills/sandbase/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sandbase
|
|
3
|
-
version: 0.3.
|
|
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
|
|
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
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
|