# FlowRelay CLI Reference Canonical: https://docs.flowrelay.app/reference/cli/ Markdown: https://docs.flowrelay.app/reference/cli.md JSON-first CLI wrapper over Agent Operations, including docs discovery and doctor commands. ## 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 . All examples reference a token via an environment variable and never embed a real token value. ### Read public status This reads aggregate public status without an Agent Access token. It is not merchant-specific. ```sh npx flowrelay-agent status --base-url https://api.flowrelay.app ``` ### Discover docs without a token This prints docs, Markdown, manifest, OpenAPI, CLI, and MCP pointers. Use the Skills page for installable skill sources. ```sh npx flowrelay-agent docs --base-url https://api.flowrelay.app ``` ### Single-grant identity check Use environment variables directly when a named profile is not needed. ```sh FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent whoami ``` ### Check a store profile Use one non-secret profile per store-scoped grant and verify identity before acting. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent whoami ``` ### Check plan usage Read usage meters before high-volume reads or repeated action previews. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent plan-usage ``` ### Read scoped events Returns JSON and never prints raw private material. ```sh 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. ### Profile config Place this in FLOWRELAY_AGENT_CONFIG, $XDG_CONFIG_HOME/flowrelay-agent/profiles.json, or ~/.config/flowrelay-agent/profiles.json. ```json { "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_..." } } } ``` ### Verify selected store The CLI sends expected-context headers when the profile includes expected store context. ```sh 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. ### Public status Read aggregate FlowRelay service status. This is public, unmetered, and not tenant-specific. ```sh npx flowrelay-agent status --base-url https://api.flowrelay.app ``` ### Docs discovery Print the docs index, Markdown links, manifest URL, OpenAPI URL, and reference URLs. ```sh npx flowrelay-agent docs --base-url https://api.flowrelay.app ``` ### Whoami Confirm the selected profile belongs to the intended store before acting. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent whoami ``` ### Doctor Check grant context, edition identity, docs reachability, manifest reachability, and OpenAPI reachability. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent doctor ``` ### Plan usage Check exact usage meters and enforcement state before loops or high-volume work. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent plan-usage ``` ### Create endpoint Read the trigger mapping reference first, then submit a JSON payload with triggerVariant and the correct resource path fields. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent create-endpoint --json endpoint.json ``` ### Event history Read scoped event history as JSON without exposing raw private material. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent events --limit 25 ``` ### Replay preview Create or inspect a replay preview before an approved execution. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent replay-intent --json replay.json ``` ### Expansion request Record non-binding future-edition or platform demand only when it is tied to FlowRelay's automation boundary. ```sh FLOWRELAY_AGENT_PROFILE=client-a FLOWRELAY_CLIENT_A_TOKEN=$FLOWRELAY_CLIENT_A_TOKEN npx flowrelay-agent expansion-request --json expansion-request.json ``` ### Feature request Use the advanced request wrapper for missing FlowRelay capabilities inside the current product surface. ```sh 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 with an agent for a new lane and Endpoint swap plan for an existing sender, receiver, webhook, or endpoint lane. These guides tell agents to inventory the current lane, 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 secrets, raw event bodies, full authentication headers, HMAC values, Shopify tokens, sessions, database URLs, or customer data. Use diagnostics IDs and redacted summaries instead. ## Example Surface - `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 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 --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` ## Safety Boundary Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.