@surfjs/cli

Inspect, test, and debug Surf-enabled websites from the terminal.

A command-line tool for working with the Surf protocol. Discover commands, execute them, and debug your integration — all from your terminal.

Part of the Surf.js ecosystem.

Installation

Global install (recommended — gives you the surf command everywhere):

npm install -g @surfjs/cli

Run without installing (via npx):

npx @surfjs/cli inspect https://example.com

After installing globally, verify it works:

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 <url>

Fetch the Surf manifest and pretty-print all available commands:

$ 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:

$ 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 <url> <command>

Execute a command against a live Surf endpoint. Pass parameters as --key value flags:

$ 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:

$ 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 <url>

Quick check if a site is Surf-enabled:

$ 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 <token> | Bearer token for authenticated commands | | --verbose | Show full parameter schemas and hints (inspect only) |

JSON Output

All commands support --json for scripting:

# 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

# 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