CLI Usage

The fyrn CLI (@fyrn/cli) is the primary tool for creating, testing, deploying, and managing integration flows from your terminal. When invoked with no arguments, it launches an interactive AI-powered assistant.

# Install
npm install -g @fyrn/cli

# Log in (opens browser for Auth0 PKCE)
fyrn login

# Check auth status
fyrn auth status

# Log out
fyrn logout

For CI/CD environments:

fyrn auth api-key --api-key sk-your-key --api-url https://api.fyrn.dev

Config files

File	Purpose
`~/.fyrn/credentials.json`	Auth tokens from `fyrn login`
`~/.fyrn/config.json`	API key and URL from `fyrn auth api-key`
`~/.fyrn/history`	Interactive mode history (max 500 lines)
`fyrn.config.json`	Per-project config (API URL, account ID)
`fyrn.config.local.json`	Local overrides (gitignored)

Authentication — `fyrn auth`

fyrn auth login

Stores access token and refresh token to ~/.fyrn/credentials.json. Verifies by calling /api/v1/auth/me.

fyrn auth logout

Clear stored credentials.

fyrn auth logout

fyrn auth status

Show current authentication status — method, token validity, expiration, source.

fyrn auth status

fyrn auth api-key

Authenticate with an API key for CI/CD environments.

Flag	Description
`--api-key <key>`	API key (or enter interactively if omitted)
`--api-url <url>`	Control plane URL

fyrn auth api-key --api-key sk-abc123 --api-url https://api.fyrn.dev
fyrn auth api-key   # interactive prompt

Project — `fyrn init`, `fyrn pull`, `fyrn push`, `fyrn diff`

fyrn init

Initialize a fyrn project in the current directory.

fyrn init

Creates fyrn.config.json, flows/ directory, and adds fyrn.config.local.json to .gitignore.

fyrn pull [flow-name]

Pull flow configs from the server to local YAML files.

Argument	Description
`[flow-name]`	Optional — pulls all flows if omitted

Flag	Description
`--force`	Overwrite local changes without warning

fyrn pull                  # pull all flows
fyrn pull my-flow          # pull one flow
fyrn pull --force          # overwrite local

fyrn push [flow-name]

Push local YAML files to the server as drafts.

Argument	Description
`[flow-name]`	Optional — pushes all flows if omitted

fyrn push                  # push all flows
fyrn push my-flow          # push one flow

fyrn diff [flow-name]

Compare local YAML files against deployed versions. Shows colored unified diff.

Argument	Description
`[flow-name]`	Optional — diffs all flows if omitted

fyrn diff                  # diff all flows
fyrn diff my-flow          # diff one flow

Flows — `fyrn flow`

All flow subcommands accept --env <environment> to target a specific environment (defaults to current).

fyrn flow list

List all flows with name, status, version, and description.

fyrn flow list
fyrn flow list --env staging

fyrn flow show <flow-id>

Show details of a flow — ID, status, version, description, timestamps, webhook URL, and YAML config.

fyrn flow show abc123

fyrn flow create <description>

Create a flow from a natural language description. AI generates the YAML, you review and confirm.

Flag	Description	Default
`--error-handling <level>`	`conservative`, `standard`, or `aggressive`	`standard`

fyrn flow create "Sync Shopify orders to NetSuite"
fyrn flow create "Forward webhook events to Slack" --error-handling conservative

fyrn flow deploy <flow-id>

Deploy a flow. Validates, compiles, and activates it. Outputs the flow ID, version, and webhook URL (if applicable).

fyrn flow deploy abc123

fyrn flow test <flow-file>

Test a flow locally with sample data. Parses the YAML, compiles the flow, and applies the mapping to the sample data.

Flag	Description	Required
`--sample-data <file>`	Path to sample JSON data file	Yes

fyrn flow test flows/my-flow.yaml --sample-data sample.json

fyrn flow clone <flow-id>

Clone an existing flow to another environment.

Flag	Description	Required
`--to <env>`	Target environment	Yes
`--env <environment>`	Source environment	No

