@caravo/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caravo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# Caravo CLI
+
+Command-line interface for [Caravo](https://caravo.ai) — search, execute, and review marketplace tools with API key or x402 USDC payments.
+
+## Install
+
+```bash
+npm install -g @caravo/cli
+```
+
+## Usage
+
+```bash
+# Search for tools
+caravo search "image generation" --per-page 5
+
+# Get tool details
+caravo info fal-ai/flux/schnell
+
+# Execute a tool
+caravo exec fal-ai/flux/schnell -d '{"prompt": "a sunset over mountains"}'
+
+# Preview cost without paying
+caravo dry-run fal-ai/flux/schnell -d '{"prompt": "test"}'
+
+# Submit a review
+caravo review EXECUTION_ID --rating 5 --comment "Great quality"
+
+# Upvote an existing review
+caravo upvote REVIEW_ID --exec EXECUTION_ID
+
+# Manage favorites (requires API key)
+caravo fav list
+caravo fav add fal-ai/flux/schnell
+caravo fav rm fal-ai/flux/schnell
+
+# Check wallet
+caravo wallet
+
+# Raw x402 HTTP
+caravo fetch https://example.com/api
+caravo fetch POST https://example.com/api -d '{"key": "value"}'
+```
+
+## Payment
+
+Payment is transparent — the same commands work in either mode:
+
+- **API key mode**: Set `CARAVO_API_KEY` — balance is deducted per call
+- **x402 USDC mode**: No API key needed. The CLI auto-manages a wallet and signs USDC payments on Base
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `search` | Search tools by query, tag, or provider |
+| `info` | Get tool details, pricing, and reviews |
+| `exec` | Execute a tool |
+| `dry-run` | Preview execution cost |
+| `review` | Submit a review |
+| `upvote` | Upvote an existing review |
+| `fav` | Manage favorites (list, add, rm) |
+| `tags` | List all categories |
+| `providers` | List all providers |
+| `requests` | List tool requests |
+| `request` | Submit a tool request |
+| `request-upvote` | Upvote a tool request |
+| `wallet` | Show wallet address and USDC balance |
+| `fetch` | Raw x402-protected HTTP requests |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm link      # makes `caravo` available globally
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+import { resolveAuth } from "./lib/auth.js";
+import { log } from "./lib/output.js";
+const HELP = `caravo — Caravo CLI
+
+Usage:
+  caravo <command> [args] [options]
+
+Commands:
+  search [query]             Search tools by keyword
+  tags                       List all tags/categories
+  providers                  List all providers
+  info <tool-id>             Get tool details + reviews
+  exec <tool-id> -d <json>   Execute a tool
+  dry-run <tool-id> -d <json> Preview execution cost
+  review <exec-id> --rating <1-5> --comment <text>
+                             Submit a review
+  upvote <review-id> --exec <exec-id>
+                             Upvote a review
+  fav list|add|rm [tool-id]  Manage favorites (API key required)
+  requests                   List tool requests
+  request --title <t> --desc <d>
+                             Submit a tool request
+  request-upvote <req-id>    Upvote a tool request
+  wallet                     Show wallet + balance info
+  fetch [METHOD] <url>       Raw x402 HTTP request
+
+Options:
+  --tag <name|slug>   Filter by tag name or slug (search)
+  --provider <name|slug> Filter by provider name or slug (search)
+  --page <n>          Page number
+  --per-page <n>      Results per page
+  --status <s>        Filter requests by status (open|fulfilled|closed)
+  --rating <1-5>      Review rating
+  --comment <text>    Review comment
+  --exec <id>         Execution ID (for upvote/request)
+  --title <text>      Tool request title
+  --desc <text>       Tool request description
+  --use-case <text>   Tool request use case
+  --agent-id <id>     Agent identifier
+  --api-key <key>     API key (default: $CARAVO_API_KEY)
+  --base-url <url>    API base URL
+  --compact           Compact JSON output (single line)
+  -d, --data <json>   Request body (JSON string)
+  -H, --header <k:v>  Additional header (fetch command, repeatable)
+  -o, --output <file> Write response to file (fetch command)
+  -w, --wallet <path> Custom wallet path
+  -h, --help          Show this help
+  -v, --version       Show version
+`;
+function parseArgs(argv) {
+    const args = {
+        subcommand: "",
+        positional: [],
+        data: null,
+        headers: {},
+        output: null,
+        walletPath: undefined,
+        apiKey: undefined,
+        baseUrl: undefined,
+        compact: false,
+        dryRun: false,
+        help: false,
+        version: false,
+        tag: undefined,
+        provider: undefined,
+        page: undefined,
+        perPage: undefined,
+        rating: undefined,
+        comment: undefined,
+        exec: undefined,
+        title: undefined,
+        desc: undefined,
+        useCase: undefined,
+        status: undefined,
+        agentId: undefined,
+    };
+    let i = 0;
+    // First non-flag arg is the subcommand
+    while (i < argv.length && argv[i].startsWith("-")) {
+        // Handle global flags before subcommand
+        if (argv[i] === "-h" || argv[i] === "--help") {
+            args.help = true;
+        }
+        else if (argv[i] === "-v" || argv[i] === "--version") {
+            args.version = true;
+        }
+        i++;
+    }
+    if (i < argv.length && !argv[i].startsWith("-")) {
+        args.subcommand = argv[i];
+        i++;
+    }
+    // Parse remaining args
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help") {
+            args.help = true;
+        }
+        else if (arg === "-v" || arg === "--version") {
+            args.version = true;
+        }
+        else if (arg === "--compact") {
+            args.compact = true;
+        }
+        else if (arg === "--dry-run") {
+            args.dryRun = true;
+        }
+        else if (arg === "-d" || arg === "--data") {
+            args.data = argv[++i];
+        }
+        else if (arg === "-H" || arg === "--header") {
+            const val = argv[++i];
+            if (val) {
+                const colonIdx = val.indexOf(":");
+                if (colonIdx > 0) {
+                    args.headers[val.slice(0, colonIdx).trim()] = val.slice(colonIdx + 1).trim();
+                }
+            }
+        }
+        else if (arg === "-o" || arg === "--output") {
+            args.output = argv[++i];
+        }
+        else if (arg === "-w" || arg === "--wallet") {
+            args.walletPath = argv[++i];
+        }
+        else if (arg === "--api-key") {
+            args.apiKey = argv[++i];
+        }
+        else if (arg === "--base-url") {
+            args.baseUrl = argv[++i];
+        }
+        else if (arg === "--tag") {
+            args.tag = argv[++i];
+        }
+        else if (arg === "--provider") {
+            args.provider = argv[++i];
+        }
+        else if (arg === "--page") {
+            args.page = argv[++i];
+        }
+        else if (arg === "--per-page") {
+            args.perPage = argv[++i];
+        }
+        else if (arg === "--rating") {
+            args.rating = argv[++i];
+        }
+        else if (arg === "--comment") {
+            args.comment = argv[++i];
+        }
+        else if (arg === "--exec") {
+            args.exec = argv[++i];
+        }
+        else if (arg === "--title") {
+            args.title = argv[++i];
+        }
+        else if (arg === "--desc") {
+            args.desc = argv[++i];
+        }
+        else if (arg === "--use-case") {
+            args.useCase = argv[++i];
+        }
+        else if (arg === "--status") {
+            args.status = argv[++i];
+        }
+        else if (arg === "--agent-id") {
+            args.agentId = argv[++i];
+        }
+        else if (!arg.startsWith("-")) {
+            args.positional.push(arg);
+        }
+        i++;
+    }
+    return args;
+}
+const VERSION = "2.0.0";
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.version) {
+        process.stdout.write(`falm ${VERSION}\n`);
+        process.exit(0);
+    }
+    if (args.help || !args.subcommand) {
+        process.stdout.write(HELP);
+        process.exit(args.help ? 0 : 1);
+    }
+    const auth = resolveAuth({
+        apiKey: args.apiKey,
+        baseUrl: args.baseUrl,
+        walletPath: args.walletPath,
+    });
+    switch (args.subcommand) {
+        case "search": {
+            const { runSearch } = await import("./commands/search.js");
+            // Join all positional args so "falm search image generation" works like "image generation"
+            const query = args.positional.length > 0 ? args.positional.join(" ") : undefined;
+            await runSearch(query, {
+                tag: args.tag,
+                provider: args.provider,
+                page: args.page,
+                perPage: args.perPage,
+            }, auth, args.compact);
+            break;
+        }
+        case "tags": {
+            const { runTags } = await import("./commands/search.js");
+            await runTags(auth, args.compact);
+            break;
+        }
+        case "providers": {
+            const { runProviders } = await import("./commands/search.js");
+            await runProviders(auth, args.compact);
+            break;
+        }
+        case "info": {
+            const { run } = await import("./commands/info.js");
+            await run(args.positional[0], auth, args.compact);
+            break;
+        }
+        case "exec": {
+            const { run } = await import("./commands/exec.js");
+            await run(args.positional[0], args.data, auth, args.compact);
+            break;
+        }
+        case "dry-run": {
+            const { runDryRun } = await import("./commands/exec.js");
+            await runDryRun(args.positional[0], args.data, auth, args.compact);
+            break;
+        }
+        case "review": {
+            const { runReview } = await import("./commands/review.js");
+            await runReview(args.positional[0], {
+                rating: args.rating,
+                comment: args.comment,
+                agentId: args.agentId,
+            }, auth, args.compact);
+            break;
+        }
+        case "upvote": {
+            const { runUpvote } = await import("./commands/review.js");
+            await runUpvote(args.positional[0], args.exec, auth, args.compact);
+            break;
+        }
+        case "fav": {
+            const { run } = await import("./commands/fav.js");
+            await run(args.positional[0], args.positional[1], auth, args.compact);
+            break;
+        }
+        case "requests": {
+            const { runList } = await import("./commands/requests.js");
+            await runList({
+                status: args.status,
+                page: args.page,
+                perPage: args.perPage,
+            }, auth, args.compact);
+            break;
+        }
+        case "request": {
+            const { runRequest } = await import("./commands/requests.js");
+            await runRequest({
+                title: args.title,
+                desc: args.desc,
+                useCase: args.useCase,
+                exec: args.exec,
+                agentId: args.agentId,
+            }, auth, args.compact);
+            break;
+        }
+        case "request-upvote": {
+            const { runUpvote: runReqUpvote } = await import("./commands/requests.js");
+            await runReqUpvote(args.positional[0], args.exec, auth, args.compact);
+            break;
+        }
+        case "wallet": {
+            const { run } = await import("./commands/wallet-cmd.js");
+            await run(auth, args.compact);
+            break;
+        }
+        case "fetch": {
+            const { run } = await import("./commands/fetch.js");
+            await run(args.positional, {
+                data: args.data,
+                headers: args.headers,
+                output: args.output,
+                dryRun: args.dryRun,
+                compact: args.compact,
+            }, auth);
+            break;
+        }
+        default:
+            log(`Unknown command: ${args.subcommand}`);
+            process.stdout.write(HELP);
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    log(`error: ${err instanceof Error ? err.message : err}`);
+    process.exit(1);
+});

