@sandbaseai/cli 0.1.14 → 0.3.3

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/dist/cli.js CHANGED
@@ -1,63 +1,95 @@
1
1
  #!/usr/bin/env node
2
- import { connect, doctor, unregister } from "./commands.js";
2
+ import { connect, doctor, setup, unregister } from "./commands.js";
3
3
  import { clientList } from "./clients.js";
4
4
  import { bridgeClients, isBridgeClient, isClient } from "./types.js";
5
5
  import { stableCatalog } from "./catalog.js";
6
+ import { agentUsage, isAgentCommand, runAgentCommand } from "./agent/commands.js";
7
+ import { cliVersion } from "./agent/update.js";
6
8
  if (Number(process.versions.node.split(".")[0]) < 20) {
7
9
  console.error("SandBase CLI requires Node.js 20 or newer. Upgrade Node.js and retry.");
8
10
  process.exit(1);
9
11
  }
10
12
  const [command, ...args] = process.argv.slice(2);
11
- const at = args.indexOf("--client");
12
- const value = at >= 0 ? args[at + 1] : undefined;
13
- const client = value === undefined || value === "auto" ? "auto" : isClient(value) ? value : undefined;
14
- const bridgeClient = value !== undefined && isBridgeClient(value) ? value : undefined;
15
- if (command === "catalog") {
16
- if (args.length !== 1 || args[0] !== "--json") {
17
- console.error("Usage: sandbase catalog --json");
18
- process.exit(2);
19
- }
13
+ const usage = `Usage:
14
+ sandbase connect [--client <client>|auto] Sign in once in the browser and configure your AI clients
15
+ sandbase setup Refresh the local MCP bridge and SandBase Skill after an update, then test connectivity
16
+ sandbase doctor [--client <client>] Check local configuration and make one real round trip to SandBase
17
+ sandbase unregister [--client <client>] Remove SandBase-managed local state
18
+ sandbase --version
19
+
20
+ ${agentUsage}
21
+
22
+ Clients: ${clientList()}`;
23
+ if (command === "--version" || command === "-v" || command === "version") {
24
+ console.log(cliVersion());
25
+ process.exit(0);
20
26
  }
21
- else if (command === "mcp-bridge") {
22
- if (!bridgeClient || at !== 0 || args.length !== 2) {
23
- console.error(`Usage: sandbase mcp-bridge --client <${bridgeClients.join("|")}>`);
24
- process.exit(2);
25
- }
27
+ if (!command || command === "--help" || command === "-h" || command === "help") {
28
+ console.log(usage);
29
+ process.exit(command ? 0 : 2);
26
30
  }
27
- else if (!command || !client || !["connect", "doctor", "unregister"].includes(command) || (at >= 0 && !value)) {
28
- console.error(`Usage: sandbase <connect|doctor|unregister> [--client <${clientList()}|auto>]`);
29
- process.exit(2);
31
+ if (isAgentCommand(command)) {
32
+ process.exitCode = await runAgentCommand(command, args);
30
33
  }
31
- const controller = new AbortController();
32
- const signals = ["SIGINT", "SIGTERM"];
33
- const abort = () => controller.abort();
34
- for (const signal of signals)
35
- process.once(signal, abort);
36
- try {
37
- if (command === "catalog")
38
- process.stdout.write(stableCatalog());
34
+ else {
35
+ const at = args.indexOf("--client");
36
+ const value = at >= 0 ? args[at + 1] : undefined;
37
+ const client = value === undefined || value === "auto" ? "auto" : isClient(value) ? value : undefined;
38
+ const bridgeClient = value !== undefined && isBridgeClient(value) ? value : undefined;
39
+ if (command === "catalog") {
40
+ if (args.length !== 1 || args[0] !== "--json") {
41
+ console.error("Usage: sandbase catalog --json");
42
+ process.exit(2);
43
+ }
44
+ }
39
45
  else if (command === "mcp-bridge") {
40
- const runtime = await import(new URL("../assets/mcp-bridge.mjs", import.meta.url).href);
41
- await runtime.runMCPBridge({ client: bridgeClient, signal: controller.signal });
46
+ if (!bridgeClient || at !== 0 || args.length !== 2) {
47
+ console.error(`Usage: sandbase mcp-bridge --client <${bridgeClients.join("|")}>`);
48
+ process.exit(2);
49
+ }
42
50
  }
43
- else if (command === "connect")
44
- await connect(client, { signal: controller.signal });
45
- else if (command === "doctor") {
46
- if (!(await doctor(client)))
47
- process.exitCode = 1;
51
+ else if (command === "setup") {
52
+ // --client/--email are accepted for parity with agent setup instructions; the CLI never asks for them.
48
53
  }
49
- else
50
- await unregister(client);
51
- }
52
- catch (e) {
53
- const message = e instanceof Error ? e.message : "Unknown failure";
54
- if (message.includes("fetch failed"))
55
- console.error("Authorization response may have been lost. Check SandBase Dashboard for a newly created CLI credential, revoke it if present, then retry.");
56
- else
57
- console.error(message.replace(/(?:sk|cln)-[A-Za-z0-9_-]+/g, "[REDACTED]"));
58
- process.exitCode = 1;
59
- }
60
- finally {
54
+ else if (!client || !["connect", "doctor", "unregister"].includes(command) || (at >= 0 && !value)) {
55
+ console.error(`Usage: sandbase <connect|doctor|unregister> [--client <${clientList()}|auto>]\nRun \`sandbase --help\` for agent commands (discover, inspect, run, runs, balance, keys).`);
56
+ process.exit(2);
57
+ }
58
+ const controller = new AbortController();
59
+ const signals = ["SIGINT", "SIGTERM"];
60
+ const abort = () => controller.abort();
61
61
  for (const signal of signals)
62
- process.removeListener(signal, abort);
62
+ process.once(signal, abort);
63
+ try {
64
+ if (command === "catalog")
65
+ process.stdout.write(stableCatalog());
66
+ else if (command === "mcp-bridge") {
67
+ const runtime = await import(new URL("../assets/mcp-bridge.mjs", import.meta.url).href);
68
+ await runtime.runMCPBridge({ client: bridgeClient, signal: controller.signal });
69
+ }
70
+ else if (command === "setup") {
71
+ if (!(await setup()))
72
+ process.exitCode = 1;
73
+ }
74
+ else if (command === "connect")
75
+ await connect(client, { signal: controller.signal });
76
+ else if (command === "doctor") {
77
+ if (!(await doctor(client)))
78
+ process.exitCode = 1;
79
+ }
80
+ else
81
+ await unregister(client);
82
+ }
83
+ catch (e) {
84
+ const message = e instanceof Error ? e.message : "Unknown failure";
85
+ if (message.includes("fetch failed"))
86
+ console.error("Authorization response may have been lost. Check SandBase Dashboard for a newly created CLI credential, revoke it if present, then retry.");
87
+ else
88
+ console.error(message.replace(/(?:sk|cln)-[A-Za-z0-9_-]+/g, "[REDACTED]"));
89
+ process.exitCode = 1;
90
+ }
91
+ finally {
92
+ for (const signal of signals)
93
+ process.removeListener(signal, abort);
94
+ }
63
95
  }
@@ -27,5 +27,11 @@ export interface CommandDependencies {
27
27
  export declare function openBrowser(url: string): Promise<void>;
28
28
  export declare function connect(client?: ConnectClient, deps?: CommandDependencies): Promise<void>;
29
29
  export declare function doctor(client?: ConnectClient, store?: CredentialStore, detect?: (client: Client) => Detection, skillsRunner?: SkillsCommandRunner, skillsReadbackVerifier?: SkillsReadbackVerifier, openClawRunner?: OpenClawCommandRunner, openClawReadbackVerifier?: OpenClawReadbackVerifier, a1Runner?: A1CommandRunner, bRunner?: BCommandRunner, cRunner?: CCommandRunner): Promise<boolean>;
30
+ /**
31
+ * `sandbase setup`: refresh everything a newer CLI ships without a new browser
32
+ * sign-in — the shared MCP bridge and every SandBase-owned Skill copy — then
33
+ * verify connectivity. User-modified Skills are never overwritten.
34
+ */
35
+ export declare function setup(store?: CredentialStore, log?: (line: string) => void): Promise<boolean>;
30
36
  export declare function unregister(client?: ConnectClient, store?: CredentialStore, detect?: (client: Client) => Detection, skillsRunner?: SkillsCommandRunner, skillsReadbackVerifier?: SkillsReadbackVerifier, openClawRunner?: OpenClawCommandRunner, openClawReadbackVerifier?: OpenClawReadbackVerifier, a1Runner?: A1CommandRunner, bRunner?: BCommandRunner, cRunner?: CCommandRunner): Promise<void>;
31
37
  export {};
package/dist/commands.js CHANGED
@@ -19,6 +19,7 @@ import { claudeDesktopArtifactPath, readClaudeDesktopArtifactState, removeClaude
19
19
  import { coworkStatePath, readCoworkState, removeCoworkState, rollbackCoworkState } from "./cowork.js";
20
20
  import { atomicWrite, readOptional, restore } from "./fs-safe.js";
21
21
  import { configPath } from "./paths.js";
22
+ import { probeEndpoint } from "./agent/probe.js";
22
23
  const sleep = (ms, signal) => new Promise((resolve, reject) => { const t = setTimeout(resolve, ms); signal?.addEventListener("abort", () => { clearTimeout(t); reject(new Error("Authorization cancelled")); }, { once: true }); });
23
24
  async function compensate(api, authorizationId, token) { for (const delay of [0, 250, 750]) {
24
25
  if (delay)
@@ -154,7 +155,7 @@ async function prepareOpenClawSkill(detected, log, runner, verify) {
154
155
  return false;
155
156
  }
156
157
  async function connectOpenClaw(deps) {
157
- const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
158
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://api.sandbase.ai").replace(/\/$/, ""));
158
159
  const store = deps.store || new FileCredentialStore();
159
160
  const log = deps.log || console.log;
160
161
  const detect = deps.detect || detectClient;
@@ -183,7 +184,7 @@ async function connectOpenClaw(deps) {
183
184
  }
184
185
  }
185
186
  async function connectDesktop(client, deps) {
186
- const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
187
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://api.sandbase.ai").replace(/\/$/, ""));
187
188
  const store = deps.store || new FileCredentialStore();
188
189
  const log = deps.log || console.log;
189
190
  const previous = await store.get(client);
@@ -210,7 +211,7 @@ async function connectDesktop(client, deps) {
210
211
  }
211
212
  }
212
213
  async function connectPromptAssisted(client, deps) {
213
- const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
214
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://api.sandbase.ai").replace(/\/$/, ""));
214
215
  const store = deps.store || new FileCredentialStore();
215
216
  const log = deps.log || console.log;
216
217
  const previous = await store.get(client);
@@ -233,7 +234,7 @@ async function connectPromptAssisted(client, deps) {
233
234
  }
234
235
  }
235
236
  async function connectChatGPT(deps) {
236
- const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
237
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://api.sandbase.ai").replace(/\/$/, ""));
237
238
  const store = deps.store || new FileCredentialStore();
238
239
  const log = deps.log || console.log;
239
240
  const previous = await store.get("chatgpt");
@@ -256,7 +257,7 @@ async function connectChatGPT(deps) {
256
257
  }
257
258
  }
258
259
  async function connectOne(client, deps) {
259
- const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
260
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://api.sandbase.ai").replace(/\/$/, ""));
260
261
  const store = deps.store || new FileCredentialStore();
261
262
  const log = deps.log || console.log;
262
263
  const detect = deps.detect || detectClient;
@@ -341,7 +342,7 @@ async function connectOne(client, deps) {
341
342
  }
342
343
  }
343
344
  async function connectAuto(deps) {
344
- const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
345
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://api.sandbase.ai").replace(/\/$/, ""));
345
346
  const store = deps.store || new FileCredentialStore();
346
347
  const log = deps.log || console.log;
347
348
  const detect = deps.detect || detectClient;
@@ -718,6 +719,81 @@ export async function doctor(client = "auto", store = new FileCredentialStore(),
718
719
  console.log(`${target}: status=${status}, mcp=${configured ? "configured" : "not_configured"}, skill=${skill}, invocation=${capability.invocation}, verification=${capability.verification}, shared_skill_references=${references.join(",") || "none"}, next_step=${skillDetail}`);
719
720
  healthy = healthy && detected.installed && !!credential && configured && !["missing", "modified"].includes(skill);
720
721
  }
722
+ if (!(await probeStoredCredentials(targets, store)))
723
+ healthy = false;
724
+ return healthy;
725
+ }
726
+ /**
727
+ * Live runtime checks: flags an outdated shared bridge and makes one real
728
+ * authenticated round trip per distinct stored credential. Skipped with
729
+ * SANDBASE_DOCTOR_NETWORK=0 (offline fixtures and tests).
730
+ */
731
+ async function probeStoredCredentials(targets, store, env = process.env) {
732
+ if (env.SANDBASE_DOCTOR_NETWORK === "0")
733
+ return true;
734
+ let ok = true;
735
+ if (await inspectBridge() === "invalid") {
736
+ console.log("bridge: status=outdated, next_step=The local MCP bridge is from another CLI version. Run `npx -y @sandbaseai/cli@latest setup` to refresh it and the SandBase Skill, then restart your AI client.");
737
+ ok = false;
738
+ }
739
+ const seen = new Set();
740
+ for (const target of targets) {
741
+ let record;
742
+ try {
743
+ record = await store.get(target);
744
+ }
745
+ catch {
746
+ continue;
747
+ }
748
+ if (!record?.credential || !record.mcpUrl || seen.has(record.credential))
749
+ continue;
750
+ seen.add(record.credential);
751
+ const result = await probeEndpoint(target, record.credential, record.mcpUrl, env);
752
+ console.log(result.line);
753
+ ok = ok && result.ok;
754
+ }
755
+ return ok;
756
+ }
757
+ const refreshableSkillClients = ["claude-code", "cursor", "hermes", "kiro"];
758
+ /**
759
+ * `sandbase setup`: refresh everything a newer CLI ships without a new browser
760
+ * sign-in — the shared MCP bridge and every SandBase-owned Skill copy — then
761
+ * verify connectivity. User-modified Skills are never overwritten.
762
+ */
763
+ export async function setup(store = new FileCredentialStore(), log = console.log) {
764
+ let healthy = true;
765
+ const connected = [];
766
+ for (const client of clients) {
767
+ try {
768
+ const record = await store.get(client);
769
+ if (record?.credential)
770
+ connected.push(client);
771
+ }
772
+ catch { /* unreadable store is reported below */ }
773
+ }
774
+ if (connected.length) {
775
+ const bridge = await installBridge();
776
+ log(`bridge: status=${bridge.changed ? "updated" : "current"}, path=${bridge.path}`);
777
+ }
778
+ else
779
+ log(`bridge: status=skipped, next_step=No connected client yet. Run \`npx -y @sandbaseai/cli@latest connect\` to sign in once in the browser.`);
780
+ for (const client of refreshableSkillClients) {
781
+ const state = await inspectSkill(client);
782
+ if (state === "installed") {
783
+ try {
784
+ const result = await installSkill(client);
785
+ log(`${client}: skill=${result.changed ? "updated" : "current"}`);
786
+ }
787
+ catch (error) {
788
+ healthy = false;
789
+ log(`${client}: skill=failed, reason=${safeFailure(error)}`);
790
+ }
791
+ }
792
+ else if (state === "modified")
793
+ log(`${client}: skill=modified, next_step=A locally edited SandBase Skill was left untouched; replace it with https://www.sandbase.ai/skill.md if you want the latest guidance.`);
794
+ }
795
+ if (connected.length && !(await probeStoredCredentials(connected, store)))
796
+ healthy = false;
721
797
  return healthy;
722
798
  }
723
799
  export async function unregister(client = "auto", store = new FileCredentialStore(), detect = detectClient, skillsRunner, skillsReadbackVerifier, openClawRunner, openClawReadbackVerifier, a1Runner, bRunner, cRunner) {
package/dist/skills.js CHANGED
@@ -42,7 +42,7 @@ export function skillFallback(client) {
42
42
  export function skillInvocation(client) { return `${clientProfiles[client].label} has a SandBase Skill artifact installed. Native discovery remains unverified until the real-client matrix is complete.`; }
43
43
  function nativeTier(client) { return skillTiers[client] === "s3_promotion" || skillTiers[client] === "s1_slash"; }
44
44
  function marked(content) { return content.includes(ownershipMarker) && /^name:\s*sandbase\s*$/m.test(content); }
45
- async function asset(relative = "../assets/skills/sandbase/SKILL.md") {
45
+ async function asset(relative = "../skills/sandbase/SKILL.md") {
46
46
  const bundled = fileURLToPath(new URL(relative, import.meta.url));
47
47
  try {
48
48
  return await readFile(bundled, "utf8");
@@ -50,7 +50,7 @@ async function asset(relative = "../assets/skills/sandbase/SKILL.md") {
50
50
  catch (error) {
51
51
  if (error.code !== "ENOENT")
52
52
  throw error;
53
- return readFile(join(process.cwd(), "assets", "skills", "sandbase", "SKILL.md"), "utf8");
53
+ return readFile(join(process.cwd(), "skills", "sandbase", "SKILL.md"), "utf8");
54
54
  }
55
55
  }
56
56
  async function sharedOwnership(env = process.env) {
@@ -0,0 +1,76 @@
1
+ # Install SandBase CLI
2
+
3
+ SandBase CLI is an open-source onboarding tool and local stdio MCP bridge. It
4
+ connects supported AI clients to the SandBase catalog of 2,000+ models and APIs without
5
+ requiring separate provider API keys.
6
+
7
+ ## Requirements
8
+
9
+ - Node.js 20 or newer
10
+ - A graphical browser for the one-time authorization flow
11
+ - A supported client from the catalog below
12
+
13
+ ## Verify before installing
14
+
15
+ This read-only command prints the 25 supported client targets. It does not open
16
+ a browser or change local configuration:
17
+
18
+ ```sh
19
+ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cli-0.1.17.tgz catalog --json
20
+ ```
21
+
22
+ ## Install with Homebrew
23
+
24
+ The official tap supports macOS and Linux:
25
+
26
+ ```sh
27
+ brew install sandbaseai/tap/sandbaseai-cli
28
+ sandbase catalog --json
29
+ sandbase connect --client <client-id>
30
+ ```
31
+
32
+ The formula installs the immutable v0.1.17 archive and verifies its published
33
+ SHA-256 before installation.
34
+
35
+ ## Connect a client
36
+
37
+ Alternatively, run the immutable v0.1.17 GitHub Release directly while npm
38
+ `latest` is being updated:
39
+
40
+ ```sh
41
+ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cli-0.1.17.tgz connect --client <client-id>
42
+ ```
43
+
44
+ For an offline/integrity check, the archive's SHA-256 is
45
+ `1ad535b2899ca460b57b3c268aef278fee28fd28e649a89b92951514fd71fffa`.
46
+
47
+ Common client IDs include `codex`, `claude-code`, `cursor`, `gemini-cli`,
48
+ `windsurf`, and `opencode`. To configure every supported client detected on the
49
+ machine, omit `--client <client-id>`.
50
+
51
+ The command opens the SandBase authorization page. The user must complete that
52
+ step personally. Never ask the user to paste a credential into chat. After
53
+ authorization, the CLI stores the credential locally with restricted file
54
+ permissions and adds only the SandBase-owned MCP entry.
55
+
56
+ ## Verify
57
+
58
+ ```sh
59
+ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cli-0.1.17.tgz doctor --client <client-id>
60
+ ```
61
+
62
+ Restart the target client after a successful connection so it reloads its MCP
63
+ configuration. The client should then expose six SandBase tools:
64
+ `sandbase_discover`, `sandbase_inspect`, `sandbase_run`, `sandbase_run_get`,
65
+ `sandbase_runs`, and `sandbase_account`.
66
+
67
+ ## Remove the managed entry
68
+
69
+ ```sh
70
+ npx -y https://github.com/sandbaseai/cli/releases/download/v0.1.17/sandbaseai-cli-0.1.17.tgz unregister --client <client-id>
71
+ ```
72
+
73
+ This removes only the SandBase-owned configuration. It leaves unrelated and
74
+ user-managed MCP entries unchanged.
75
+
76
+ Source: https://github.com/sandbaseai/cli
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@sandbaseai/cli",
3
- "version": "0.1.14",
4
- "description": "Secure SandBase MCP onboarding CLI",
3
+ "version": "0.3.3",
4
+ "mcpName": "io.github.sandbaseai/cli",
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",
5
6
  "type": "module",
6
7
  "bin": {
7
8
  "sandbase": "dist/cli.js"
@@ -12,12 +13,14 @@
12
13
  "files": [
13
14
  "dist",
14
15
  "assets",
16
+ "skills",
17
+ "llms-install.md",
15
18
  "README.md",
16
19
  "LICENSE"
17
20
  ],
18
21
  "scripts": {
19
22
  "build": "tsc -p tsconfig.json",
20
- "test": "npm run build && tsc -p tsconfig.test.json && node --test dist-test/test/*.test.js",
23
+ "test": "npm run build && tsc -p tsconfig.test.json && node --import ./dist-test/test/setup.js --test dist-test/test/*.test.js",
21
24
  "lint": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
22
25
  "audit:package": "bash scripts/audit-package.sh",
23
26
  "prepack": "npm run build"
@@ -29,9 +32,31 @@
29
32
  "license": "Apache-2.0",
30
33
  "repository": {
31
34
  "type": "git",
32
- "url": "https://github.com/sandbaseai/sandbase.git",
33
- "directory": "sandbase-cli"
35
+ "url": "git+https://github.com/sandbaseai/cli.git"
34
36
  },
37
+ "homepage": "https://github.com/sandbaseai/cli#readme",
38
+ "bugs": {
39
+ "url": "https://github.com/sandbaseai/cli/issues"
40
+ },
41
+ "keywords": [
42
+ "ai",
43
+ "agent",
44
+ "cli",
45
+ "mcp",
46
+ "model-context-protocol",
47
+ "cursor",
48
+ "claude-code",
49
+ "codex",
50
+ "windsurf",
51
+ "gemini-cli",
52
+ "opencode",
53
+ "openclaw",
54
+ "hermes-agent",
55
+ "model-routing",
56
+ "multimodal-ai",
57
+ "developer-tools",
58
+ "automation"
59
+ ],
35
60
  "publishConfig": {
36
61
  "access": "public",
37
62
  "provenance": true
@@ -0,0 +1,182 @@
1
+ ---
2
+ name: sandbase
3
+ version: 0.3.3
4
+ description: >-
5
+ Discover better ways to complete tasks. Proactively search SandBase (the
6
+ sandbase_discover MCP tool, or `sandbase discover` in a shell) before writing a
7
+ scraper, before using a generic web fetch for structured data, before telling
8
+ the user something is inaccessible, and whenever a task needs a capability you
9
+ do not have yourself: image, video, music, or speech generation; social media
10
+ data (X/Twitter, TikTok, Douyin, Xiaohongshu, Instagram, YouTube, Reddit,
11
+ Weibo, Bilibili, LinkedIn); search results; web scraping; product, company, or
12
+ people data; embeddings; or a specific third-party model. 2,000+ models and
13
+ APIs, paid per call from one balance. Exceptions: if the user already has a
14
+ dedicated MCP server, API key, or tool for that specific service, use it; and
15
+ if your built-in web search or page fetch already gives what the task needs,
16
+ use that — SandBase fills gaps in the user's stack, it does not replace it.
17
+ ---
18
+
19
+ # SandBase
20
+
21
+ <!-- sandbase-cli-managed: sandbase -->
22
+
23
+ SandBase gives you 2,000+ models and APIs behind one interface: search the catalog, read a tool's input schema and price, run it, and fetch the result. One balance covers everything; the user never manages provider keys.
24
+
25
+ There are **two transports** with the same capabilities. Pick one before doing anything else.
26
+
27
+ ---
28
+
29
+ ## 1. Pick your transport
30
+
31
+ | Condition | Use | Setup |
32
+ |---|---|---|
33
+ | You have tools named `sandbase_discover`, `sandbase_run`, … | **MCP** (preferred) | None |
34
+ | No `sandbase_*` tools, but you can run shell commands | **CLI** | §3 |
35
+ | The MCP tools return "SandBase is unreachable" | **CLI** for `sandbase doctor`, then tell the user what it reports | §3 |
36
+ | Neither | Tell the user how to connect (§1.1), then stop | — |
37
+
38
+ **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
+
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
+ ---
51
+
52
+ ## 2. Transport A — MCP tools (preferred)
53
+
54
+ Discovery, inspection, run status, and balance are **free**; only `sandbase_run` spends the user's balance.
55
+
56
+ | Tool | What it does |
57
+ |---|---|
58
+ | `sandbase_discover` | Search the catalog in natural language (`q`), optionally filtered by `type` (`llm`, `api`, `multimodal`, `embedding`, `service`) or `vendor` |
59
+ | `sandbase_inspect` | Input schema (`inputSchema`), pricing, and an `execute_as` template for one tool |
60
+ | `sandbase_run` | Execute a tool (**costs money**) |
61
+ | `sandbase_run_get` | Status, cost, and output of a run — poll with this |
62
+ | `sandbase_runs` | Recent runs with cost |
63
+ | `sandbase_account` | Balance |
64
+ | `sandbase_run_cancel` | Cancel an Agent Service run |
65
+
66
+ ### MCP workflow
67
+
68
+ 1. `sandbase_discover({"q": "twitter posts"})` → pick a `tool_name` from `data` (each result carries `description`, `pricing`, `vendor`, `run_count`).
69
+ 2. `sandbase_inspect({"name": "sandbase_twitter_web_search_timeline"})` → read `inputSchema` and `pricing`; copy `execute_as`.
70
+ 3. `sandbase_run({"name": "sandbase_twitter_web_search_timeline", "arguments": {"keyword": "AI agents"}})`. There are two kinds of tools:
71
+ - **Sync** (LLMs, most data APIs): the call waits for the upstream and returns `status: "completed"` with `output` directly.
72
+ - **Async** (image, video, audio, other long jobs): the call returns at once with `status: "running"` and a `run_id` (also `prediction_id` / `taskId`).
73
+ 4. For an async run, call `sandbase_run_get({"run_id": "<run_id>"})` every 5–10 seconds until `status` is `completed` or `failed`; the finished `output` is in that response. A run that has finished but is still copying its files also reports `running` — keep polling. Never call `sandbase_run` again for the same job (that starts and bills a new run).
74
+
75
+ **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
+
77
+ ---
78
+
79
+ ## 3. Transport B — CLI (fallback)
80
+
81
+ ```sh
82
+ sandbase --version || npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz --version
83
+ ```
84
+
85
+ If `sandbase` is not installed, prefix every command with `npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz` (or install it: `npm install -g https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz`). If the CLI prints "Update available", run `npx -y https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz setup` — it refreshes the CLI's MCP bridge and this Skill.
86
+
87
+ **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
+
89
+ | Need | MCP tool | CLI |
90
+ |---|---|---|
91
+ | Search | `sandbase_discover` | `sandbase discover -q "<query>" [-t api] [-l 10]` |
92
+ | Schema + price | `sandbase_inspect` | `sandbase inspect <tool_name>` |
93
+ | Execute | `sandbase_run` | `sandbase run <tool_name> -i '<json>' [-w] [-o result.json]` (or `-f input.json`) |
94
+ | Poll / fetch result | `sandbase_run_get` | `sandbase runs get -r <run_id> [-w] [-o result.json]` |
95
+ | Recent runs | `sandbase_runs` | `sandbase runs list` |
96
+ | Balance | `sandbase_account` | `sandbase balance` |
97
+ | Diagnose connectivity | — | `sandbase doctor` |
98
+ | **Save output to a file** | not available | `-o result.json` on `run` / `runs get` |
99
+
100
+ - Add `-j` for JSON output. Errors then look like `{"error": {"code", "message", "hint"}}`; follow `hint`.
101
+ - `-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/URLs in the output are also listed in text mode.
103
+ - Exit code is `0` on success or still-running, `1` on failure (including a failed run), `2` on bad usage.
104
+ - 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
+ - To store an API key without exposing it: `printf %s "$KEY" | sandbase keys add -k -`.
106
+
107
+ ---
108
+
109
+ ## 4. When to use SandBase — and when not
110
+
111
+ **Check the catalog before building from scratch.** Before writing a scraper, falling back to a generic web fetch for structured data, or telling the user you cannot access something, run a discover. The catalog grows continuously; you don't know what is there until you search.
112
+
113
+ **Fill gaps, don't replace the user's stack.** Precedence:
114
+
115
+ 1. An explicit user instruction for this task.
116
+ 2. The user's own dedicated tools: their MCP servers, API keys, CLIs, workflows.
117
+ 3. Your built-in web search / fetch, when plain pages or snippets are enough.
118
+ 4. SandBase, for whatever the above don't cover: structured data (posts, profiles, reviews, products), media generation, specific models, or when built-in tools are blocked or return unusable pages.
119
+
120
+ SandBase runs spend the user's balance; never spend it on something their own tool already does for free. When both could work and the user hasn't chosen, use theirs and mention SandBase only if it adds something.
121
+
122
+ Do not use SandBase for purely local work (editing files, reasoning over code already in context).
123
+
124
+ ---
125
+
126
+ ## 5. Search tips
127
+
128
+ - Short noun phrases work best: `twitter posts`, `text to video`, `amazon product reviews`, `web scraping`.
129
+ - Chinese works and aliases are expanded: `推特`, `小红书`, `抖音`, `文生视频`, `图片生成`.
130
+ - Narrow with `type` (`llm`, `api`, `multimodal`, `embedding`, `service`) or `vendor` (`openai`, `twitter`, `kling`).
131
+ - Split multi-source tasks: one discover per source ("twitter posts", then "reddit posts"), then run each.
132
+ - Zero results come with `hints`; read them before rephrasing.
133
+
134
+ ---
135
+
136
+ ## 6. Cost and budget
137
+
138
+ - `inspect` shows the price: per call (`base_price`), per million tokens (`input_per_million` / `output_per_million`), or a `formula`.
139
+ - Many data endpoints are billed **per result** and 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).
140
+ - Check `sandbase_account` before a batch of paid calls, and report cost when the user cares about budget (`cost` appears on `sandbase_run_get` and `sandbase_runs`).
141
+ - Never re-run a slow tool just because it is still running; poll it.
142
+
143
+ ---
144
+
145
+ ## 7. Errors
146
+
147
+ Tool failures come back as error results whose text names the cause **and the next step**. Read it and act on it.
148
+
149
+ | Message contains | Do this |
150
+ |---|---|
151
+ | "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 https://github.com/sandbaseai/cli/releases/latest/download/sandbaseai-cli.tgz connect`. |
153
+ | "insufficient" / 402 | Tell the user to top up at https://www.sandbase.ai/console/billing. |
154
+ | "not found" / "unknown tool" | Re-run `sandbase_discover`; copy `tool_name` exactly. |
155
+ | "invalid params" / schema | Re-run `sandbase_inspect`; pass exactly its `inputSchema` fields. |
156
+ | "upstream" / "provider" / "capability call failed" | Retry once, then pick another tool from discover. |
157
+ | 429 / rate limit | Wait 10–30 seconds, retry once. |
158
+
159
+ ---
160
+
161
+ ## 8. Hints
162
+
163
+ Responses may include `hints` (and `warnings`): suggested next steps, caveats, or alternatives from the server. Read them before deciding your next move and prefer them over guessing.
164
+
165
+ ---
166
+
167
+ ## 9. Rules for agents
168
+
169
+ 1. **Check the user's stack first, then discover.** Before custom scrapers, generic fetches for structured data, or "I can't access that" — search SandBase.
170
+ 2. **Never route around the user's own tools.** SandBase costs money; theirs may not.
171
+ 3. **Prefer MCP when connected**; use the CLI when MCP is missing or broken, or to write large outputs to disk.
172
+ 4. **Always inspect before running.** Never guess parameters; `inputSchema` is the source of truth.
173
+ 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.
175
+ 7. **Start with conservative limits** (5–10 results).
176
+ 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. **Tool schemas and `sandbase --help` are authoritative** if they disagree with this document.
179
+
180
+ 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
+
182
+ This file is managed by SandBase CLI and is replaced by `sandbase setup` / `sandbase connect` unless you edit it; keep custom instructions in a separate Skill. Latest copy: https://www.sandbase.ai/skill.md