fyrn flow clone abc123 --to staging
fyrn flow clone abc123 --to production --env development

fyrn flow diff <flow-a> <flow-b>

Compare two flows side-by-side. Shows a colored unified diff of their YAML configs.

fyrn flow diff abc123 def456
fyrn flow diff abc123 def456 --env production

fyrn flow delete <flow-id>

Soft-delete a flow. The flow is marked as deleted and can be restored by support if needed.

fyrn flow delete abc123
fyrn flow delete abc123 --env staging

Connectors — `fyrn connector`

fyrn connector list

List all connectors with name, type, status, and flow count.

fyrn connector list

fyrn connector catalog

Browse the connector catalog with name, type, auth method, and description.

fyrn connector catalog

fyrn connector instances

List all connector instances with name, status, config summary, and last tested time.

fyrn connector instances

fyrn connector test <id>

Test a connector instance connection.

fyrn connector test abc123

fyrn connector build [url-or-description]

Build a private connector from API documentation using AI. Point it at an API docs URL or describe the API in plain text.

Flag	Description
`--name <name>`	Connector name
`--spec <path>`	Path to an OpenAPI/Swagger spec file

fyrn connector build "https://docs.acme.com/api"
fyrn connector build "Acme CRM REST API with OAuth2" --name acme-crm
fyrn connector build --spec ./openapi.yaml --name acme-crm

fyrn connector connect <instance>

Start OAuth authorization for a connector instance. Opens a browser to complete the OAuth flow.

fyrn connector connect shopify-main

fyrn connector status <instance>

Show OAuth connection status for a connector instance — token validity, expiration, and scopes.

fyrn connector status shopify-main

Logs — `fyrn logs`

fyrn logs tail <flow-id>

Stream live message logs via SSE. Press Ctrl+C to stop.

Flag	Description
`--status <status>`	Filter by delivery status

fyrn logs tail abc123
fyrn logs tail abc123 --status failed

fyrn logs search <flow-id>

Search message logs.

Flag	Description	Default
`--status <status>`	Filter by delivery status
`--since <duration>`	Messages since (e.g., `1h`, `30m`, `7d`)
`--search <text>`	Search in payload content
`--limit <n>`	Max results	`20`

Duration strings: s (seconds), m (minutes), h (hours), d (days). Non-matching values are treated as ISO date-time strings.

fyrn logs search abc123
fyrn logs search abc123 --status failed --since 1h
fyrn logs search abc123 --search "order_id" --limit 50

fyrn logs replay <message-id>

Replay a message through the full pipeline.

fyrn logs replay msg-abc123

Schedules — `fyrn schedules`

fyrn schedules list

List all schedules with flow, cron expression, timezone, enabled state, next run, and last status.

fyrn schedules list

fyrn schedules trigger <flow-name>

Manually trigger a scheduled flow. Accepts flow name (case-insensitive) or flow ID.

fyrn schedules trigger my-flow
fyrn schedules trigger abc123

Adapters — `fyrn adapters`

Custom code adapters run JavaScript in sandboxed V8 isolates for non-standard data transformations.

fyrn adapters list

List all adapters with name, type, AI-generated flag, last test, and created date.

fyrn adapters list

fyrn adapters generate <description>

Generate an adapter with AI from a natural language description.

Flag	Description	Default
`--type <type>`	`request_transform`, `response_transform`, `auth`, `enrichment`, `full`	`request_transform`
`--sample <json>`	Sample input JSON

fyrn adapters generate "Convert XML order to JSON format"
fyrn adapters generate "Add HMAC signature header" --type auth
fyrn adapters generate "Flatten nested address fields" --sample '{"address":{"street":"123 Main"}}'

fyrn adapters test <adapter-id>

Test an adapter with sample input.

Flag	Description	Required
`--input <json>`	JSON input payload	Yes

fyrn adapters test abc123 --input '{"order_id": "12345"}'

fyrn adapters templates

List available pre-built adapter templates.