package/dist/commands/exec.js

@@ -0,0 +1,72 @@
+import { apiGet, apiPost, validateToolId, normalizeToolId } from "../lib/api.js";
+import { outputJson, log } from "../lib/output.js";
+import { parsePaymentPreview } from "../x402.js";
+export async function run(toolId, data, auth, compact) {
+    if (!toolId) {
+        log("Usage: caravo exec <tool-id> -d '<json>'");
+        process.exit(1);
+    }
+    const err = validateToolId(toolId);
+    if (err) {
+        log(err);
+        process.exit(1);
+    }
+    const normalized = normalizeToolId(toolId);
+    let input = {};
+    if (data) {
+        try {
+            input = JSON.parse(data);
+        }
+        catch {
+            log("Invalid JSON in -d/--data");
+            process.exit(1);
+        }
+    }
+    const result = await apiPost(`/api/tools/${normalized}/execute`, input, auth);
+    outputJson(result.data, compact);
+}
+export async function runDryRun(toolId, data, auth, compact) {
+    if (!toolId) {
+        log("Usage: caravo dry-run <tool-id> [-d '<json>']");
+        process.exit(1);
+    }
+    const err = validateToolId(toolId);
+    if (err) {
+        log(err);
+        process.exit(1);
+    }
+    const normalized = normalizeToolId(toolId);
+    if (auth.mode === "x402") {
+        // Probe execute endpoint for exact x402 cost
+        const url = `${auth.baseUrl}/api/tools/${normalized}/execute`;
+        const resp = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: data || "{}",
+        });
+        if (resp.status === 402) {
+            const preview = parsePaymentPreview(resp);
+            if (preview) {
+                outputJson({
+                    tool_id: toolId,
+                    cost: `$${preview.amount}`,
+                    asset: preview.asset,
+                    pay_to: preview.payTo,
+                    wallet: auth.wallet.address,
+                    mode: "x402",
+                }, compact);
+                return;
+            }
+        }
+        outputJson({
+            tool_id: toolId,
+            status: resp.status,
+            note: "Endpoint did not return 402 payment requirements",
+        }, compact);
+        return;
+    }
+    // API key mode: fetch tool info for pricing
+    const info = await apiGet(`/api/tools/${normalized}`, auth);
+    const pricing = info?.pricing;
+    outputJson({ tool_id: normalized, pricing, mode: "apikey" }, compact);
+}

