CLI

CLI#

The @surfjs/cli is a developer tool for building and debugging Surf integrations. It sends HTTP requests to your server — it cannot execute browser-only commands or show UI changes.

The CLI is not an agent interface. Browser agents use window.surf. Headless agents use @surfjs/client. The CLI is for you, the developer.

When to Use the CLI#

surf ping — Verify Your Site Is Surf-Enabled

Quick health check during development or in CI:

surf ping https://shop.example.com
# ✅ https://shop.example.com is Surf-enabled (42ms)

surf inspect — Discover Available Commands

Explore the manifest to verify your commands are registered correctly. The output includes execution hints so you know where each command runs:

surf inspect https://myapp.com
 
# 🏄 My Canvas App (Surf v0.2)
#    5 commands available:
#
#    canvas.addCircle(x, y, radius, fill)  🌐 browser
#    Add circle to canvas
#
#    canvas.getState()                      📡 any
#    Get current canvas state
#
#    canvas.export(width?, height?)         📡 server
#    Export canvas as image
#
#    product.search(query, limit?)          📡 any
#    Search products
#
#    order.create(sku, quantity?)           🔐 server
#    Create an order
 
# Full parameter schemas
surf inspect https://myapp.com --verbose

The icons indicate execution mode:

• 🌐 browser — runs in the browser only
• 📡 any / server — available over HTTP
• 🔐 — requires authentication

surf test — Test Commands During Development

Execute commands from your terminal to verify server-side handlers work:

# Test a search command
surf test https://shop.example.com search --query "laptop"
# Executing search on https://shop.example.com...
#  OK
#  { "results": [...], "total": 42 }
#  ⏱ 47ms execute / 89ms total
 
# Machine-readable output for CI/CD
surf test https://shop.example.com search --query "laptop" --json
 
# Test authenticated commands
surf test https://shop.example.com order.create --auth sk-token --sku LAPTOP-01
 
# For @surfjs/next deployments (custom execute path)
surf test https://my-app.vercel.app search --base-path /api/surf/execute --query "laptop"

Browser-only commands return a helpful error:

$ surf test myapp.com canvas.addCircle --x 400
⚠️  canvas.addCircle requires browser execution
    Open the site and run: await window.surf.execute('canvas.addCircle', { x: 400 })

The CLI prompts for missing required parameters interactively and coerces values to the correct type.

CI/CD — Automated Testing

Use the CLI in your test pipeline to verify Surf endpoints after deployment:

# In your CI pipeline
surf ping https://staging.myapp.com || exit 1
surf test https://staging.myapp.com search --query "test" --json | jq '.ok'

When NOT to Use the CLI#

| Instead of... | Use... | Why | |---------------|--------|-----| | CLI as agent interface | window.surf (browser) or @surfjs/client (headless) | CLI is for development, not production | | CLI for browser-only commands | window.surf in a browser | Browser commands need browser context | | CLI for visual verification | A browser agent that can see the UI | CLI shows JSON, not UI changes | | CLI for production workflows | @surfjs/client with error handling | CLI is not designed for automation |

The CLI sends HTTP requests and prints JSON. It can't show you whether the cart icon updated or a circle appeared on the canvas. For that, you need a browser.

Reference#

| Flag | Description | |------|-------------| | --json | Machine-readable JSON output | | --auth <token> | Bearer token for authenticated commands | | --verbose | Show full parameter schemas (inspect only) | | --base-path <path> | Override execute path (default: /surf/execute). Use /api/surf/execute for @surfjs/next. |