CLI

The wp binary is the fastest developer path into Waypath's external agent surface. It authenticates with a wp_live_... key, lists the capabilities available to that key, invokes them directly, and provides friendly wrappers for the common workflows.

All write-capable wrappers call the capability gateway. They do not call legacy dashboard mutation routes.

01Install

npm i -g @waypath/cli
wp auth login --key wp_live_...
wp doctor

In this monorepo, build the local package with:

npm run build -w @waypath/cli

The package exposes wp, waypath, and wp-mcp binaries.

02Auth

wp auth login --key wp_live_...
wp auth login --key wp_live_... --api-base http://localhost:4747
wp auth whoami

Configuration resolves in this order:

1. WAYPATH_API_KEY, WAYPATH_API_BASE, WAYPATH_WORKSPACE
2. ~/.waypath/config.json
3. https://api.waypath.app

Use global --json for automation:

wp --json auth whoami

03Capability discovery

wp capabilities list
wp capabilities explain context.get

list shows the grant-filtered capabilities available to the active key. explain prints live metadata from GET /api/v1/capabilities: input schema, output schema, examples, grant, allowed modes, side-effect class, cost, approval behavior, MCP tool name, and version.

04Direct invoke

wp invoke context.get \
  --mode execute \
  --input '{"email":"alice@example.com"}'

wp invoke memory.write \
  --mode execute \
  --idempotency-key mem-001 \
  --input '{
    "customer":"alice@example.com",
    "type":"observation",
    "agent":"cli",
    "payload":{"note":"Asked for pricing."},
    "idempotency_key":"mem-001"
  }'

wp invoke queue.outreach \
  --mode queue \
  --file outreach-input.json

wp invoke and wp capabilities invoke both call:

POST /api/v1/capabilities/:id/invoke

The response envelope is the same one API and MCP callers receive:

{
  "status": "queued",
  "result": {},
  "pending_action_id": "pa_123",
  "action_credit_cost": 2,
  "request_id": "req_123",
  "quota": {
    "plan": "starter",
    "limit": 500,
    "used": 42,
    "remaining": 458
  },
  "receipt_url": "/api/v1/capabilities/actions/req_123",
  "pending_receipt_url": "/api/v1/capabilities/pending/pa_123"
}

05Friendly wrappers

06Common workflows

Fetch context:

wp context get jane@acme.com

Write memory:

wp memory write --customer cus_8af2 --body "Requested pricing follow-up."

Ingest an event:

wp events send \
  --type page_view \
  --customer jane@acme.com \
  --props '{"path":"/pricing"}'

Queue outreach:

wp outreach queue cus_8af2 \
  --subject "Following up" \
  --body "Quick note based on your recent activity."

Place a call when grants and AOS policy allow it:

wp calls place cus_8af2 --intent "Follow up on pricing question."

If execute is not allowed, the gateway returns a queued pending action instead of bypassing approval.

07Usage and quota

wp usage actions
wp --json usage actions --limit 5

Quota output includes the plan, monthly limit, used action credits, remaining credits, and recent ledger rows. Quota failures use the same 402 quota_exceeded response shape as API and MCP.

08Key management

The CLI includes key-management commands for dashboard-authenticated operator contexts. Normal wp_live_... agent keys receive 403 on these routes and must not be able to mint or revoke other keys. Use the dashboard or REST with a dashboard JWT when issuing production keys.

wp keys issue "cursor-agent" \
  --agent cursor \
  --scope v1:context:read \
  --grant capability:context.get capability:memory.write \
  --mode dry_run execute

wp keys list
wp keys revoke key_91ab2c

09MCP helpers

wp mcp install
wp mcp start

wp mcp install writes a Claude Desktop config entry that runs @waypath/mcp with the configured WAYPATH_API_KEY and WAYPATH_API_BASE.

10See also

• Quickstart
• Capabilities
• API Keys
• MCP Setup