package/dist/commands/fav.js

@@ -0,0 +1,46 @@
+import { apiGet, apiPost, apiDelete, validateToolId } from "../lib/api.js";
+import { outputJson, log } from "../lib/output.js";
+export async function run(sub, toolId, auth, compact) {
+    if (auth.mode !== "apikey") {
+        log("Favorites require an API key. Set $CARAVO_API_KEY or use --api-key.");
+        process.exit(1);
+    }
+    switch (sub) {
+        case "list": {
+            const data = await apiGet("/api/favorites", auth);
+            outputJson(data, compact);
+            break;
+        }
+        case "add": {
+            if (!toolId) {
+                log("Usage: caravo fav add <tool-id>");
+                process.exit(1);
+            }
+            const err = validateToolId(toolId);
+            if (err) {
+                log(err);
+                process.exit(1);
+            }
+            const { data } = await apiPost("/api/favorites", { tool_id: toolId }, auth);
+            outputJson(data, compact);
+            break;
+        }
+        case "rm": {
+            if (!toolId) {
+                log("Usage: caravo fav rm <tool-id>");
+                process.exit(1);
+            }
+            const err = validateToolId(toolId);
+            if (err) {
+                log(err);
+                process.exit(1);
+            }
+            const data = await apiDelete("/api/favorites", { tool_id: toolId }, auth);
+            outputJson(data, compact);
+            break;
+        }
+        default:
+            log("Usage: caravo fav <list|add|rm> [tool-id]");
+            process.exit(1);
+    }
+}

