FlowRelay CLI Reference

What the CLI is for #

The CLI is a JSON-first wrapper over Agent Operations for docs discovery, environment checks, safe reads, and approved action previews. It points users and agents back to public docs for product meaning.

Install and first command #

The npm package and the command are both named flowrelay-agent. Run it without a global install using npx flowrelay-agent <command>.

All examples reference a token via an environment variable and never embed a real token value.

npx flowrelay-agent status --base-url https://api.flowrelay.app

npx flowrelay-agent docs --base-url https://api.flowrelay.app

FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent whoami

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent whoami

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent plan-usage

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent events --limit 25

Configuration #

For public aggregate status, use flowrelay-agent status without an Agent Access token. For store-scoped Agent Operations, set FLOWRELAY_AGENT_BASE_URL to https://api.flowrelay.app and FLOWRELAY_AGENT_TOKEN to the merchant-authorized Agent Access grant token. For agency, partner, or recurring operator work, prefer one named profile per store-scoped grant. A profile stores baseUrl, tokenEnv, and optional expected platform/store context; it never stores the token value.

Store profiles #

Profiles let an agency or partner work across multiple client stores while keeping each store's authorization separate. Each Shopify store keeps its own FlowRelay platform account, installation, Shopify-billed plan, usage, secrets, diagnostics, replay controls, audit, and Agent Access grants. Before changing setup or recovery state, run whoami with the selected profile, confirm the returned platform account, shop, and installation match the intended store, then read plan usage.

{
  "profiles": {
    "client-a": {
      "baseUrl": "https://api.flowrelay.app",
      "tokenEnv": "FLOWRELAY_CLIENT_A_TOKEN",
      "expectedPlatformKey": "shopify_flow",
      "expectedPlatformAccountId": "flr_pac_...",
      "expectedShopDomain": "client-a.myshopify.com",
      "expectedInstallationId": "flr_st_..."
    }
  }
}

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent whoami

Common commands #

Use these documented commands for docs discovery, environment checks, plan usage, endpoint setup, scoped event reads, and approved replay previews.

npx flowrelay-agent status --base-url https://api.flowrelay.app

npx flowrelay-agent docs --base-url https://api.flowrelay.app

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent whoami

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent doctor

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent plan-usage

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent create-endpoint --json endpoint.json

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent events --limit 25

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent replay-intent <event-id> --json replay.json

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent expansion-request --json expansion-request.json

FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent request POST /agent/v1/feature-requests --json feature-request.json

Support and product-demand requests #

The CLI includes first-class helpers for support-request previews/submits and expansion requests. Feature requests use the same Agent Operations contract but do not have a bespoke CLI shortcut yet; discover feature_request_submit through docs, doctor, manifest metadata, OpenAPI, or MCP, then submit through the advanced request command or direct API. Expansion and feature-request responses are recorded for review and must not be represented as product commitments.

Agent setup and endpoint swap guides #

Before endpoint setup or migration work, use Set up a new event path with an agent for a new path and Move an existing event path with an agent for an existing sender, receiver, webhook, or endpoint path. These guides tell agents to inventory the current path, choose one safe pilot endpoint, check plan fit, stop for operator approval before sender URL/auth or Shopify Flow changes, prove FlowRelay accepted and handed off one event, then summarize monitoring cadence, rollback, stop conditions, and unresolved approvals.

Output rules #

Use JSON output for agents and scripts. Human-friendly output still includes stable docs URLs, refusal reasons, and the next safe action when a command cannot proceed.

Mission and availability #

Use the CLI docs command for public discovery, then use whoami and doctor with the selected profile to summarize store identity, setup state, next recommended actions, allowed capabilities, blocked capabilities, and safety guidance. Pair that output with the mission playbooks and availability guide before commands that change setup or recovery state.

Safety boundary #

The CLI does not print retained raw private material by default: no raw event bodies, full authentication headers, HMAC values, Shopify tokens, sessions, database URLs, or customer data. Endpoint creation is the deliberate exception: create-endpoint returns the newly created endpoint secret once in its JSON response. Run it only in a trusted secret-capable client, capture the secret into the sender's private secret store, and do not paste or log the response.