@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/README.zh-CN.md
CHANGED
|
@@ -26,36 +26,40 @@
|
|
|
26
26
|
|
|
27
27
|
**SandBase 改变了这一切。** 一行命令,通过 [Model Context Protocol](https://modelcontextprotocol.io) 将你的 Agent 连接到 2,000+ AI 模型与 API。不用管理 API Key,不用折腾配置。
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
把这一行发给你的 agent,它会自己读取 Skill、运行 `connect`,只需你在浏览器里确认一次登录:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
set up https://www.sandbase.ai/SKILL.md
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
想自己动手:
|
|
30
36
|
|
|
31
37
|
```sh
|
|
32
|
-
|
|
33
|
-
sandbase connect
|
|
38
|
+
npx -y @sandbaseai/cli@latest connect
|
|
34
39
|
```
|
|
35
40
|
|
|
36
|
-
|
|
41
|
+
在 macOS 或 Linux 上使用官方 Homebrew Formula:
|
|
37
42
|
|
|
38
43
|
```sh
|
|
39
|
-
|
|
44
|
+
brew install sandbaseai/tap/sandbaseai-cli
|
|
45
|
+
sandbase connect
|
|
40
46
|
```
|
|
41
47
|
|
|
42
48
|
想先验证兼容性、暂不登录也不修改本地配置?运行只读目录命令,确认当前版本支持的 25 个客户端:
|
|
43
49
|
|
|
44
50
|
```sh
|
|
45
|
-
npx -y
|
|
51
|
+
npx -y @sandbaseai/cli@latest catalog --json
|
|
46
52
|
```
|
|
47
53
|
|
|
48
54
|
<p align="center">
|
|
49
|
-
<a href="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/catalog-audit-5eea5978a1ed.webp"><img src="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/catalog-audit-5eea5978a1ed.webp" alt="SandBase CLI
|
|
50
|
-
<a href="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/doctor-readback-3c86ac73e463.webp"><img src="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/doctor-readback-3c86ac73e463.webp" alt="SandBase CLI
|
|
55
|
+
<a href="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/catalog-audit-5eea5978a1ed.webp"><img src="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/catalog-audit-5eea5978a1ed.webp" alt="SandBase CLI 只读目录审计显示 25 个客户端目标" width="49%"></a>
|
|
56
|
+
<a href="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/doctor-readback-3c86ac73e463.webp"><img src="https://static.sandbase.ai/blog/screenshots/sandbase-cli-mcp-bridge-25-ai-clients/doctor-readback-3c86ac73e463.webp" alt="SandBase CLI doctor 对空白隔离配置按预期安全失败" width="49%"></a>
|
|
51
57
|
</p>
|
|
52
|
-
<p align="center"><sub
|
|
58
|
+
<p align="center"><sub>证据:不写配置的目录审计,以及针对空白隔离配置的受限 doctor 检查。</sub></p>
|
|
53
59
|
|
|
54
|
-
|
|
55
|
-
`1ad535b2899ca460b57b3c268aef278fee28fd28e649a89b92951514fd71fffa`。
|
|
56
|
-
目前 npm 的 `latest` 标签仍是 v0.1.14,因此在可信发布启用完成前,请使用上面的版本化 GitHub 地址。
|
|
60
|
+
每个 GitHub 发布版都会随包公布自己的 SHA-256,可据此校验并固定到某个确切版本。
|
|
57
61
|
|
|
58
|
-
项目已进入[官方 MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers
|
|
62
|
+
项目已进入[官方 MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.sandbaseai%2Fcli),并被[中国独立开发者项目(程序员版)](https://github.com/1c7/chinese-independent-developer/blob/master/pages/README-Programmer-Edition.md#sandbase---github)独立收录。
|
|
59
63
|
|
|
60
64
|
查看[中文项目页](https://sandbaseai.github.io/cli/zh/)和[中文工作流指南](https://github.com/sandbaseai/cli/discussions/48)。如果 SandBase CLI 对你有帮助,请[给仓库一个 Star](https://github.com/sandbaseai/cli),让更多开发者发现它。
|
|
61
65
|
|
|
@@ -124,15 +128,15 @@ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cl
|
|
|
124
128
|
无需登录或修改任何文件,即可预览完整兼容性目录:
|
|
125
129
|
|
|
126
130
|
```sh
|
|
127
|
-
npx -y
|
|
131
|
+
npx -y @sandbaseai/cli@latest catalog --json
|
|
128
132
|
```
|
|
129
133
|
|
|
130
134
|
```sh
|
|
131
135
|
# 一次连接所有检测到的客户端
|
|
132
|
-
npx -y
|
|
136
|
+
npx -y @sandbaseai/cli@latest connect
|
|
133
137
|
|
|
134
138
|
# 或者指定某个客户端
|
|
135
|
-
npx -y
|
|
139
|
+
npx -y @sandbaseai/cli@latest connect --client cursor
|
|
136
140
|
```
|
|
137
141
|
|
|
138
142
|
### OpenClaw 快速开始
|
|
@@ -140,8 +144,8 @@ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cl
|
|
|
140
144
|
直接指定 OpenClaw,并在使用前让 CLI 回读验证由 SandBase 管理的 MCP 服务与 Skill:
|
|
141
145
|
|
|
142
146
|
```sh
|
|
143
|
-
npx -y
|
|
144
|
-
npx -y
|
|
147
|
+
npx -y @sandbaseai/cli@latest connect --client openclaw
|
|
148
|
+
npx -y @sandbaseai/cli@latest doctor --client openclaw
|
|
145
149
|
```
|
|
146
150
|
|
|
147
151
|
当 `doctor` 确认凭证、MCP bridge 和 Skill 均已配置后,重启 OpenClaw,
|
|
@@ -150,7 +154,7 @@ SandBase 管理、但同样名为 `sandbase` 的 MCP 服务,安装器会保持
|
|
|
150
154
|
以后若要移除由 SandBase 管理的 MCP 条目和本地凭证:
|
|
151
155
|
|
|
152
156
|
```sh
|
|
153
|
-
npx -y
|
|
157
|
+
npx -y @sandbaseai/cli@latest unregister --client openclaw
|
|
154
158
|
```
|
|
155
159
|
|
|
156
160
|
OpenClaw 目前没有受支持的 Skill 移除命令,因此 `unregister` 会明确报告这一限制,
|
|
@@ -161,8 +165,8 @@ OpenClaw 目前没有受支持的 Skill 移除命令,因此 `unregister` 会
|
|
|
161
165
|
SandBase 可以在同一次授权事务中安装由它管理的 Hermes Skill 和本地 MCP 条目:
|
|
162
166
|
|
|
163
167
|
```sh
|
|
164
|
-
npx -y
|
|
165
|
-
npx -y
|
|
168
|
+
npx -y @sandbaseai/cli@latest connect --client hermes
|
|
169
|
+
npx -y @sandbaseai/cli@latest doctor --client hermes
|
|
166
170
|
```
|
|
167
171
|
|
|
168
172
|
`doctor` 会验证所有权明确的本地凭证、MCP 条目与 Skill。随后重启 Hermes,
|
|
@@ -172,7 +176,7 @@ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cl
|
|
|
172
176
|
共用的 bridge:
|
|
173
177
|
|
|
174
178
|
```sh
|
|
175
|
-
npx -y
|
|
179
|
+
npx -y @sandbaseai/cli@latest unregister --client hermes
|
|
176
180
|
```
|
|
177
181
|
|
|
178
182
|
该集成已被独立收录于
|
|
@@ -198,6 +202,14 @@ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cl
|
|
|
198
202
|
|
|
199
203
|
---
|
|
200
204
|
|
|
205
|
+
## 价格
|
|
206
|
+
|
|
207
|
+
- **数据 API(搜索、社交、抓取、电商、金融)免费调用。**
|
|
208
|
+
- discover、inspect、运行状态、余额、文件上传均免费。
|
|
209
|
+
- 模型(LLM、图像、视频、音频)按次或按百万 token 计费。
|
|
210
|
+
|
|
211
|
+
`sandbase inspect <工具名>` 会显示当前价格,`base_price: 0` 表示免费。价格可能变动,请以实时返回为准。
|
|
212
|
+
|
|
201
213
|
## 命令
|
|
202
214
|
|
|
203
215
|
### CLI 命令
|
|
@@ -265,7 +277,7 @@ discover → inspect → run
|
|
|
265
277
|
## 开始使用
|
|
266
278
|
|
|
267
279
|
```sh
|
|
268
|
-
npx -y
|
|
280
|
+
npx -y @sandbaseai/cli@latest connect
|
|
269
281
|
```
|
|
270
282
|
|
|
271
283
|
然后让你的 Agent 做一些它以前做不到的事。
|
package/assets/mcp-bridge.mjs
CHANGED
|
@@ -19,6 +19,8 @@ import { pathToFileURL } from "node:url";
|
|
|
19
19
|
const allowedClients = new Set(["codex", "claude-code", "cursor", "gemini-cli", "hermes", "openclaw", "opencode", "qwen-code", "windsurf", "cursor-cli", "kimi-cli", "kiro", "kiro-cli", "amp", "crush", "iflow-cli", "warp", "claude-desktop", "cowork", "antigravity", "trae", "qoder", "workbuddy", "pi"]);
|
|
20
20
|
const BILLING_URL = "https://www.sandbase.ai/console/billing";
|
|
21
21
|
const RECONNECT = "npx -y @sandbaseai/cli@latest connect";
|
|
22
|
+
const KEYS_URL = "https://www.sandbase.ai/console/keys";
|
|
23
|
+
const SPENDING_LIMIT = `This SandBase key reached the spending limit set on it. Stop and tell the user: topping up does not lift it; they can raise or remove the limit at ${KEYS_URL}, then retry.`;
|
|
22
24
|
// Tool calls get no bridge-side deadline (long synchronous tools must be able to
|
|
23
25
|
// finish); control-plane methods are bounded so offline detection stays quick.
|
|
24
26
|
const CONTROL_TIMEOUT_MS = 60_000;
|
|
@@ -71,9 +73,11 @@ export function isIdempotentRequest(request) {
|
|
|
71
73
|
}
|
|
72
74
|
export function hintFor(message) {
|
|
73
75
|
const text = String(message || "").toLowerCase();
|
|
76
|
+
// Before auth: "API key spending limit exceeded" is neither a sign-in nor a balance problem.
|
|
77
|
+
if (/spending limit/.test(text)) return SPENDING_LIMIT;
|
|
74
78
|
// Auth first: "API key not found" is a sign-in problem, not a misspelled tool.
|
|
75
79
|
if (/unauthori[sz]ed|api key|credential|revoked|expired|authenticat|sign-in|signin/.test(text)) return `The SandBase sign-in is not valid. Ask the user to run \`${RECONNECT}\` in a terminal.`;
|
|
76
|
-
if (/insufficient (balance|credit|funds)|payment required|
|
|
80
|
+
if (/insufficient (balance|credit|funds)|payment required|top up/.test(text)) return `Tell the user their SandBase balance is insufficient; they can top up at ${BILLING_URL}.`;
|
|
77
81
|
if (/rate.?limit|too many requests|429/.test(text)) return "Rate limited: wait 10-30 seconds, then retry once.";
|
|
78
82
|
if (/run .*not found|task not found/.test(text)) return "Use the prediction_id/run_id returned by sandbase_run, or list recent runs with sandbase_runs. Agent Service runs also need service_id.";
|
|
79
83
|
if (/invalid service request|unknown tool|tool(?: '[^']*')? (?:was )?not found|model not found|tool name is required/.test(text)) return "Check the exact tool name with sandbase_discover (names look like sandbase_twitter_web_search_timeline), then sandbase_inspect it.";
|
|
@@ -86,7 +90,8 @@ function httpFailure(status, text, host) {
|
|
|
86
90
|
try { const parsed = JSON.parse(text); const e = parsed?.error; detail = typeof e === "string" ? e : typeof e?.message === "string" ? e.message : typeof parsed?.message === "string" ? parsed.message : ""; } catch { /* non-JSON gateway body is never forwarded */ }
|
|
87
91
|
const suffix = detail ? `: ${detail.slice(0, 300)}` : "";
|
|
88
92
|
if (status === 401) return `SandBase rejected the saved sign-in (401)${suffix}. Ask the user to run \`${RECONNECT}\` in a terminal to sign in again.`;
|
|
89
|
-
if (status === 402
|
|
93
|
+
if (status === 402 && /spending limit/i.test(detail)) return `${SPENDING_LIMIT} (402${suffix})`;
|
|
94
|
+
if (status === 402) return `SandBase balance is insufficient (402)${suffix}. The user can top up at ${BILLING_URL}.`;
|
|
90
95
|
if (status === 403) return `This SandBase credential is not allowed for this request (403)${suffix}. Ask the user to run \`${RECONNECT}\`.`;
|
|
91
96
|
if (status === 429) return `SandBase rate limit reached (429)${suffix}. Wait 10-30 seconds, then retry once.`;
|
|
92
97
|
if (status >= 500) return `SandBase returned HTTP ${status} from ${host}${suffix}. Temporary server error: retry in a minute; the user can run \`sandbase doctor\` if it persists.`;
|
package/dist/agent/client.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
export declare const DEFAULT_MCP_URL = "https://api.sandbase.ai/v1/mcp";
|
|
2
2
|
export declare const UNREACHABLE_HINT = "Check this machine's network, proxy, or VPN, then run `sandbase doctor` and retry.";
|
|
3
|
-
export type ErrorCode = "AUTH_REQUIRED" | "AUTH_FAILED" | "INSUFFICIENT_BALANCE" | "FORBIDDEN" | "NOT_FOUND" | "RATE_LIMITED" | "INVALID_INPUT" | "NETWORK" | "UPSTREAM" | "RUN_FAILED" | "INVALID_RESPONSE" | "TOOL_ERROR" | "USAGE";
|
|
3
|
+
export type ErrorCode = "AUTH_REQUIRED" | "AUTH_FAILED" | "INSUFFICIENT_BALANCE" | "SPENDING_LIMIT" | "FORBIDDEN" | "NOT_FOUND" | "RATE_LIMITED" | "INVALID_INPUT" | "NETWORK" | "UPSTREAM" | "RUN_FAILED" | "INVALID_RESPONSE" | "TOOL_ERROR" | "USAGE";
|
|
4
4
|
export declare class SandBaseError extends Error {
|
|
5
5
|
readonly code: ErrorCode;
|
|
6
6
|
readonly hint?: string | undefined;
|
|
@@ -12,6 +12,7 @@ export declare function webUrl(env?: NodeJS.ProcessEnv): string;
|
|
|
12
12
|
export declare function billingUrl(env?: NodeJS.ProcessEnv): string;
|
|
13
13
|
export declare function keysUrl(env?: NodeJS.ProcessEnv): string;
|
|
14
14
|
export declare const CONNECT_COMMAND = "npx -y @sandbaseai/cli@latest connect";
|
|
15
|
+
export declare function spendingLimitHint(env?: NodeJS.ProcessEnv): string;
|
|
15
16
|
export declare function validMcpUrl(value: unknown): string | undefined;
|
|
16
17
|
export interface Endpoint {
|
|
17
18
|
credential: string;
|
|
@@ -48,7 +49,7 @@ export interface ToolOutput {
|
|
|
48
49
|
export type FetchLike = (url: string, init: {
|
|
49
50
|
method: string;
|
|
50
51
|
headers: Record<string, string>;
|
|
51
|
-
body: string;
|
|
52
|
+
body: string | FormData;
|
|
52
53
|
signal: AbortSignal;
|
|
53
54
|
}) => Promise<{
|
|
54
55
|
ok: boolean;
|
package/dist/agent/client.js
CHANGED
|
@@ -27,6 +27,7 @@ export function webUrl(env = process.env) { return (env.SANDBASE_WEB_URL || "htt
|
|
|
27
27
|
export function billingUrl(env = process.env) { return `${webUrl(env)}/console/billing`; }
|
|
28
28
|
export function keysUrl(env = process.env) { return `${webUrl(env)}/console/keys`; }
|
|
29
29
|
export const CONNECT_COMMAND = "npx -y @sandbaseai/cli@latest connect";
|
|
30
|
+
export function spendingLimitHint(env = process.env) { return `Stop and tell the user: this key's spending limit is reached. Topping up does not lift it; they can raise or remove the limit at ${keysUrl(env)}, then retry.`; }
|
|
30
31
|
export function validMcpUrl(value) {
|
|
31
32
|
if (typeof value !== "string")
|
|
32
33
|
return undefined;
|
|
@@ -120,10 +121,14 @@ export function describeNetworkFailure(error) {
|
|
|
120
121
|
/** Map a server/tool error message to the most useful next step. */
|
|
121
122
|
export function hintForMessage(message, env = process.env) {
|
|
122
123
|
const text = message.toLowerCase();
|
|
124
|
+
// "API key spending limit exceeded" mentions the key but is not a sign-in problem, and
|
|
125
|
+
// topping up does not lift it, so it is checked before both auth and balance.
|
|
126
|
+
if (/spending limit/.test(text))
|
|
127
|
+
return spendingLimitHint(env);
|
|
123
128
|
// Auth first: "API key not found" is a sign-in problem, not a misspelled tool.
|
|
124
129
|
if (/unauthori[sz]ed|api key|credential|revoked|expired|authenticat|sign-in|signin/.test(text))
|
|
125
130
|
return `Sign in again with \`${CONNECT_COMMAND}\`, or check SANDBASE_API_KEY.`;
|
|
126
|
-
if (/insufficient (balance|credit|funds)|payment required|
|
|
131
|
+
if (/insufficient (balance|credit|funds)|payment required|top up/.test(text))
|
|
127
132
|
return `Top up at ${billingUrl(env)}, then retry.`;
|
|
128
133
|
if (/rate.?limit|too many requests|429/.test(text))
|
|
129
134
|
return "Rate limited. Wait 10-30 seconds, then retry once.";
|
|
@@ -148,8 +153,10 @@ export function httpError(status, body, host, env = process.env) {
|
|
|
148
153
|
const detail = message ? `: ${message}` : "";
|
|
149
154
|
if (status === 401)
|
|
150
155
|
return new SandBaseError("AUTH_FAILED", `SandBase rejected the saved sign-in or API key (401)${detail}.`, `Sign in again with \`${CONNECT_COMMAND}\`, or create a new key at ${keysUrl(env)}.`, status);
|
|
156
|
+
if (status === 402 && /spending limit/i.test(message))
|
|
157
|
+
return new SandBaseError("SPENDING_LIMIT", `This credential reached the spending limit set on it in the SandBase Dashboard (402)${detail}.`, spendingLimitHint(env), status);
|
|
151
158
|
if (status === 402)
|
|
152
|
-
return new SandBaseError("INSUFFICIENT_BALANCE", `Insufficient balance
|
|
159
|
+
return new SandBaseError("INSUFFICIENT_BALANCE", `Insufficient balance (402)${detail}.`, `Top up at ${billingUrl(env)}, then retry.`, status);
|
|
153
160
|
if (status === 403)
|
|
154
161
|
return new SandBaseError("FORBIDDEN", `This credential is not allowed to call ${host} (403)${detail}.`, `Use a credential issued by \`${CONNECT_COMMAND}\` or a full API key from ${keysUrl(env)}.`, status);
|
|
155
162
|
if (status === 404)
|
|
@@ -243,7 +250,7 @@ export class SandBaseMCPClient {
|
|
|
243
250
|
return toolOutput(await this.rpc("tools/call", { name, arguments: args }), this.env);
|
|
244
251
|
}
|
|
245
252
|
}
|
|
246
|
-
const serverErrorCodes = { tool_not_found: "NOT_FOUND", run_not_found: "NOT_FOUND", invalid_arguments: "INVALID_INPUT", insufficient_balance: "INSUFFICIENT_BALANCE", rate_limited: "RATE_LIMITED", unauthorized: "AUTH_FAILED", run_failed: "RUN_FAILED", upstream_error: "UPSTREAM", internal_error: "UPSTREAM" };
|
|
253
|
+
const serverErrorCodes = { tool_not_found: "NOT_FOUND", run_not_found: "NOT_FOUND", invalid_arguments: "INVALID_INPUT", insufficient_balance: "INSUFFICIENT_BALANCE", spending_limit: "SPENDING_LIMIT", rate_limited: "RATE_LIMITED", unauthorized: "AUTH_FAILED", run_failed: "RUN_FAILED", upstream_error: "UPSTREAM", internal_error: "UPSTREAM" };
|
|
247
254
|
export function toolOutput(result, env = process.env) {
|
|
248
255
|
const value = (result || {});
|
|
249
256
|
const text = (value.content || []).filter(item => item?.type === "text" && typeof item.text === "string").map(item => item.text).join("\n");
|
package/dist/agent/commands.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type FetchLike } from "./client.js";
|
|
2
|
-
export declare const agentCommands: readonly ["discover", "inspect", "run", "runs", "balance", "keys"];
|
|
2
|
+
export declare const agentCommands: readonly ["discover", "inspect", "run", "runs", "upload", "balance", "keys"];
|
|
3
3
|
export type AgentCommand = typeof agentCommands[number];
|
|
4
4
|
export declare function isAgentCommand(value: string | undefined): value is AgentCommand;
|
|
5
5
|
export interface AgentDeps {
|
|
@@ -11,10 +11,18 @@ export interface AgentDeps {
|
|
|
11
11
|
now?: () => number;
|
|
12
12
|
stdin?: () => Promise<string>;
|
|
13
13
|
}
|
|
14
|
-
export declare const agentUsage = "SandBase agent commands (same capabilities as the sandbase_* MCP tools):\n sandbase discover -q \"<what you need>\" [-t llm|api|multimodal|embedding|service] [--vendor <slug>] [-l 10] [-j]\n sandbase inspect <tool_name> [-j]\n sandbase run <tool_name> [-i '<json>' | -f input.json] [-w] [--timeout 300] [-o result.json] [-j]\n sandbase runs get -r <run_id> [--service <svc_id>] [-w] [--timeout 300] [-o result.json] [-j]\n sandbase runs list [-l 10] [--model <model>] [--service <svc_id>] [-j]\n sandbase balance [-j]\n sandbase keys add -k - (reads the key from stdin) | keys list | keys remove\nGlobal: --client <client> picks a connected client's credential; SANDBASE_API_KEY overrides all; -j prints JSON.";
|
|
14
|
+
export declare const agentUsage = "SandBase agent commands (same capabilities as the sandbase_* MCP tools):\n sandbase discover -q \"<what you need>\" [-t llm|api|multimodal|embedding|service] [--vendor <slug>] [-l 10] [-j]\n sandbase inspect <tool_name> [-j]\n sandbase run <tool_name> [-i '<json>' | -f input.json] [-w] [--timeout 300] [-o result.json] [-j]\n sandbase runs get -r <run_id> [--service <svc_id>] [-w] [--timeout 300] [-o result.json] [-j]\n sandbase runs list [-l 10] [--model <model>] [--service <svc_id>] [-j]\n sandbase upload <file> [-j] (local image/audio/video \u2192 public URL for tools that take a URL)\n sandbase balance [-j]\n sandbase keys add -k - (reads the key from stdin) | keys list | keys remove\nGlobal: --client <client> picks a connected client's credential; SANDBASE_API_KEY overrides all; -j prints JSON.";
|
|
15
15
|
export declare function formatPrice(pricing: unknown): string;
|
|
16
|
+
/**
|
|
17
|
+
* Files the run produced. The server returns media outputs as `[{url, …}]`
|
|
18
|
+
* (content_type is only added when it can be inferred), so an entry counts as a
|
|
19
|
+
* file when it has a `url` and carries no content of its own. A scraped page's
|
|
20
|
+
* `{url, markdown}`, a tweet row, or a nested avatar is content, not a file.
|
|
21
|
+
*/
|
|
22
|
+
export declare function generatedFiles(output: unknown): string[];
|
|
16
23
|
/** Resolve a root-level local $ref (#/components/schemas/X, #/$defs/X, #/definitions/X) so agents see real fields. */
|
|
17
24
|
export declare function resolveSchema(schema: unknown): Record<string, unknown>;
|
|
25
|
+
export declare function uploadUrlFor(mcpUrl: string): string;
|
|
18
26
|
/** Shows at most a quarter of the key (capped at 6 chars) so short keys are not mostly revealed. */
|
|
19
27
|
export declare function maskKey(key: string): string;
|
|
20
28
|
export declare function runAgentCommand(command: AgentCommand, argv: string[], deps?: AgentDeps): Promise<number>;
|
package/dist/agent/commands.js
CHANGED
|
@@ -3,13 +3,13 @@
|
|
|
3
3
|
// agent without MCP (or with a broken MCP session) still has a working path,
|
|
4
4
|
// and so large results can go straight to disk with -o instead of the context.
|
|
5
5
|
import { constants as fsConstants } from "node:fs";
|
|
6
|
-
import { access, readFile, rm, writeFile } from "node:fs/promises";
|
|
7
|
-
import { dirname, resolve as resolvePath } from "node:path";
|
|
6
|
+
import { access, readFile, rm, stat, writeFile } from "node:fs/promises";
|
|
7
|
+
import { basename, dirname, extname, resolve as resolvePath } from "node:path";
|
|
8
8
|
import { parseArgs } from "node:util";
|
|
9
9
|
import { atomicWrite } from "../fs-safe.js";
|
|
10
|
-
import { CONNECT_COMMAND, keyFilePath, keysUrl, readStoredKey, resolveEndpoint, SandBaseError, SandBaseMCPClient, toolOutput, validMcpUrl } from "./client.js";
|
|
10
|
+
import { CONNECT_COMMAND, describeNetworkFailure, httpError, keyFilePath, keysUrl, readStoredKey, resolveEndpoint, SandBaseError, SandBaseMCPClient, toolOutput, validMcpUrl } from "./client.js";
|
|
11
11
|
import { updateNotice } from "./update.js";
|
|
12
|
-
export const agentCommands = ["discover", "inspect", "run", "runs", "balance", "keys"];
|
|
12
|
+
export const agentCommands = ["discover", "inspect", "run", "runs", "upload", "balance", "keys"];
|
|
13
13
|
export function isAgentCommand(value) { return agentCommands.includes(value); }
|
|
14
14
|
export const agentUsage = `SandBase agent commands (same capabilities as the sandbase_* MCP tools):
|
|
15
15
|
sandbase discover -q "<what you need>" [-t llm|api|multimodal|embedding|service] [--vendor <slug>] [-l 10] [-j]
|
|
@@ -17,6 +17,7 @@ export const agentUsage = `SandBase agent commands (same capabilities as the san
|
|
|
17
17
|
sandbase run <tool_name> [-i '<json>' | -f input.json] [-w] [--timeout 300] [-o result.json] [-j]
|
|
18
18
|
sandbase runs get -r <run_id> [--service <svc_id>] [-w] [--timeout 300] [-o result.json] [-j]
|
|
19
19
|
sandbase runs list [-l 10] [--model <model>] [--service <svc_id>] [-j]
|
|
20
|
+
sandbase upload <file> [-j] (local image/audio/video → public URL for tools that take a URL)
|
|
20
21
|
sandbase balance [-j]
|
|
21
22
|
sandbase keys add -k - (reads the key from stdin) | keys list | keys remove
|
|
22
23
|
Global: --client <client> picks a connected client's credential; SANDBASE_API_KEY overrides all; -j prints JSON.`;
|
|
@@ -82,20 +83,39 @@ function hintLines(hints) {
|
|
|
82
83
|
}
|
|
83
84
|
function printHints(out, ...sources) { const lines = sources.flatMap(hintLines); if (lines.length)
|
|
84
85
|
out.print(["", "Hints:", ...lines.map(line => ` - ${line}`)].join("\n")); }
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
86
|
+
/**
|
|
87
|
+
* Files the run produced. The server returns media outputs as `[{url, …}]`
|
|
88
|
+
* (content_type is only added when it can be inferred), so an entry counts as a
|
|
89
|
+
* file when it has a `url` and carries no content of its own. A scraped page's
|
|
90
|
+
* `{url, markdown}`, a tweet row, or a nested avatar is content, not a file.
|
|
91
|
+
*/
|
|
92
|
+
export function generatedFiles(output) {
|
|
93
|
+
const isUrl = (value) => typeof value === "string" && /^https?:\/\/\S+$/.test(value);
|
|
94
|
+
// Keys that make an object a data row rather than a produced file.
|
|
95
|
+
const contentKeys = ["text", "markdown", "md", "html", "content", "title", "body", "snippet", "caption", "summary", "data", "items", "results", "children", "comments", "author", "user"];
|
|
96
|
+
const fileEntry = (entry) => {
|
|
97
|
+
if (isUrl(entry))
|
|
98
|
+
return entry;
|
|
99
|
+
if (!entry || typeof entry !== "object" || Array.isArray(entry))
|
|
100
|
+
return undefined;
|
|
101
|
+
const record = entry;
|
|
102
|
+
if (!isUrl(record.url))
|
|
103
|
+
return undefined;
|
|
104
|
+
return contentKeys.some(key => record[key] !== undefined) ? undefined : record.url;
|
|
105
|
+
};
|
|
106
|
+
const list = (value) => {
|
|
107
|
+
const entries = Array.isArray(value) ? value : [value];
|
|
108
|
+
return entries.map(fileEntry).filter((url) => !!url);
|
|
109
|
+
};
|
|
110
|
+
let files = list(output);
|
|
111
|
+
// {images: [{url}], seed: 1} / {video: {url}}: a media-named key holds the files.
|
|
112
|
+
if (!files.length && output && typeof output === "object" && !Array.isArray(output)) {
|
|
113
|
+
for (const [key, value] of Object.entries(output)) {
|
|
114
|
+
if (/^(image|video|audio|file|media|clip|frame)s?$/i.test(key))
|
|
115
|
+
files = files.concat(list(value));
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return [...new Set(files)].slice(0, 20);
|
|
99
119
|
}
|
|
100
120
|
function shellQuote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
|
|
101
121
|
const commonOptions = { json: { type: "boolean", short: "j" }, client: { type: "string" }, help: { type: "boolean", short: "h" } };
|
|
@@ -218,9 +238,9 @@ function printRun(out, view, outputFile) {
|
|
|
218
238
|
if (view.cost === undefined && view.cost_status === "settling")
|
|
219
239
|
lines.push("Cost: settling (see `sandbase runs list` shortly)");
|
|
220
240
|
if (phase === "succeeded" && hasOutput(view)) {
|
|
221
|
-
const
|
|
222
|
-
if (
|
|
223
|
-
lines.push("Files:", ...
|
|
241
|
+
const files = generatedFiles(view.output);
|
|
242
|
+
if (files.length)
|
|
243
|
+
lines.push("Files:", ...files.map(url => ` ${url}`));
|
|
224
244
|
if (outputFile)
|
|
225
245
|
lines.push(`Saved output to ${outputFile}`);
|
|
226
246
|
else {
|
|
@@ -442,6 +462,71 @@ async function runs(argv, out, env, deps, fetchImpl) {
|
|
|
442
462
|
}
|
|
443
463
|
throw new SandBaseError("USAGE", "Use `sandbase runs get -r <run_id>` or `sandbase runs list`.");
|
|
444
464
|
}
|
|
465
|
+
// What /v1/upload accepts, by extension. Server limits are 20/50/500 MB; video is
|
|
466
|
+
// capped at 100 MB here because the API sits behind Cloudflare's request-body limit.
|
|
467
|
+
const MB = 1024 * 1024;
|
|
468
|
+
const uploadTypes = {
|
|
469
|
+
".jpg": { mime: "image/jpeg", kind: "image", max: 20 * MB }, ".jpeg": { mime: "image/jpeg", kind: "image", max: 20 * MB }, ".png": { mime: "image/png", kind: "image", max: 20 * MB }, ".webp": { mime: "image/webp", kind: "image", max: 20 * MB }, ".gif": { mime: "image/gif", kind: "image", max: 20 * MB },
|
|
470
|
+
".mp3": { mime: "audio/mpeg", kind: "audio", max: 50 * MB }, ".m4a": { mime: "audio/mp4", kind: "audio", max: 50 * MB }, ".wav": { mime: "audio/wav", kind: "audio", max: 50 * MB }, ".ogg": { mime: "audio/ogg", kind: "audio", max: 50 * MB }, ".aac": { mime: "audio/aac", kind: "audio", max: 50 * MB }, ".flac": { mime: "audio/flac", kind: "audio", max: 50 * MB },
|
|
471
|
+
".mp4": { mime: "video/mp4", kind: "video", max: 100 * MB }, ".mov": { mime: "video/quicktime", kind: "video", max: 100 * MB }, ".webm": { mime: "video/webm", kind: "video", max: 100 * MB },
|
|
472
|
+
};
|
|
473
|
+
export function uploadUrlFor(mcpUrl) { const url = new URL(mcpUrl); url.pathname = url.pathname.replace(/\/mcp$/, "/upload"); url.search = ""; return url.href; }
|
|
474
|
+
async function upload(argv, out, env, fetchImpl) {
|
|
475
|
+
const { values, positionals } = parse(argv, { file: { type: "string", short: "f" } });
|
|
476
|
+
const path = (values.file ?? positionals[0] ?? "").trim();
|
|
477
|
+
if (!path)
|
|
478
|
+
throw new SandBaseError("USAGE", "Pass the local file to upload.", "Example: sandbase upload ./photo.png");
|
|
479
|
+
const type = uploadTypes[extname(path).toLowerCase()];
|
|
480
|
+
if (!type)
|
|
481
|
+
throw new SandBaseError("USAGE", `Cannot upload ${basename(path)}: only images (jpg, png, webp, gif), audio (mp3, m4a, wav, ogg, aac, flac) and video (mp4, mov, webm) are accepted.`);
|
|
482
|
+
let size;
|
|
483
|
+
try {
|
|
484
|
+
const info = await stat(path);
|
|
485
|
+
if (!info.isFile())
|
|
486
|
+
throw new Error("not a file");
|
|
487
|
+
size = info.size;
|
|
488
|
+
}
|
|
489
|
+
catch {
|
|
490
|
+
throw new SandBaseError("USAGE", `Cannot read ${path}: it does not exist or is not a file.`);
|
|
491
|
+
}
|
|
492
|
+
if (size > type.max)
|
|
493
|
+
throw new SandBaseError("USAGE", `${basename(path)} is ${Math.ceil(size / MB)} MB; the ${type.kind} limit is ${type.max / MB} MB.`, type.kind === "video" ? "Trim or compress the video, or pass a URL where it is already hosted." : "Compress the file, or pass a URL where it is already hosted.");
|
|
494
|
+
const endpoint = await resolveEndpoint(values.client ? { client: values.client } : {}, env);
|
|
495
|
+
const target = uploadUrlFor(endpoint.url);
|
|
496
|
+
const host = new URL(target).host;
|
|
497
|
+
const form = new FormData();
|
|
498
|
+
form.append("file", new Blob([await readFile(path)], { type: type.mime }), basename(path));
|
|
499
|
+
let response;
|
|
500
|
+
try {
|
|
501
|
+
response = await (fetchImpl ?? globalThis.fetch)(target, { method: "POST", headers: { authorization: `Bearer ${endpoint.credential}`, "x-sandbase-client": "cli" }, body: form, signal: AbortSignal.timeout(600_000) });
|
|
502
|
+
}
|
|
503
|
+
catch (error) {
|
|
504
|
+
throw new SandBaseError("NETWORK", `Upload to ${host} failed (${describeNetworkFailure(error)}).`, "Check the network, then retry; nothing is billed for uploads.");
|
|
505
|
+
}
|
|
506
|
+
const text = await response.text();
|
|
507
|
+
if (response.status === 403 && /insufficient_scope/.test(text))
|
|
508
|
+
throw new SandBaseError("FORBIDDEN", `This sign-in cannot upload files on ${host} yet (403).`, `Ask the user for a full API key from ${keysUrl(env)} and run the upload with SANDBASE_API_KEY set (never paste the key into chat).`, 403);
|
|
509
|
+
if (response.status === 404)
|
|
510
|
+
throw new SandBaseError("NOT_FOUND", `${host} does not accept file uploads (404).`, "Pass a URL where the file is already hosted instead.", 404);
|
|
511
|
+
if (!response.ok)
|
|
512
|
+
throw httpError(response.status, text, host, env);
|
|
513
|
+
let data;
|
|
514
|
+
try {
|
|
515
|
+
data = JSON.parse(text);
|
|
516
|
+
}
|
|
517
|
+
catch {
|
|
518
|
+
data = {};
|
|
519
|
+
}
|
|
520
|
+
const inner = (data.data && typeof data.data === "object" ? data.data : data);
|
|
521
|
+
if (typeof inner.url !== "string" || !inner.url)
|
|
522
|
+
throw new SandBaseError("INVALID_RESPONSE", `Expected an uploaded file URL from ${host}.`, "Retry once; run `sandbase doctor` if it persists.");
|
|
523
|
+
if (out.json) {
|
|
524
|
+
out.data(inner);
|
|
525
|
+
return 0;
|
|
526
|
+
}
|
|
527
|
+
out.print([`Uploaded ${basename(path)} (${inner.type ?? type.mime}, ${Math.max(1, Math.round(size / 1024))} KB)`, `URL: ${inner.url}`, ...(inner.duration_seconds ? [`Duration: ${trimNumber(inner.duration_seconds)}s`] : []), "", "Pass this URL to the tool's image/audio/video URL field. Anyone with the URL can read the file."].join("\n"));
|
|
528
|
+
return 0;
|
|
529
|
+
}
|
|
445
530
|
async function balance(argv, out, env, fetchImpl) {
|
|
446
531
|
const { values } = parse(argv, {});
|
|
447
532
|
const api = await client(values, env, fetchImpl);
|
|
@@ -527,8 +612,9 @@ export async function runAgentCommand(command, argv, deps = {}) {
|
|
|
527
612
|
: command === "inspect" ? await inspect(argv, out, env, deps.fetchImpl)
|
|
528
613
|
: command === "run" ? await run(argv, out, env, timing, deps.fetchImpl)
|
|
529
614
|
: command === "runs" ? await runs(argv, out, env, timing, deps.fetchImpl)
|
|
530
|
-
: command === "
|
|
531
|
-
: await
|
|
615
|
+
: command === "upload" ? await upload(argv, out, env, deps.fetchImpl)
|
|
616
|
+
: command === "balance" ? await balance(argv, out, env, deps.fetchImpl)
|
|
617
|
+
: await keys(argv, out, env, deps);
|
|
532
618
|
if (!json)
|
|
533
619
|
await notice();
|
|
534
620
|
}
|
package/llms-install.md
CHANGED
|
@@ -16,7 +16,7 @@ This read-only command prints the 25 supported client targets. It does not open
|
|
|
16
16
|
a browser or change local configuration:
|
|
17
17
|
|
|
18
18
|
```sh
|
|
19
|
-
npx -y
|
|
19
|
+
npx -y @sandbaseai/cli@latest catalog --json
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
## Install with Homebrew
|
|
@@ -29,20 +29,20 @@ sandbase catalog --json
|
|
|
29
29
|
sandbase connect --client <client-id>
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
The formula installs the
|
|
32
|
+
The formula installs the latest release archive and verifies its published
|
|
33
33
|
SHA-256 before installation.
|
|
34
34
|
|
|
35
35
|
## Connect a client
|
|
36
36
|
|
|
37
|
-
Alternatively, run the
|
|
37
|
+
Alternatively, run the latest GitHub Release directly while npm
|
|
38
38
|
`latest` is being updated:
|
|
39
39
|
|
|
40
40
|
```sh
|
|
41
|
-
npx -y
|
|
41
|
+
npx -y @sandbaseai/cli@latest connect --client <client-id>
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
For an offline
|
|
45
|
-
|
|
44
|
+
For an offline integrity check, compare the tarball against the SHA-256 published
|
|
45
|
+
on its [release page](https://github.com/sandbaseai/cli/releases/latest).
|
|
46
46
|
|
|
47
47
|
Common client IDs include `codex`, `claude-code`, `cursor`, `gemini-cli`,
|
|
48
48
|
`windsurf`, and `opencode`. To configure every supported client detected on the
|
|
@@ -56,7 +56,7 @@ permissions and adds only the SandBase-owned MCP entry.
|
|
|
56
56
|
## Verify
|
|
57
57
|
|
|
58
58
|
```sh
|
|
59
|
-
npx -y
|
|
59
|
+
npx -y @sandbaseai/cli@latest doctor --client <client-id>
|
|
60
60
|
```
|
|
61
61
|
|
|
62
62
|
Restart the target client after a successful connection so it reloads its MCP
|
|
@@ -67,7 +67,7 @@ configuration. The client should then expose six SandBase tools:
|
|
|
67
67
|
## Remove the managed entry
|
|
68
68
|
|
|
69
69
|
```sh
|
|
70
|
-
npx -y
|
|
70
|
+
npx -y @sandbaseai/cli@latest unregister --client <client-id>
|
|
71
71
|
```
|
|
72
72
|
|
|
73
73
|
This removes only the SandBase-owned configuration. It leaves unrelated and
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sandbaseai/cli",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.7",
|
|
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",
|