# 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 command name are both flowrelay-agent. Use npx when you do not want to install it globally.

### 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
```

### Check a grant token
Set the token from the merchant's Agent Access screen before running doctor.

```sh
FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent doctor
```

### Check plan usage
Read published meters before high-volume reads or repeated action previews.

```sh
FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent plan-usage
```

### Read scoped events
Returns JSON and never prints raw private material.

```sh
FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent events --limit 25
```

## Configuration
Set FLOWRELAY_AGENT_BASE_URL to https://api.flowrelay.app for production Agent Operations. Set FLOWRELAY_AGENT_TOKEN to the merchant-authorized Agent Access grant token. You can also pass --base-url for commands that do not need a token.

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

### 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
```

### Doctor
Check grant context, edition identity, docs reachability, manifest reachability, and OpenAPI reachability.

```sh
FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent doctor
```

### Plan usage
Check exact usage meters and enforcement state before loops or high-volume work.

```sh
FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_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_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_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_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent events --limit 25
```

### Replay preview
Create or inspect a replay preview before an approved execution.

```sh
FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent replay-intent <event-id> --json replay.json
```

## 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 doctor with a grant to summarize setup state, next recommended actions, allowed capabilities, blocked capabilities, and safety guidance. Pair that output with the mission playbooks and availability guide before side-effecting commands.

## 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 docs --base-url https://api.flowrelay.app`
- `FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent doctor`
- `FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent plan-usage`
- `FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent create-endpoint --json endpoint.json`
- `FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent events --limit 25`
- `FLOWRELAY_AGENT_BASE_URL=https://api.flowrelay.app FLOWRELAY_AGENT_TOKEN=$FLOWRELAY_AGENT_TOKEN npx flowrelay-agent replay-intent <event-id> --json replay.json`

## Safety Boundary
Do not include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.