@vapi-network/cli 0.2.3 → 0.5.0

package/README.md

@@ -1,6 +1,14 @@
-# @vapi-network/cli
+# `@vapi-network/cli`
 
-The command-line interface used by the `vapi-network` distribution. It keeps
-the wallet key encrypted on the local machine and signs x402 payments locally.
+The command implementations behind the `vapi` binary of
+[vAPI Network](https://github.com/vAPI-Network/vapi-network): wallet management,
+discovery, payment, receipts, the OS secret store and the MCP launcher. The
+wallet key stays encrypted on the local machine and every x402 payment is signed
+locally.
+
+Two entry points: `@vapi-network/cli` exports `runCli` and the `HELP` text for
+embedding, and `@vapi-network/cli/cli` is the executable itself.
 
 Most users should install or run the unscoped `vapi-network` package instead.
+See the [root README](https://github.com/vAPI-Network/vapi-network#readme) for
+the full command reference.

package/dist/agent.d.ts

@@ -0,0 +1,14 @@
+import { listAgentProfiles, readAgentProfile, readSpendLedgerRows, removeAgentProfile, writeAgentProfile } from "@vapi-network/core";
+import { createAgentRunDeps, getWallet, runAgent } from "@vapi-network/mcp";
+import { type CliDependencies, type CliIo } from "./cli.js";
+export type AgentCommandDependencies = {
+    readAgentProfile?: typeof readAgentProfile;
+    writeAgentProfile?: typeof writeAgentProfile;
+    listAgentProfiles?: typeof listAgentProfiles;
+    removeAgentProfile?: typeof removeAgentProfile;
+    readSpendLedgerRows?: typeof readSpendLedgerRows;
+    createAgentRunDeps?: typeof createAgentRunDeps;
+    runAgent?: typeof runAgent;
+    getWallet?: typeof getWallet;
+};
+export declare function agentCommand(argv: string[], json: boolean, io: CliIo, dependencies: CliDependencies): Promise<number>;

package/dist/check.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `vapi check <url>`: a free, local x402 conformance doctor. It asks the URL
+ * for its price the way a client would, without paying, and grades the 402
+ * rule by rule, including its advertised extensions; then it looks for the
+ * origin's discovery document and an OpenAPI description beside the checked
+ * path, at the origin root, or through the origin's API catalog. No wallet is
+ * opened, nothing is signed, and no registry is called: every request goes to
+ * the origin being checked.
+ *
+ * Offer issue codes use the registry's snake_case `probe.conformance`
+ * vocabulary, so `vapi check` and `vapi inspect` speak one language. The local
+ * extensions finding does not change that registry-shaped record.
+ */
+import { type ListingConformance } from "@vapi-network/core";
+export type CheckResult = "pass" | "warn" | "fail";
+export type CheckRule = {
+    rule: string;
+    result: CheckResult;
+    detail: string;
+    issues: string[];
+};
+export type CheckReport = {
+    url: string;
+    method: string;
+    status: number;
+    /** Which payment protocol the 402 speaks; absent when the response is not a 402 or carries neither. */
+    transport?: "x402" | "mpp";
+    /** The same record the registry keeps per listing; null when there is no offer to grade. */
+    conformance: ListingConformance | null;
+    /** Known x402 extensions advertised by the declared offer, in a stable order. */
+    extensions: string[];
+    rules: CheckRule[];
+    summary: Record<CheckResult, number>;
+};
+export type MppChallenge = {
+    intent?: string;
+    method?: string;
+};
+export declare function checkX402(target: URL, options: {
+    method: string;
+    fetchImpl: typeof fetch;
+}): Promise<CheckReport>;
+/** One line per rule, then the tally. */
+export declare function formatCheckReport(report: CheckReport): string;
+/** Finds the MPP scheme and keeps only the challenge fields used in check output. */
+export declare function parseMppChallenge(headerValue: string | null): MppChallenge | undefined;

package/dist/cli.d.ts

@@ -1,10 +1,142 @@
-export declare const HELP = "vAPI Network\n\nUsage:\n  vapi init [--networks <base,solana>] [--json]\n  vapi fund [--amount <usd>] [--json]\n  vapi accounts [--enable solana] [--json]\n  vapi search [query] [--kind <kind>] [--network <caip2>] [--limit <n>] [--cursor <cursor>] [--json]\n  vapi inspect <id> [--endpoint <name>] [--json]\n  vapi pay <id-or-url> [--method <method>] [--endpoint <name>] [--body <json>] [--content-type <type>] [--network <caip2>] [--expected-pay-to <address>] [--max <amount>] [--json]\n  vapi balance [--json]\n  vapi receipts [--limit <n>] [--json]\n  vapi receipts export --format <json|csv> [--range <24h|7d|30d>]\n  vapi stats [--range <24h|7d|30d>] [--json]\n  vapi sweep <address> [--network <caip2>] [--json]\n  vapi export-key [--network <caip2>] [--json]\n  vapi report \"<what happened>\" [--include-addresses] [--send] [--json]\n  vapi mcp [--json]\n  vapi serve [--json]\n  vapi version [--json]\n  vapi publish [--json]\n\nWith no command, vapi shows this help. The MCP server starts only with `vapi mcp`.";
+import { sweepBack, WalletStore, type AuditEvent, type ListingVerification, type SecretStore, type VapiConfig, type VapiPaymentAccount, type WalletEntry, type WalletName } from "@vapi-network/core";
+import { type pollDeviceLink, type startDeviceLink } from "@vapi-network/core/agent-link";
+import type { buyRouterBalance, listRouterModels, ownerStake, rotateRouterKey, routerChat, routerCredentials, routerUsage } from "@vapi-network/core/router-client";
+import { type AgentCommandDependencies } from "./agent.js";
+export declare const HELP = "vAPI Network\n\nUsage:\n  vapi init [--networks <base,arc,solana>] [--json]\n  vapi wallet list [--json]\n  vapi wallet create <name> [--networks <base,arc,solana>] [--label <text>] [--json]\n  vapi wallet use <name> [--json]\n  vapi wallet rename <old> <new> [--json]\n  vapi wallet remove <name> [--force] [--json]\n  vapi wallet restore <name> [--json]\n  vapi wallet caps <name> [--per-call <usd>] [--per-day <usd>] [--json]\n  vapi fund [--amount <usd>] [--wallet <name>] [--json]\n  vapi accounts [--enable <solana|arc>] [--wallet <name>] [--json]\n  vapi search [query] [--kind <kind>] [--network <caip2>] [--limit <n>] [--cursor <cursor>] [--include-unverified] [--json]\n  vapi inspect <id> [--endpoint <name>] [--json]\n  vapi pay <id-or-url> [--method <method>] [--endpoint <name>] [--body <json>] [--content-type <type>] [--network <caip2>] [--expected-pay-to <address>] [--max <amount>] [--wallet <name>] [--json]\n  vapi pay --resume <receipt-id> [--json]\n  vapi check <url> [--method <method>] [--json]\n  vapi balance [--wallet <name>] [--json]\n  vapi receipts [--limit <n>] [--wallet <name>] [--all-wallets] [--json]\n  vapi receipts export --format <json|csv> [--range <24h|7d|30d>] [--wallet <name>] [--all-wallets]\n  vapi stats [--range <24h|7d|30d>] [--wallet <name>] [--all-wallets] [--json]\n  vapi sweep [<address>] [--network <caip2>] [--wallet <name>] [--json]\n  vapi agent create <name> --model <id> --instructions <file> [--call-budget <usd>] [--max-per-call <usd>] [--router-budget <usd>] [--approve-above <usd>] [--include-unverified] [--max-steps <n>] [--json]\n  vapi agent run <name> \"<task>\" [--json]\n  vapi agent list [--json]\n  vapi agent pause <name> [--json]\n  vapi agent resume <name> [--json]\n  vapi agent revoke <name> [--json]\n  vapi login [--wallet <name>] [--label <name>] [--publish] [--no-browser] [--json]\n  vapi logout [--wallet <name>] [--json]\n  vapi whoami [--wallet <name>] [--json]\n  vapi router models [--wallet <name>] [--json]\n  vapi router usage [--wallet <name>] [--json]\n  vapi router chat --model <id> [--system <text>] [--max-tokens <n>] \"<prompt>\" [--wallet <name>] [--json]\n  vapi router buy <1|5|20|50> [--wallet <name>] [--json]\n  vapi router buy --auto <1|5|20|50> --below <usd> [--wallet <name>] [--json]\n  vapi router buy --auto off [--wallet <name>] [--json]\n  vapi router key [--rotate] [--wallet <name>] [--json]\n  vapi stake status [--wallet <name>] [--json]\n  vapi stake open [--wallet <name>] [--no-browser] [--json]\n  vapi export-key [--network <caip2>] [--wallet <name>] [--json]\n  vapi backup [--wallet <name>] [--json]\n  vapi import (--phrase | --key) [--wallet <name>] [--networks <base,arc,solana>] [--replace] [--force] [--json]\n  vapi passphrase [--wallet <name>] [--json]\n  vapi unlock [--wallet <name>] [--json]\n  vapi lock [--wallet <name> | --all] [--json]\n  vapi report \"<what happened>\" [--include-addresses] [--send] [--json]\n  vapi auth set-key [--json]\n  vapi auth status [--json]\n  vapi auth clear [--json]\n  vapi publish <url> [--method <method>] [--mode <origin|endpoint|openapi>] [--name <text>] [--description <text>] [--category <ai|data|crypto|compute|search>] [--select <names>] [--wallet <name>] [--yes] [--resume] [--json]\n  vapi publish activate <slug> [--json]\n  vapi publish verify-request <slug> [--json]\n  vapi publish list [--json]\n  vapi claim <origin> [--wallet <name>] [--json]\n  vapi mcp [--wallet <name>] [--json]\n  vapi serve [--json]\n  vapi version [--json]\n  vapi help [--json]\n\nEvery command that touches a wallet takes `--wallet <name>`, falls back to `VAPI_WALLET`, then to the default set by `vapi wallet use`, and names the wallet it used on its first line.\n\n`vapi search` answers with vAPI-verified listings plus the mirrored external catalogs. `--include-unverified` also returns self-listed APIs that passed vAPI's automated x402 probe but were never reviewed; every result is tagged `[verified]`, `[requested]`, `[unverified]` or `[external]`.\n\n`vapi check <url>` grades an x402 API's 402 without paying: status, transport, declared version and its required fields, the exact scheme, canonical USDC, payTo, maxTimeoutSeconds, advertised extensions, and the origin's /.well-known/x402. It looks for OpenAPI beside the checked path, at /openapi.json, then through same-origin service-desc links in /.well-known/api-catalog. No wallet, no payment, no registry call. It exits 1 when a rule fails. A 402 that answers with Stripe/Tempo's MPP challenge (WWW-Authenticate: Payment) is recognised and reported as transport mpp; vapi pay cannot pay it.\n\n`vapi pay --resume <receipt-id>` answers the one question a lost response leaves: did that payment settle? It reads the signed authorization's state on-chain \u2014 settled, expired, or still pending \u2014 and never pays.\n\n`vapi fund` opens the funding page: card via Coinbase (needs a Coinbase account; US guest checkout), send from MetaMask/Coinbase Wallet/WalletConnect, or bridge from another chain.\n\n`vapi unlock` keeps one wallet's passphrase in the OS secret store \u2014 the macOS Keychain, or libsecret on Linux \u2014 so an agent can pay without `VAPI_KEYSTORE_PASSWORD` in its configuration. `vapi lock` takes it out again. Unlock order: `VAPI_KEYSTORE_PASSWORD`, then the secret store, then a prompt on a terminal. Windows still needs the variable.\n\n`vapi backup` and `vapi export-key` print a secret, so they run only on a real terminal, never for an agent, and ask you to type the wallet name first. Set `VAPI_NO_SECRETS=1` to switch them off entirely. Every export and every wallet change is logged to ~/.vapi/audit.log.\n\n`vapi publish <url>` lists an API you own. vAPI probes the URL \u2014 an origin, one endpoint, or an OpenAPI document \u2014 you choose which endpoints to list, and your wallet signs one line naming where the payouts go. Listing is permissionless: a listing that passed the probe goes live with `vapi publish activate <slug>`, and `vapi publish verify-request <slug>` asks for the review that puts it in the default search. Deploying the FeeSplitter that receives the payouts is a wallet transaction and stays in the console. A catalog of more than 20 endpoints is listed as several listings of up to 20, with one result line per endpoint; `--resume` skips every endpoint this key already lists.\n\n`vapi claim <origin>` takes ownership of the listings vAPI indexed from your API. The wallet their payments go to signs one line, `Claim the vAPI Call listings served from <origin>`; the listings stay paid directly to that wallet, and `vapi publish list` shows them.\n\n`vapi auth set-key` types the registry API key once, on a terminal, into the same OS secret store as the passphrase. A key is a secret: it is never an argument, `VAPI_API_KEY` is the route for CI, and no agent or MCP tool can reach it.\n\nWith no command, vapi shows this help. The MCP server starts only with `vapi mcp`.";
 export type CliIo = {
     stdout(message: string): void;
     stderr(message: string): void;
 };
+/** Every secret the CLI reads is read here, so tests never touch a terminal. */
+export type CliPrompts = {
+    /** Reads one line from the terminal without echoing it. */
+    secret(prompt: string): Promise<string>;
+    /**
+     * Reads one visible line, for a typed confirmation such as a wallet name.
+     * Never used for a secret, so it may echo.
+     */
+    line?(prompt: string): Promise<string>;
+};
 export type CliDependencies = {
     fetchImpl?: typeof fetch;
+    prompts?: CliPrompts;
+    /** Whether a person is watching. Only then is a recovery phrase shown. */
+    interactive?: boolean;
+    /** The environment this run sees: wallet selection and agent detection. */
+    env?: NodeJS.ProcessEnv;
+    /** The OS secret store `vapi unlock` and `vapi lock` act on. */
+    secretStore?: SecretStore;
+    /** Injected clock, so a signed message is reproducible in a test. */
+    now?: () => Date;
+    /** Device-link operations, injected so tests never touch the account service. */
+    agentLink?: {
+        startDeviceLink?: typeof startDeviceLink;
+        pollDeviceLink?: typeof pollDeviceLink;
+        forgetAgentLink?: typeof import("@vapi-network/core/agent-link").forgetAgentLink;
+    };
+    /** Router operations, injected so CLI tests never make service requests. */
+    router?: {
+        listRouterModels?: typeof listRouterModels;
+        routerUsage?: typeof routerUsage;
+        routerChat?: typeof routerChat;
+        buyRouterBalance?: typeof buyRouterBalance;
+        rotateRouterKey?: typeof rotateRouterKey;
+        ownerStake?: typeof ownerStake;
+        routerCredentials?: typeof routerCredentials;
+    };
+    /** Agent profile and run operations, injected so tests stay local and deterministic. */
+    agent?: AgentCommandDependencies;
+    /** Reads stdin to EOF for `vapi router chat ... -`. */
+    readStdin?: () => Promise<string>;
+    /** Opens one public URL in the platform browser. */
+    openUrl?: (url: string) => boolean;
+    /** Moves a wallet balance, injected for deterministic sweep command tests. */
+    sweepBack?: typeof sweepBack;
+};
+export declare class UsageError extends Error {
+}
+export declare function getEnvironment(dependencies: CliDependencies): NodeJS.ProcessEnv;
+/** The wallet one invocation acts on, resolved before any passphrase is read. */
+export type WalletTarget = {
+    store: WalletStore;
+    name: WalletName;
+    path: string;
+    entry: WalletEntry;
+    address?: string;
 };
+/** Opens the store and picks the wallet in one step, for the usual command. */
+export declare function targetWallet(parsed: {
+    one(name: string): string | undefined;
+}, dependencies: CliDependencies): Promise<WalletTarget>;
+/** The OS secret store this run uses: the machine's, or the one a test injects. */
+export declare function getSecretStore(dependencies: CliDependencies): SecretStore;
+/** Opens the selected wallet, and keeps the passphrase for callers that need it. */
+export declare function unlockTarget(target: WalletTarget, dependencies: CliDependencies): Promise<{
+    account: VapiPaymentAccount;
+    passphrase: string;
+}>;
+/** One audit line. The home is the wallet store's, so `VAPI_HOME` is honoured. */
+export declare function recordAudit(dependencies: CliDependencies, event: AuditEvent, options?: {
+    wallet?: string;
+    detail?: string;
+}): Promise<void>;
+/**
+ * The gate in front of `vapi backup` and `vapi export-key`: refuse, log the
+ * attempt, and say which stream or which variable decided it. Nothing is
+ * printed to stdout, so a caller capturing it gets nothing either way.
+ */
+export declare function requireSecretsAllowed(dependencies: CliDependencies, event: AuditEvent, wallet: string | undefined, options?: {
+    refusal?: string;
+    forcedReason?: string;
+}): Promise<void>;
 /** Run one CLI invocation and return its process exit code. */
 export declare function runCli(argv?: string[], io?: CliIo, dependencies?: CliDependencies): Promise<number>;
+/**
+ * Creates another wallet on this machine, with the same custody notice, the
+ * same passphrase confirmation and the same one-time phrase as `vapi init`.
+ * No network call: a fresh wallet has nothing to look up.
+ */
+export declare function walletCreateCommand(argv: string[], json: boolean, io: CliIo, dependencies: CliDependencies): Promise<void>;
+/** Per-wallet spend caps, in US dollars, converted to atomic USDC on the way in. */
+export declare function walletCapsCommand(argv: string[], json: boolean, io: CliIo, dependencies: CliDependencies): Promise<void>;
+/**
+ * The registry behind the configured discovery URLs. `VAPI_REGISTRY_URL` has
+ * already moved those by the time the config is loaded, so deriving the base
+ * from them follows the env override, a self-hosted registry and a mount
+ * prefix alike. A hand-edited discovery URL falls back to the shipped default.
+ */
+export declare function registryBaseUrl(config: VapiConfig): string;
+/**
+ * The short word for how far a listing got through vAPI review. A mirrored
+ * external row is called `external` rather than `unverified`: vAPI reviewed
+ * nothing it merely mirrored, and saying "unverified" would read as a verdict
+ * on a catalog vAPI never claimed to judge.
+ */
+export declare function verificationTag(listing: {
+    verification?: ListingVerification;
+    external?: boolean;
+}): "verified" | "requested" | "unverified" | "external";
+/**
+ * One line, above the result, when the listing that was just paid is not
+ * vAPI-verified. It never blocks and never prompts: the payment has already
+ * happened, and the point is that the next one is an informed choice.
+ */
+export declare function verificationNotice(verification: ListingVerification | undefined): string[];
+/**
+ * Open a funding URL without ever failing the command: a headless or locked-down
+ * machine simply keeps the printed link.
+ */
+export declare function openInBrowser(url: string): boolean;
+type ArgumentSpec = {
+    valueOptions: Set<string>;
+    booleanOptions?: Set<string>;
+    repeatableOptions?: Set<string>;
+    maximumPositionals: number;
+};
+export declare function parseArguments(argv: string[], spec: ArgumentSpec): {
+    positionals: string[];
+    one: (name: string) => string | undefined;
+    many: (name: string) => string[];
+    has: (name: string) => boolean;
+};
+export {};