package/dist/commands/fetch.js

@@ -0,0 +1,71 @@
+import { writeFileSync } from "fs";
+import { fetchWithX402, parsePaymentPreview } from "../x402.js";
+import { outputJson, log } from "../lib/output.js";
+export async function run(positional, opts, auth) {
+    let method;
+    let url;
+    if (positional.length >= 2) {
+        method = positional[0].toUpperCase();
+        url = positional[1];
+    }
+    else if (positional.length === 1) {
+        method = "GET";
+        url = positional[0];
+    }
+    else {
+        log("Usage: caravo fetch [METHOD] <url> [-d '<json>']");
+        process.exit(1);
+    }
+    const headers = { ...opts.headers };
+    if (opts.data && !headers["Content-Type"] && !headers["content-type"]) {
+        headers["Content-Type"] = "application/json";
+    }
+    const fetchOpts = {
+        method,
+        headers,
+        ...(opts.data ? { body: opts.data } : {}),
+    };
+    // --dry-run: probe endpoint for cost without paying
+    if (opts.dryRun) {
+        const resp = await fetch(url, fetchOpts);
+        if (resp.status === 402) {
+            const preview = parsePaymentPreview(resp);
+            if (preview) {
+                outputJson({
+                    dry_run: true,
+                    cost: `$${preview.amount}`,
+                    pay_to: preview.payTo,
+                    wallet: auth.wallet.address,
+                }, opts.compact);
+            }
+            else {
+                const body = await resp.text();
+                outputJson({ dry_run: true, status: 402, body }, opts.compact);
+            }
+        }
+        else {
+            outputJson({
+                dry_run: true,
+                status: resp.status,
+                note: "Endpoint did not return 402",
+            }, opts.compact);
+        }
+        return;
+    }
+    // Make request with automatic x402 payment
+    const { response, paid, cost } = await fetchWithX402(url, fetchOpts, auth.wallet);
+    const body = await response.text();
+    if (paid)
+        log(`paid $${cost} via x402`);
+    if (opts.output) {
+        writeFileSync(opts.output, body);
+        log(`response written to ${opts.output}`);
+    }
+    else {
+        process.stdout.write(body);
+        if (!body.endsWith("\n"))
+            process.stdout.write("\n");
+    }
+    if (!response.ok)
+        process.exit(1);
+}

package/dist/commands/info.js

@@ -0,0 +1,16 @@
+import { apiGet, validateToolId, normalizeToolId } from "../lib/api.js";
+import { outputJson, log } from "../lib/output.js";
+export async function run(toolId, auth, compact) {
+    if (!toolId) {
+        log("Usage: caravo info <tool-id>");
+        process.exit(1);
+    }
+    const err = validateToolId(toolId);
+    if (err) {
+        log(err);
+        process.exit(1);
+    }
+    const normalized = normalizeToolId(toolId);
+    const data = await apiGet(`/api/tools/${normalized}`, auth);
+    outputJson(data, compact);
+}