fyrn adapters templates

Lookup tables — `fyrn lookup`

fyrn lookup list

List all lookup tables with name, description, version, and created date.

fyrn lookup list

fyrn lookup show <id>

Show a lookup table and its entries.

Flag	Description	Default
`-s, --search <query>`	Search entries by key or value
`-l, --limit <n>`	Max entries to display	`20`

fyrn lookup show abc123
fyrn lookup show abc123 --search "US" --limit 50

fyrn lookup create <name>

Create a new lookup table.

Flag	Description
`-d, --description <text>`	Table description

fyrn lookup create country-codes
fyrn lookup create country-codes --description "ISO country code mappings"

fyrn lookup delete <id>

Delete a lookup table.

fyrn lookup delete abc123

fyrn lookup set <id> <key> <value>

Add or update an entry in a lookup table.

fyrn lookup set abc123 US "United States"

fyrn lookup remove <id> <key>

Delete an entry from a lookup table.

fyrn lookup remove abc123 US

fyrn lookup import <id> <file>

Import entries from a CSV file. Requires key and value columns.

fyrn lookup import abc123 country-codes.csv

fyrn lookup export <id>

Export a lookup table as CSV to stdout.

fyrn lookup export abc123
fyrn lookup export abc123 > countries.csv

Bundles — `fyrn bundle`

Export and import flow bundles as ZIP files for backup or cross-environment migration.

fyrn bundle export <flow-name>

Export a flow as a ZIP bundle.

Flag	Description
`-o, --output <file>`	Output file path (default: `<flow-name>.zip`)

fyrn bundle export my-flow
fyrn bundle export my-flow --output /tmp/my-flow-bundle.zip

fyrn bundle import <file>

Import a flow from a ZIP bundle. Displays imported flow, lookup tables, and warnings.

fyrn bundle import my-flow.zip

Self-healing — `fyrn healing`

Manage self-healing events. When fyrn detects an API schema change, it auto-generates a fix and creates a healing event for review.

fyrn healing list

List healing events.

Flag	Description
`--status <status>`	Filter by status (`pending`, `approved`, `rejected`)
`--flow <flow-id>`	Filter by flow

fyrn healing list
fyrn healing list --status pending
fyrn healing list --flow abc123

fyrn healing show <id>

Show full details of a healing event — the detected change, proposed fix, and diff.

fyrn healing show heal-abc123

fyrn healing approve <id>

Approve a healing event and apply the proposed fix.

fyrn healing approve heal-abc123

fyrn healing reject <id>

Reject a healing event. The flow remains unchanged.

fyrn healing reject heal-abc123

Governance — `fyrn governance`

Manage governance policies. Alias: fyrn gov.

fyrn governance list

List all governance policies.

fyrn governance list
fyrn gov list

fyrn governance show <id>

Show details of a governance policy.

fyrn governance show policy-abc123

fyrn governance check [flow-id]

Run governance checks against a flow, or all flows.

Flag	Description
`--all`	Check all flows

fyrn governance check abc123
fyrn gov check --all

AI agents — `fyrn agents`

Manage AI agent API keys and monitor agent activity.

fyrn agents keys list

List all agent API keys.

fyrn agents keys list

fyrn agents keys create

Create a new agent API key.

Flag	Description
`--name <name>`	Key name
`--tier <tier>`	Access tier
`--rate-limit <n>`	Requests per minute
`--daily-quota <n>`	Daily request quota
`--sandbox`	Restrict to sandbox environment
`--approval`	Require approval for destructive actions

fyrn agents keys create --name "CI bot" --tier standard --rate-limit 60
fyrn agents keys create --name "Dev agent" --sandbox --approval --daily-quota 1000

fyrn agents keys update <key-id>

Update an existing agent API key.

Flag	Description
`--name <name>`	Update key name
`--tier <tier>`	Update access tier
`--approval`	Toggle approval requirement

fyrn agents keys update ak-abc123 --tier premium
fyrn agents keys update ak-abc123 --name "Production bot" --approval

