@wave/cli

Machine-first CLI used by a Node LangGraph agent to execute semantic Wave operations against the Rails API.

See also:

• ./.env.example
• ./docs/ENVIRONMENT_CONTRACT_CHECKLIST.md

Principles

• stdout emits exactly one JSON envelope.
• stderr is for debug/diagnostic logs only.
• No prompts, colors, or interactive UX.
• JWT forwarding is centralized.

Install

npm install @wave/cli

Or run locally:

npm run dev -- tasks list --project-id 123 --organization-id 42 --base-url https://api.example.com --token token

Secure stdin auth/context examples:

printf '%s' "token-value" | wave --token-stdin --base-url https://api.example.com --organization-id 42 tasks list --page 1 --per 10

printf '%s' '{"token":"token-value","baseUrl":"https://api.example.com","organizationId":"42","agentName":"atlas"}' \
  | wave --auth-json-stdin tasks list --page 1 --per 10

Runtime Contract

Required (from flags, stdin, or env):

• WAVE_API_TOKEN
• WAVE_API_BASE_URL
• WAVE_ORGANIZATION_ID

Optional env:

• WAVE_AGENT_NAME
• WAVE_AGENT_RUN_ID
• WAVE_REQUEST_ID
• WAVE_TIMEOUT_MS
• WAVE_DEBUG
• WAVE_OPENAPI_PATH (local contract file, e.g. openapi/wave-cli.yaml)
• WAVE_OPENAPI_URL (hosted contract file)
• WAVE_OPENAPI_VERSION (pinned spec version/hash)

Deterministic precedence:

• explicit flags (--token / --jwt, --base-url, --organization-id, and tracing/runtime flags)
• stdin context (--token-stdin or --auth-json-stdin)
• env vars (WAVE_*)
• failure with structured JSON error

Commands

Examples:

wave tasks list --project-id 123
wave tasks create --project-id 123 --title "Fix auth bug"
wave tasks update --id 99 --status in_progress
wave projects list
wave projects show --id 123
wave rocks update-status --id 55 --status on_track
wave meetings show --id 77
wave members show --id 44
wave meetings notes --id 77 --content "Decisions captured"
wave issues create --issue-group-id 321 --name "Auth issue" --issue-type short_term
wave foundation strategic-plans show
wave foundation strategic-objectives update --data-json '{"strategic_objective":{"summary":"Updated"}}'
wave foundation annual-objectives create --data-json '{"annual_objective":{"strategic_objective_id":"7","name":"Annual Goal"}}'
wave foundation quarterly-objectives create --data-json '{"quarterly_objective":{"strategic_objective_id":"7","annual_objective_id":"8","name":"Quarterly Goal"}}'
wave lists create --data-json '{"name":"Weekly List"}'
wave list-items create --data-json '{"list_id":"123","summary":"Follow up"}'
wave todos create --data-json '{"todo_group_id":"55","name":"Send update"}'
wave knowledge create --data-json '{"title":"Runbook","content":"..."}'
wave pulse update --id 12 --data-json '{"status":"on_track"}'

All commands require organization context via --organization-id or WAVE_ORGANIZATION_ID. You can also provide organizationId via --auth-json-stdin.

Parent-Child Create Rules

These child resources enforce parent IDs at CLI validation time:

• list-items.create requires list_id
• issues.create requires issue_group_id
• todos.create requires todo_group_id
• rocks.create requires rock_collection_id
• scorecards.create requires measurable_group_id

If a required parent field is missing, CLI returns JSON error with exit code 2.

JSON Envelope

Success:

{
  "ok": true,
  "command": "tasks.list",
  "status": 200,
  "data": {},
  "error": null,
  "meta": {
    "requestId": "req_123"
  }
}

Failure:

{
  "ok": false,
  "command": "tasks.create",
  "status": 403,
  "data": null,
  "error": {
    "code": "forbidden",
    "message": "Forbidden",
    "details": {}
  },
  "meta": {
    "requestId": "req_124"
  }
}

Exit Codes

• 0: success
• 1: generic uncaught error
• 2: invalid args/config
• 3: missing or invalid auth
• 4: forbidden
• 5: not found
• 6: validation failure
• 7: network or upstream error