package/dist/commands/requests.js

@@ -0,0 +1,51 @@
+import { apiGet, apiPost, parsePositiveInt } from "../lib/api.js";
+import { outputJson, log } from "../lib/output.js";
+export async function runList(opts, auth, compact) {
+    const params = new URLSearchParams();
+    if (opts.status)
+        params.set("status", opts.status);
+    if (opts.page) {
+        const p = parsePositiveInt(opts.page, "page");
+        if (p === null)
+            process.exit(1);
+        params.set("page", String(p));
+    }
+    if (opts.perPage) {
+        const pp = parsePositiveInt(opts.perPage, "per-page");
+        if (pp === null)
+            process.exit(1);
+        params.set("per_page", String(pp));
+    }
+    const qs = params.toString();
+    const data = await apiGet(`/api/tool-requests${qs ? `?${qs}` : ""}`, auth);
+    outputJson(data, compact);
+}
+export async function runRequest(opts, auth, compact) {
+    if (!opts.title || !opts.desc) {
+        log("Usage: caravo request --title <title> --desc <description>");
+        process.exit(1);
+    }
+    const body = {
+        title: opts.title,
+        description: opts.desc,
+    };
+    if (opts.useCase)
+        body.use_case = opts.useCase;
+    if (opts.exec)
+        body.execution_id = opts.exec;
+    if (opts.agentId)
+        body.agent_id = opts.agentId;
+    const { data } = await apiPost("/api/tool-requests", body, auth);
+    outputJson(data, compact);
+}
+export async function runUpvote(reqId, execId, auth, compact) {
+    if (!reqId) {
+        log("Usage: caravo request-upvote <request-id> [--exec <execution-id>]");
+        process.exit(1);
+    }
+    const body = {};
+    if (execId)
+        body.execution_id = execId;
+    const { data } = await apiPost(`/api/tool-requests/${reqId}`, body, auth);
+    outputJson(data, compact);
+}

package/dist/commands/review.js

@@ -0,0 +1,43 @@
+import { apiPost } from "../lib/api.js";
+import { outputJson, log } from "../lib/output.js";
+export async function runReview(execId, opts, auth, compact) {
+    if (!execId) {
+        log("Usage: caravo review <execution-id> --rating <1-5> --comment <text>");
+        process.exit(1);
+    }
+    if (!opts.rating || !opts.comment) {
+        log("--rating and --comment are required");
+        process.exit(1);
+    }
+    // Reject floats like "3.5" — parseInt would silently truncate to 3
+    if (opts.rating !== String(parseInt(opts.rating, 10))) {
+        log("--rating must be an integer 1-5");
+        process.exit(1);
+    }
+    const rating = parseInt(opts.rating, 10);
+    if (isNaN(rating) || rating < 1 || rating > 5) {
+        log("--rating must be an integer 1-5");
+        process.exit(1);
+    }
+    const body = {
+        execution_id: execId,
+        rating,
+        comment: opts.comment,
+    };
+    if (opts.agentId)
+        body.agent_id = opts.agentId;
+    const { data } = await apiPost("/api/reviews", body, auth);
+    outputJson(data, compact);
+}
+export async function runUpvote(reviewId, execId, auth, compact) {
+    if (!reviewId || !execId) {
+        log("Usage: caravo upvote <review-id> --exec <execution-id>");
+        process.exit(1);
+    }
+    const body = {
+        review_id: reviewId,
+        execution_id: execId,
+    };
+    const { data } = await apiPost("/api/reviews/upvote", body, auth);
+    outputJson(data, compact);
+}

package/dist/commands/search.js

@@ -0,0 +1,34 @@
+import { apiGet, parsePositiveInt } from "../lib/api.js";
+import { outputJson } from "../lib/output.js";
+export async function runSearch(query, opts, auth, compact) {
+    const params = new URLSearchParams();
+    if (query)
+        params.set("query", query);
+    if (opts.tag)
+        params.set("tag", opts.tag);
+    if (opts.provider)
+        params.set("provider", opts.provider);
+    if (opts.page) {
+        const p = parsePositiveInt(opts.page, "page");
+        if (p === null)
+            process.exit(1);
+        params.set("page", String(p));
+    }
+    if (opts.perPage) {
+        const pp = parsePositiveInt(opts.perPage, "per-page");
+        if (pp === null)
+            process.exit(1);
+        params.set("per_page", String(pp));
+    }
+    const qs = params.toString();
+    const data = await apiGet(`/api/tools${qs ? `?${qs}` : ""}`, auth);
+    outputJson(data, compact);
+}
+export async function runTags(auth, compact) {
+    const data = await apiGet("/api/tags", auth);
+    outputJson(data, compact);
+}
+export async function runProviders(auth, compact) {
+    const data = await apiGet("/api/providers", auth);
+    outputJson(data, compact);
+}

