# @surfjs/cli **Inspect, test, and debug Surf-enabled websites from the terminal.** [![npm](https://img.shields.io/npm/v/@surfjs/cli?color=0057FF&label=npm)](https://www.npmjs.com/package/@surfjs/cli) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/hauselabs/surf/blob/main/LICENSE)
--- A command-line tool for working with the [Surf](https://surf.codes) protocol. Discover commands, execute them, and debug your integration — all from your terminal. Part of the **[Surf.js](https://github.com/hauselabs/surf)** ecosystem. ## Installation **Global install** (recommended — gives you the `surf` command everywhere): ```bash npm install -g @surfjs/cli ``` **Run without installing** (via npx): ```bash npx @surfjs/cli inspect https://example.com ``` After installing globally, verify it works: ```bash surf --help ``` > **Note:** If `surf` is not found after global install, your npm global bin directory may not be in your PATH. > Run `npm bin -g` to find it, then add it to your shell profile. ## Commands ### `surf inspect ` Fetch the Surf manifest and pretty-print all available commands: ```bash $ surf inspect https://acme-store.com 🏄 Acme Store (Surf v0.1.0) E-commerce store with 50,000+ products 5 commands available: search(query: string, maxPrice?: number, category?: string) Search products by keyword cart.add(sku: string, qty?: number) 🔐 Add item to cart cart.checkout() 🔐 Complete purchase ``` Use `--verbose` to see full parameter schemas, types, defaults, descriptions, and command hints: ```bash $ surf inspect https://acme-store.com --verbose search(query: string, maxPrice?: number) Search products by keyword Parameters: query — type: string | required maxPrice — type: number | Max price filter Hints: idempotent=true, sideEffects=false, estimatedMs=50 ``` ### `surf test ` Execute a command against a live Surf endpoint. Pass parameters as `--key value` flags: ```bash $ surf test https://acme-store.com search --query "wireless headphones" --maxPrice 100 Executing search on https://acme-store.com... OK [ { "id": "1", "name": "Wireless Headphones", "price": 79.99, "sku": "WH-001" } ] ⏱ 45ms execute / 312ms total ``` **Interactive prompts:** If required parameters are missing, the CLI prompts for them: ```bash $ surf test https://acme-store.com search 🏄 Acme Store → search Search products by keyword query (string) — Search query: wireless headphones Executing search on https://acme-store.com... OK [...] ``` **Parameter coercion:** Values are automatically coerced to the correct type based on the manifest schema (`number`, `boolean`, `string`). ### `surf ping ` Quick check if a site is Surf-enabled: ```bash $ surf ping https://acme-store.com ✅ https://acme-store.com is Surf-enabled (23ms) $ surf ping https://not-surf.com ❌ https://not-surf.com is not Surf-enabled (HTTP 404, 156ms) ``` ## Flags | Flag | Description | |---|---| | `--json` | Machine-readable JSON output (for piping/scripting) | | `--auth ` | Bearer token for authenticated commands | | `--verbose` | Show full parameter schemas and hints (inspect only) | ### JSON Output All commands support `--json` for scripting: ```bash # Inspect $ surf inspect https://example.com --json {"ok":true,"manifest":{...},"ms":234} # Ping $ surf ping https://example.com --json {"ok":true,"status":200,"ms":23} # Test $ surf test https://example.com search --query shoes --json {"ok":true,"result":[...],"timing":{"executeMs":45,"totalMs":312}} ``` ## Examples ```bash # Inspect a site's commands surf inspect https://acme-store.com # Inspect with full details surf inspect https://acme-store.com --verbose # Test a command surf test https://acme-store.com search --query "blue shoes" # Test with auth surf test https://acme-store.com addToCart --sku "WH-001" --quantity 2 --auth "my-token" # Ping check surf ping https://acme-store.com --json # Pipe inspect output surf inspect https://api.example.com --json | jq '.manifest.commands | keys' ``` ## License [MIT](../../LICENSE)