fyrn agents keys revoke <key-id>

Revoke an agent API key. This is immediate and irreversible.

fyrn agents keys revoke ak-abc123

fyrn agents activity

View recent agent activity.

Flag	Description
`--key <key-id>`	Filter by key
`--tool <tool>`	Filter by tool used
`--status <status>`	Filter by status
`--limit <n>`	Max results

fyrn agents activity
fyrn agents activity --key ak-abc123 --limit 50
fyrn agents activity --tool flow.create --status failed

Published APIs — `fyrn apis`

Manage APIs published through fyrn.

fyrn apis list

List all published APIs.

fyrn apis list

fyrn apis docs <name>

Open interactive API documentation for a published API.

fyrn apis docs orders-api

fyrn apis spec <name>

Output the OpenAPI spec for a published API.

Flag	Description	Default
`-f, --format <format>`	Output format (`json` or `yaml`)	`yaml`
`-o, --output <file>`	Write to file instead of stdout

fyrn apis spec orders-api
fyrn apis spec orders-api -f json -o openapi.json

Environments — `fyrn env`

Manage environments.

fyrn env list

List all environments.

fyrn env list

fyrn env switch <name-or-slug>

Switch the active environment.

fyrn env switch staging
fyrn env switch prod

fyrn env current

Show the current active environment.

fyrn env current

fyrn env create <name>

Create a new environment.

Flag	Description
`--color <hex>`	Environment color for the dashboard

fyrn env create staging
fyrn env create qa --color "#f59e0b"

Accounts — `fyrn accounts`

Manage accounts (for users with access to multiple accounts).

fyrn accounts list

List all accounts you have access to.

fyrn accounts list

fyrn accounts switch <name-or-id>

Switch the active account.

fyrn accounts switch acme-corp
fyrn accounts switch acc-abc123

fyrn accounts current

Show the current active account.

fyrn accounts current

Billing — `fyrn billing`

Manage billing and subscription.

fyrn billing status

Show current billing status — plan, usage, and renewal date.

fyrn billing status

fyrn billing upgrade <plan>

Upgrade to a new plan.

Flag	Description
`--annual`	Switch to annual billing

fyrn billing upgrade pro
fyrn billing upgrade enterprise --annual

fyrn billing portal

Open the billing portal in your browser to manage payment methods and invoices.

fyrn billing portal

Usage and plan — `fyrn usage`, `fyrn plan`

fyrn usage

Show current usage vs plan limits — flows, messages, connectors, and API calls.

fyrn usage

fyrn plan

Show current plan details — name, limits, features, and renewal date.

fyrn plan

Interactive mode

Run fyrn with no arguments to launch an AI-powered conversational assistant (powered by Claude). The assistant can list flows, create flows, deploy, manage connectors, search message logs, and more — all through natural language.

fyrn

History is stored at ~/.fyrn/history (max 500 lines).

Common workflows

Generate → validate → deploy

fyrn flow create "Sync orders from Shopify to my ERP system"
# Review the generated YAML, confirm
fyrn flow deploy <flow-id>

Pull → edit → push → deploy

fyrn pull my-flow
# Edit flows/my-flow.yaml in your editor
fyrn diff my-flow          # review changes
fyrn push my-flow          # upload as draft
fyrn flow deploy <flow-id> # activate

Test locally before deploying

fyrn flow test flows/my-flow.yaml --sample-data test-data.json

Monitor a running flow

fyrn flow list                              # see all flows and status
fyrn flow show <flow-id>                    # flow details
fyrn logs tail <flow-id>                    # live log stream
fyrn logs search <flow-id> --status failed  # find failures
fyrn logs replay <message-id>               # replay a failed message

Manage lookup tables

fyrn lookup create country-warehouses --description "Maps countries to warehouse IDs"
fyrn lookup set <id> US warehouse-east-01
fyrn lookup set <id> FI warehouse-eu-01
fyrn lookup import <id> countries.csv
fyrn lookup export <id> > backup.csv