package/dist/commands/wallet-cmd.js

@@ -0,0 +1,48 @@
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { apiGet } from "../lib/api.js";
+import { outputJson } from "../lib/output.js";
+const USDC_ADDRESS = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const USDC_ABI = [
+    {
+        inputs: [{ name: "account", type: "address" }],
+        name: "balanceOf",
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function",
+    },
+];
+async function getUsdcBalance(address) {
+    const client = createPublicClient({ chain: base, transport: http() });
+    const balance = await client.readContract({
+        address: USDC_ADDRESS,
+        abi: USDC_ABI,
+        functionName: "balanceOf",
+        args: [address],
+    });
+    return (Number(balance) / 1_000_000).toFixed(6);
+}
+export async function run(auth, compact) {
+    const info = {
+        mode: auth.mode,
+        wallet_address: auth.wallet.address,
+    };
+    // Check on-chain USDC balance
+    try {
+        info.usdc_balance = `$${await getUsdcBalance(auth.wallet.address)}`;
+    }
+    catch {
+        info.usdc_balance = "unavailable (RPC error)";
+    }
+    // If API key mode, also show platform balance
+    if (auth.mode === "apikey") {
+        try {
+            const profile = (await apiGet("/api/profile", auth));
+            info.api_balance = profile?.balance;
+        }
+        catch {
+            info.api_balance = "unavailable";
+        }
+    }
+    outputJson(info, compact);
+}

package/dist/lib/api.js

@@ -0,0 +1,81 @@
+import { fetchWithX402 } from "../x402.js";
+import { log } from "./output.js";
+/** Normalize a tool ID: trim whitespace, strip trailing slashes, lowercase. */
+export function normalizeToolId(toolId) {
+    return toolId.trim().replace(/\/+$/, "").toLowerCase();
+}
+/** Validate tool_id format: only allow safe chars, no path traversal. */
+export function validateToolId(toolId) {
+    const trimmed = normalizeToolId(toolId);
+    if (!trimmed)
+        return "tool_id must not be empty";
+    if (trimmed.includes(".."))
+        return "Invalid tool_id: path traversal not allowed";
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_./-]*$/.test(trimmed)) {
+        return "Invalid tool_id format: must start with alphanumeric and contain only letters, numbers, hyphens, underscores, dots, and slashes";
+    }
+    if (trimmed.length > 200)
+        return "tool_id too long";
+    return null;
+}
+/** Check if API response is an error and set process exit code accordingly. */
+export function checkResponseError(data, httpStatus) {
+    if (httpStatus >= 400) {
+        process.exitCode = 1;
+        return true;
+    }
+    if (data && typeof data === "object" && "error" in data) {
+        process.exitCode = 1;
+        return true;
+    }
+    return false;
+}
+export async function apiGet(path, auth) {
+    const r = await fetch(`${auth.baseUrl}${path}`, { headers: auth.headers() });
+    const data = await r.json();
+    checkResponseError(data, r.status);
+    return data;
+}
+export async function apiPost(path, body, auth) {
+    const url = `${auth.baseUrl}${path}`;
+    const opts = {
+        method: "POST",
+        headers: auth.headers(),
+        body: JSON.stringify(body),
+    };
+    if (auth.mode === "x402") {
+        const { response, paid, cost } = await fetchWithX402(url, opts, auth.wallet);
+        if (paid)
+            log(`paid $${cost} via x402`);
+        const data = await response.json();
+        checkResponseError(data, response.status);
+        return { data, paid, cost };
+    }
+    const r = await fetch(url, opts);
+    const data = await r.json();
+    checkResponseError(data, r.status);
+    return { data, paid: false, cost: null };
+}
+export async function apiDelete(path, body, auth) {
+    const r = await fetch(`${auth.baseUrl}${path}`, {
+        method: "DELETE",
+        headers: auth.headers(),
+        body: JSON.stringify(body),
+    });
+    const data = await r.json();
+    checkResponseError(data, r.status);
+    return data;
+}
+/** Validate a string is a positive integer. Returns the parsed int or null. */
+export function parsePositiveInt(value, name) {
+    if (value !== String(parseInt(value, 10))) {
+        log(`--${name} must be a positive integer`);
+        return null;
+    }
+    const n = parseInt(value, 10);
+    if (isNaN(n) || n < 1) {
+        log(`--${name} must be a positive integer`);
+        return null;
+    }
+    return n;
+}

