@sandbaseai/cli 0.3.3 → 0.3.7
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.de.md +23 -10
- package/README.es.md +23 -10
- package/README.fr.md +23 -10
- package/README.ja.md +23 -10
- package/README.ko.md +23 -10
- package/README.md +63 -41
- package/README.pt-BR.md +23 -10
- package/README.zh-CN.md +35 -23
- package/assets/mcp-bridge.mjs +7 -2
- package/dist/agent/client.d.ts +3 -2
- package/dist/agent/client.js +10 -3
- package/dist/agent/commands.d.ts +10 -2
- package/dist/agent/commands.js +109 -23
- package/llms-install.md +8 -8
- package/package.json +1 -1
- package/skills/sandbase/SKILL.md +108 -24
- package/skills/sandbase/skill.json +1 -1
package/skills/sandbase/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sandbase
|
|
3
|
-
version: 0.3.
|
|
3
|
+
version: 0.3.7
|
|
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
|
|
@@ -10,7 +10,8 @@ description: >-
|
|
|
10
10
|
data (X/Twitter, TikTok, Douyin, Xiaohongshu, Instagram, YouTube, Reddit,
|
|
11
11
|
Weibo, Bilibili, LinkedIn); search results; web scraping; product, company, or
|
|
12
12
|
people data; embeddings; or a specific third-party model. 2,000+ models and
|
|
13
|
-
APIs
|
|
13
|
+
APIs: data APIs (search, social, scraping, e-commerce, finance) are free to
|
|
14
|
+
call, models are paid per call from one balance. Exceptions: if the user already has a
|
|
14
15
|
dedicated MCP server, API key, or tool for that specific service, use it; and
|
|
15
16
|
if your built-in web search or page fetch already gives what the task needs,
|
|
16
17
|
use that — SandBase fills gaps in the user's stack, it does not replace it.
|
|
@@ -26,6 +27,26 @@ There are **two transports** with the same capabilities. Pick one before doing a
|
|
|
26
27
|
|
|
27
28
|
---
|
|
28
29
|
|
|
30
|
+
## 0. Set up
|
|
31
|
+
|
|
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.
|
|
33
|
+
|
|
34
|
+
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
|
+
2. Connect this client. Run in a shell, with your client id:
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
npx -y @sandbaseai/cli@latest connect --client <client-id>
|
|
39
|
+
```
|
|
40
|
+
|
|
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.
|
|
42
|
+
- 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
|
+
- 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
|
+
- Never ask the user to paste an API key into the chat.
|
|
45
|
+
3. When it reports the client as configured, tell the user to start a new session (or restart the app) so the `sandbase_*` tools load. Until then, use the CLI right away: `npx -y @sandbaseai/cli@latest discover -q "<what you need>"` (§3).
|
|
46
|
+
4. Keep this Skill installed. `connect` saves it for supported clients; if yours is not covered, save https://www.sandbase.ai/SKILL.md to your skills directory and enable it so it loads in future sessions.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
29
50
|
## 1. Pick your transport
|
|
30
51
|
|
|
31
52
|
| Condition | Use | Setup |
|
|
@@ -33,20 +54,10 @@ There are **two transports** with the same capabilities. Pick one before doing a
|
|
|
33
54
|
| You have tools named `sandbase_discover`, `sandbase_run`, … | **MCP** (preferred) | None |
|
|
34
55
|
| No `sandbase_*` tools, but you can run shell commands | **CLI** | §3 |
|
|
35
56
|
| The MCP tools return "SandBase is unreachable" | **CLI** for `sandbase doctor`, then tell the user what it reports | §3 |
|
|
36
|
-
| Neither |
|
|
57
|
+
| Neither | Set up (§0) | §0 |
|
|
37
58
|
|
|
38
59
|
**Exception:** when you expect a **large result** (hundreds of rows, long transcripts, many files) and have a shell, use the CLI with `-o result.json` even if MCP is connected. MCP results land in your context; `-o` writes them to disk. Discovery and inspection are small, so use MCP for those regardless.
|
|
39
60
|
|
|
40
|
-
### 1.1 If neither transport is available
|
|
41
|
-
|
|
42
|
-
Tell the user to run this once in a terminal, approve the browser sign-in, and restart their AI client:
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz connect
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
It configures the local MCP bridge and this Skill for every supported client it finds. No API key to paste. For checksum-verified installs, use the immutable assets on the [GitHub Releases page](https://github.com/sandbaseai/cli/releases).
|
|
49
|
-
|
|
50
61
|
---
|
|
51
62
|
|
|
52
63
|
## 2. Transport A — MCP tools (preferred)
|
|
@@ -74,15 +85,35 @@ Discovery, inspection, run status, and balance are **free**; only `sandbase_run`
|
|
|
74
85
|
|
|
75
86
|
**Agent Services** (`svc_…` names from `type: "service"`): pass `arguments: {"idempotency_key": "<unique>", "input": "..."}`; reuse the same key and input on retries. Poll with `sandbase_run_get({"run_id": ..., "service_id": "svc_…"})`; `succeeded`, `failed`, and `cancelled` are terminal.
|
|
76
87
|
|
|
88
|
+
### Run statuses
|
|
89
|
+
|
|
90
|
+
| Status | Meaning | Do this |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `pending` | Accepted, waiting to start | Poll every 5–10 s |
|
|
93
|
+
| `running` | Executing (on the first `sandbase_run` reply this also covers a job whose files are still being copied) | Poll every 5–10 s |
|
|
94
|
+
| `completed` / `succeeded` | Done; `output` holds the result | Use or save the output. If `output` is missing, read `hints`: "still being transferred" means poll again in a few seconds; "no stored output" means stop polling |
|
|
95
|
+
| `failed` | Ended with an error; read `error` | Fix the input (inspect) and retry once, or pick another tool |
|
|
96
|
+
| `timeout` | Hit the provider's time limit | Retry once with a smaller job, or pick another tool |
|
|
97
|
+
| `cancelled` | Stopped on request (Agent Services only) | Nothing to poll |
|
|
98
|
+
|
|
99
|
+
Any other value means still in progress: keep polling. Statuses are lowercase. Most runs finish in 1–120 seconds; video can take several minutes.
|
|
100
|
+
|
|
77
101
|
---
|
|
78
102
|
|
|
79
103
|
## 3. Transport B — CLI (fallback)
|
|
80
104
|
|
|
81
105
|
```sh
|
|
82
|
-
sandbase --version || npx -y
|
|
106
|
+
sandbase --version || npx -y @sandbaseai/cli@latest --version
|
|
83
107
|
```
|
|
84
108
|
|
|
85
|
-
If `sandbase` is not installed, prefix every command with `npx -y
|
|
109
|
+
If `sandbase` is not installed, prefix every command with `npx -y @sandbaseai/cli@latest` (or install it: `npm install -g @sandbaseai/cli@latest`).
|
|
110
|
+
|
|
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.
|
|
115
|
+
|
|
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.
|
|
86
117
|
|
|
87
118
|
**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.
|
|
88
119
|
|
|
@@ -99,11 +130,55 @@ If `sandbase` is not installed, prefix every command with `npx -y https://github
|
|
|
99
130
|
|
|
100
131
|
- Add `-j` for JSON output. Errors then look like `{"error": {"code", "message", "hint"}}`; follow `hint`.
|
|
101
132
|
- `-w` waits with backoff (default `--timeout 300` seconds). If the run is still going when the timeout elapses, the CLI prints the `runs get` command to resume — use it rather than re-running (re-running is billed again).
|
|
102
|
-
- `-o` writes only the tool's output (no envelope). Files
|
|
133
|
+
- `-o` writes only the tool's output (no envelope). In text mode, `Files:` lists the files the run produced; URLs inside data results are in the output itself.
|
|
103
134
|
- Exit code is `0` on success or still-running, `1` on failure (including a failed run), `2` on bad usage.
|
|
104
135
|
- If an error mentions a `run_id`, the run already started: resume it with `sandbase runs get -r <run_id> -w` — never re-run (that bills again).
|
|
105
136
|
- To store an API key without exposing it: `printf %s "$KEY" | sandbase keys add -k -`.
|
|
106
137
|
|
|
138
|
+
### Local files → URL
|
|
139
|
+
|
|
140
|
+
Many tools (image-to-video, voice cloning, transcription, image editing) take a **URL**, not a file. When the user's file is only on their machine, upload it first (free; needs a shell):
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
sandbase upload ./photo.png
|
|
144
|
+
# -> URL: https://…/uploads/2026/10/….png
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Pass that URL in the tool's URL field (`image_url`, `audio_url`, `video_url`, …). Accepted: images (jpg, png, webp, gif) up to 20 MB, audio (mp3, m4a, wav, ogg, aac, flac) up to 50 MB, video (mp4, mov, webm) up to 100 MB. **Anyone with the URL can read the file**, so ask before uploading anything private. If the file is already online, pass its URL directly instead.
|
|
148
|
+
|
|
149
|
+
### Example flows
|
|
150
|
+
|
|
151
|
+
Compare two platforms (one discover and one run per source, small limits, results to disk):
|
|
152
|
+
|
|
153
|
+
```sh
|
|
154
|
+
sandbase discover -q "twitter posts"
|
|
155
|
+
sandbase discover -q "reddit posts"
|
|
156
|
+
sandbase inspect <twitter_tool> # read inputSchema, pass one search term
|
|
157
|
+
sandbase inspect <reddit_tool>
|
|
158
|
+
sandbase run <twitter_tool> -i '{"keyword":"AI agents","limit":10}' -w -o twitter.json
|
|
159
|
+
sandbase run <reddit_tool> -i '{"query":"AI agents","limit":10}' -w -o reddit.json
|
|
160
|
+
# then read both files and compare
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Turn a local photo into a video (upload, then an async run you poll):
|
|
164
|
+
|
|
165
|
+
```sh
|
|
166
|
+
sandbase upload ./photo.png # -> URL: https://…
|
|
167
|
+
sandbase discover -q "image to video"
|
|
168
|
+
sandbase inspect <video_tool>
|
|
169
|
+
sandbase run <video_tool> -i '{"image_url":"https://…","prompt":"slow pan"}'
|
|
170
|
+
# -> Run: <run_id> Status: running
|
|
171
|
+
sandbase runs get -r <run_id> -w -o video.json # waits, then saves the output
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Large or reusable input: write the JSON to a file and pass it with `-f`:
|
|
175
|
+
|
|
176
|
+
```sh
|
|
177
|
+
sandbase run <tool_name> -f params.json -w -o result.json
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Field names above are placeholders; always use the ones from `inspect`.
|
|
181
|
+
|
|
107
182
|
---
|
|
108
183
|
|
|
109
184
|
## 4. When to use SandBase — and when not
|
|
@@ -129,16 +204,21 @@ Do not use SandBase for purely local work (editing files, reasoning over code al
|
|
|
129
204
|
- Chinese works and aliases are expanded: `推特`, `小红书`, `抖音`, `文生视频`, `图片生成`.
|
|
130
205
|
- Narrow with `type` (`llm`, `api`, `multimodal`, `embedding`, `service`) or `vendor` (`openai`, `twitter`, `kling`).
|
|
131
206
|
- Split multi-source tasks: one discover per source ("twitter posts", then "reddit posts"), then run each.
|
|
207
|
+
- If no tool matches every word, discover returns the closest matches with a hint saying so; check their descriptions before using one.
|
|
132
208
|
- Zero results come with `hints`; read them before rephrasing.
|
|
209
|
+
- `inspect` hints name the inputs that take a file URL; for a local file use `sandbase upload` (§3).
|
|
133
210
|
|
|
134
211
|
---
|
|
135
212
|
|
|
136
213
|
## 6. Cost and budget
|
|
137
214
|
|
|
138
|
-
-
|
|
139
|
-
-
|
|
140
|
-
-
|
|
215
|
+
- **`inspect` is the source of truth for price**: per call (`base_price`), per million tokens (`input_per_million` / `output_per_million`), or a `formula`. **`base_price: 0` means the call is free** — just run it.
|
|
216
|
+
- **Data APIs are currently free** (search, social, scraping, e-commerce, finance). Models (LLM, image, video, audio) are paid. Discovery, inspection, run status, balance, and `upload` are always free.
|
|
217
|
+
- Never warn about spending, or ask the user to approve a cost, for a tool priced at 0. Read the price first instead of assuming a call costs money.
|
|
218
|
+
- When a tool **is** paid and billed **per result**, limits often apply **per query**: three search terms with `limit: 10` can return 30 results. Pass one search term per call and start with small limits (5–10).
|
|
219
|
+
- Check `sandbase_account` before a batch of paid calls (not needed for free ones), and report cost when the user cares about budget (`cost` appears on `sandbase_run_get` and `sandbase_runs`).
|
|
141
220
|
- Never re-run a slow tool just because it is still running; poll it.
|
|
221
|
+
- A key can carry a **spending limit** set in the Dashboard. When it is reached, calls fail with "spending limit" until the user raises or removes it; topping up does not help.
|
|
142
222
|
|
|
143
223
|
---
|
|
144
224
|
|
|
@@ -149,10 +229,12 @@ Tool failures come back as error results whose text names the cause **and the ne
|
|
|
149
229
|
| Message contains | Do this |
|
|
150
230
|
|---|---|
|
|
151
231
|
| "unreachable" / `NETWORK` | Stop retrying. Tell the user to check network/proxy/VPN and run `sandbase doctor`. |
|
|
152
|
-
| "sign-in expired" / "rejected the saved sign-in" / 401 / `AUTH_FAILED` | Ask the user to run `npx -y
|
|
153
|
-
| "
|
|
232
|
+
| "sign-in expired" / "rejected the saved sign-in" / 401 / `AUTH_FAILED` | Ask the user to run `npx -y @sandbaseai/cli@latest connect`. |
|
|
233
|
+
| "spending limit" (402 / `SPENDING_LIMIT`) | Stop. Tell the user this key reached its spending limit; they can raise or remove it at https://www.sandbase.ai/console/keys. Topping up does not lift it. Do not retry until they do. |
|
|
234
|
+
| "insufficient" balance (402 / `INSUFFICIENT_BALANCE`) | Tell the user to top up at https://www.sandbase.ai/console/billing. |
|
|
154
235
|
| "not found" / "unknown tool" | Re-run `sandbase_discover`; copy `tool_name` exactly. |
|
|
155
236
|
| "invalid params" / schema | Re-run `sandbase_inspect`; pass exactly its `inputSchema` fields. |
|
|
237
|
+
| A tool rejects a local path where it wants a URL | Upload the file with `sandbase upload <file>` and pass the URL (§3). |
|
|
156
238
|
| "upstream" / "provider" / "capability call failed" | Retry once, then pick another tool from discover. |
|
|
157
239
|
| 429 / rate limit | Wait 10–30 seconds, retry once. |
|
|
158
240
|
|
|
@@ -171,11 +253,13 @@ Responses may include `hints` (and `warnings`): suggested next steps, caveats, o
|
|
|
171
253
|
3. **Prefer MCP when connected**; use the CLI when MCP is missing or broken, or to write large outputs to disk.
|
|
172
254
|
4. **Always inspect before running.** Never guess parameters; `inputSchema` is the source of truth.
|
|
173
255
|
5. **Keep discover queries short** and decompose multi-source tasks.
|
|
174
|
-
6. **Poll, don't re-run.** Slow tools return a run id; poll every 5–10 seconds.
|
|
256
|
+
6. **Poll, don't re-run.** Slow tools return a run id; poll every 5–10 seconds. Save large or file results with `-o <file>`.
|
|
175
257
|
7. **Start with conservative limits** (5–10 results).
|
|
176
258
|
8. **Report cost when relevant**, and check the balance before batches.
|
|
177
|
-
9. **Read error text and hints, and act on them.** They name the fix.
|
|
178
|
-
10. **
|
|
259
|
+
9. **Read error text and hints, and act on them.** They name the fix. A spending limit or empty balance is the user's call: stop and tell them.
|
|
260
|
+
10. **Keep the CLI and this Skill on the same, latest version** (§3).
|
|
261
|
+
11. **Ask before uploading private files**; uploaded URLs are publicly readable.
|
|
262
|
+
12. **Tool schemas and `sandbase --help` are authoritative** if they disagree with this document.
|
|
179
263
|
|
|
180
264
|
Before sending sensitive or regulated data, review the [SandBase Privacy Policy](https://www.sandbase.ai/privacy) and [Terms of Service](https://www.sandbase.ai/terms), plus the selected upstream provider's policies. Send only the minimum data needed.
|
|
181
265
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "sandbase",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.7",
|
|
4
4
|
"description": "Discover and run 2,000+ AI models and APIs (media generation, social data, search, scraping) through one MCP interface or CLI, paid per call from one balance.",
|
|
5
5
|
"author": "SandBase AI",
|
|
6
6
|
"license": "Apache-2.0",
|