package/dist/lib/auth.js

@@ -0,0 +1,23 @@
+import { loadOrCreateWallet } from "../wallet.js";
+const DEFAULT_BASE_URL = "https://caravo.ai";
+export function resolveAuth(args) {
+    const apiKey = args.apiKey || process.env.CARAVO_API_KEY;
+    const baseUrl = args.baseUrl || process.env.CARAVO_URL || DEFAULT_BASE_URL;
+    let cached;
+    return {
+        mode: apiKey ? "apikey" : "x402",
+        apiKey,
+        baseUrl,
+        get wallet() {
+            if (!cached)
+                cached = loadOrCreateWallet(args.walletPath);
+            return cached;
+        },
+        headers() {
+            const h = { "Content-Type": "application/json" };
+            if (apiKey)
+                h["Authorization"] = `Bearer ${apiKey}`;
+            return h;
+        },
+    };
+}

package/dist/lib/output.js

@@ -0,0 +1,7 @@
+export function outputJson(data, compact = false) {
+    const json = compact ? JSON.stringify(data) : JSON.stringify(data, null, 2);
+    process.stdout.write(json + "\n");
+}
+export function log(msg) {
+    process.stderr.write(`[caravo] ${msg}\n`);
+}

package/dist/wallet.js

@@ -0,0 +1,80 @@
+import { randomBytes } from "crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { privateKeyToAccount } from "viem/accounts";
+const WALLET_DIR = join(homedir(), ".caravo");
+const WALLET_FILE = join(WALLET_DIR, "wallet.json");
+/**
+ * Known wallet paths from other MCP servers and web3 services.
+ * On startup we check these in order — if any exist, we reuse that wallet
+ * instead of creating a new one. This avoids fragmenting USDC across
+ * multiple addresses.
+ */
+const KNOWN_WALLET_PATHS = [
+    // Legacy wallet path (pre-rename)
+    join(homedir(), ".fal-marketplace-mcp", "wallet.json"),
+    join(homedir(), ".x402scan-mcp", "wallet.json"),
+    join(homedir(), ".payments-mcp", "wallet.json"),
+];
+function tryLoadWallet(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const data = JSON.parse(readFileSync(path, "utf-8"));
+        if (typeof data.privateKey === "string" &&
+            data.privateKey.startsWith("0x") &&
+            typeof data.address === "string" &&
+            data.address.startsWith("0x")) {
+            return { privateKey: data.privateKey, address: data.address };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Check if a file exists but is not a valid wallet (corrupted/malformed). */
+function isCorruptedWallet(path) {
+    if (!existsSync(path))
+        return false;
+    return tryLoadWallet(path) === null;
+}
+export function loadOrCreateWallet(customPath) {
+    // 0. Custom wallet path takes priority
+    if (customPath) {
+        const custom = tryLoadWallet(customPath);
+        if (custom)
+            return custom;
+        // Distinguish between missing and corrupted
+        if (isCorruptedWallet(customPath)) {
+            process.stderr.write(`[caravo] invalid wallet file at ${customPath} (corrupted or malformed)\n`);
+        }
+        else {
+            process.stderr.write(`[caravo] wallet not found at ${customPath}\n`);
+        }
+        process.exit(1);
+    }
+    // 1. Check our own wallet first
+    const own = tryLoadWallet(WALLET_FILE);
+    if (own)
+        return own;
+    // 2. Check wallets from other known MCPs
+    for (const path of KNOWN_WALLET_PATHS) {
+        const existing = tryLoadWallet(path);
+        if (existing) {
+            mkdirSync(WALLET_DIR, { recursive: true });
+            writeFileSync(WALLET_FILE, JSON.stringify(existing, null, 2), { mode: 0o600 });
+            process.stderr.write(`[caravo] reusing existing wallet from ${path}\n`);
+            return existing;
+        }
+    }
+    // 3. No existing wallet found — generate new
+    const privateKey = ("0x" + randomBytes(32).toString("hex"));
+    const account = privateKeyToAccount(privateKey);
+    const wallet = { privateKey, address: account.address };
+    mkdirSync(WALLET_DIR, { recursive: true });
+    writeFileSync(WALLET_FILE, JSON.stringify(wallet, null, 2), { mode: 0o600 });
+    process.stderr.write(`[caravo] created new wallet: ${account.address}\n`);
+    return wallet;
+}

package/dist/x402.js

@@ -0,0 +1,119 @@
+import { randomBytes } from "crypto";
+import { getAddress } from "viem";
+import { signTypedData } from "viem/actions";
+import { createWalletClient, http } from "viem";
+import { base } from "viem/chains";
+import { privateKeyToAccount } from "viem/accounts";
+const authorizationTypes = {
+    TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+    ],
+};
+async function signPayment(requirements, wallet) {
+    const account = privateKeyToAccount(wallet.privateKey);
+    const client = createWalletClient({ account, chain: base, transport: http() });
+    const now = Math.floor(Date.now() / 1000);
+    const chainId = parseInt(requirements.network.split(":")[1]);
+    const nonce = ("0x" + randomBytes(32).toString("hex"));
+    const authorization = {
+        from: getAddress(account.address),
+        to: getAddress(requirements.payTo),
+        value: BigInt(requirements.amount),
+        validAfter: BigInt(now - 60),
+        validBefore: BigInt(now + requirements.maxTimeoutSeconds),
+        nonce,
+    };
+    const signature = await signTypedData(client, {
+        domain: {
+            name: requirements.extra?.name ?? "USD Coin",
+            version: requirements.extra?.version ?? "2",
+            chainId,
+            verifyingContract: getAddress(requirements.asset),
+        },
+        types: authorizationTypes,
+        primaryType: "TransferWithAuthorization",
+        message: authorization,
+    });
+    return {
+        x402Version: 2,
+        resource: undefined,
+        accepted: requirements,
+        payload: {
+            authorization: {
+                from: authorization.from,
+                to: authorization.to,
+                value: authorization.value.toString(),
+                validAfter: authorization.validAfter.toString(),
+                validBefore: authorization.validBefore.toString(),
+                nonce,
+            },
+            signature,
+        },
+    };
+}
+export async function fetchWithX402(url, options, wallet) {
+    const resp = await fetch(url, options);
+    if (resp.status !== 402) {
+        return { response: resp, paid: false, cost: null };
+    }
+    // Parse payment requirements from header or body
+    let paymentRequired = null;
+    const header = resp.headers.get("payment-required");
+    if (header) {
+        try {
+            paymentRequired = JSON.parse(atob(header));
+        }
+        catch {
+            paymentRequired = null;
+        }
+    }
+    if (!paymentRequired) {
+        try {
+            paymentRequired = await resp.json();
+        }
+        catch {
+            return { response: resp, paid: false, cost: null };
+        }
+    }
+    const requirements = paymentRequired?.accepts?.[0];
+    if (!requirements) {
+        return { response: resp, paid: false, cost: null };
+    }
+    // Sign and retry
+    const paymentPayload = await signPayment(requirements, wallet);
+    const paymentHeader = btoa(JSON.stringify(paymentPayload));
+    const paidResp = await fetch(url, {
+        ...options,
+        headers: {
+            ...options.headers,
+            "X-PAYMENT": paymentHeader,
+        },
+    });
+    // Cost in human-readable dollars (amount is in USDC micro-units, 1e6 = $1)
+    const costDollars = (parseInt(requirements.amount) / 1_000_000).toFixed(6);
+    return { response: paidResp, paid: true, cost: costDollars };
+}
+export function parsePaymentPreview(resp) {
+    const header = resp.headers.get("payment-required");
+    if (!header)
+        return null;
+    try {
+        const pr = JSON.parse(atob(header));
+        const req = pr.accepts?.[0];
+        if (!req)
+            return null;
+        return {
+            amount: (parseInt(req.amount) / 1_000_000).toFixed(6),
+            asset: req.asset,
+            payTo: req.payTo,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@caravo/cli",
+  "version": "0.1.0",
+  "description": "Caravo CLI — search, execute, and review tools with API key or x402 USDC payments",
+  "type": "module",
+  "bin": {
+    "caravo": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --experimental-strip-types src/cli.ts"
+  },
+  "dependencies": {
+    "viem": "^2.28.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.2",
+    "@types/node": "^22"
+  },
+  "keywords": ["caravo", "marketplace", "cli", "x402", "usdc", "base", "agent", "mcp"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Caravo-AI/Caravo-CLI"
+  },
+  "homepage": "https://caravo.ai",
+  "license": "MIT",
+  "files": [
+    "dist/"
+  ]
+}