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.

Binary: fyrn
NPM package: @fyrn/cli
Default API URL: https://api.fyrn.ai
Node requirement: >= 22.0.0

Installation

npm install -g @fyrn/cli

Or without installing:

npx @fyrn/cli --help

Authentication

Interactive (developer laptops)

fyrn login          # opens Auth0 PKCE flow in a browser
fyrn auth status    # show current identity
fyrn logout         # clear credentials

Tokens are stored at ~/.fyrn/credentials.json (mode 0600). fyrn login and fyrn auth login are equivalent; same for logout.

API key (CI/CD, scripts, agents)

Prefer the FYRN_API_KEY environment variable — the CLI reads it directly, no config file is written, and the key never touches the CI runner’s disk. Get the key from the dashboard under Settings → Agent Keys.

export FYRN_API_KEY=sk-your-agent-key
fyrn flow list

If you want a persistent key on a workstation (not recommended for CI), write it to ~/.fyrn/config.json via:

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

--api-url is optional; the default is https://api.fyrn.ai.

Environment variables

Variable	Required	Default	Description
`FYRN_API_KEY`	CI only	—	Agent API key. Takes precedence over `~/.fyrn/config.json`.
`FYRN_API_URL`	No	`https://api.fyrn.ai`	Control-plane base URL.
`FYRN_AUTH0_DOMAIN`	No	`fyrn.eu.auth0.com`	Override Auth0 domain (local dev).
`FYRN_AUTH0_CLI_CLIENT_ID`	No	built-in	Override Auth0 PKCE client ID (local dev).
`FYRN_AUTH0_AUDIENCE`	No	`https://api.fyrn.ai`	Override Auth0 audience (local dev).
`ANTHROPIC_API_KEY`	No	—	Required for `fyrn` interactive mode (AI assistant).
`BRAVE_SEARCH_API_KEY`	No	—	Optional web search in interactive mode.

The CLI also loads .env files — first the nearest .env walking up from cwd, then ~/.fyrn/.env as a global fallback. Real environment variables always win over .env values.

Configuration files

Path	Purpose
`~/.fyrn/config.json`	API key, API URL, Auth0 overrides, active account/environment
`~/.fyrn/credentials.json`	OAuth tokens from `fyrn login`
`~/.fyrn/.env`	Global env-var fallback
`.env` (project)	Per-project env-var overrides
`fyrn.config.json`	Per-project configuration
`fyrn.config.local.json`	Local overrides (gitignored)

Where a command takes --env, the value can be an environment name or slug; the CLI resolves it to a UUID before calling the API.

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

fyrn init

Initialize a fyrn project in the current directory. Creates fyrn.config.json, a flows/ directory, and adds fyrn.config.local.json to .gitignore.

fyrn init

fyrn pull [flow-name]

Pull remote flow(s) to flows/. Pulls all flows if flow-name is omitted.

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

fyrn pull
fyrn pull my-flow
fyrn pull --force

fyrn push [flow-name]

Push local flow(s) to the control plane as drafts.

fyrn push
fyrn push my-flow

fyrn diff [flow-name]

Show differences between local and remote flow YAML as a colored unified diff.

fyrn diff
fyrn diff my-flow

Flows — `fyrn flow`

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

fyrn flow list

fyrn flow list
fyrn flow list --env staging

fyrn flow show <flow-id>

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

fyrn flow show abc123

fyrn flow create “<description>”

Generate a flow from natural language (AI). Review and confirm the generated YAML.

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>

Validate, compile, and activate a flow.

fyrn flow deploy abc123

fyrn flow test <flow-file>

Test a local YAML file against sample data without hitting the API.

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 preview <flow-id>

Preview a deployed flow’s transform via the server.

Flag	Description
`--payload <file>`	JSON payload file
`--generate`	Use AI to generate a sample payload

fyrn flow preview abc123 --payload sample.json
fyrn flow preview abc123 --generate

fyrn flow clone <flow-id>

Clone an existing flow to another environment.

Flag	Description	Required
`--to <env>`	Target environment	Yes
`--env <env>`	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 the YAML configs of two deployed flows.

fyrn flow diff abc123 def456

fyrn flow delete <flow-id>

Soft-delete a flow.

fyrn flow delete abc123

Connectors — `fyrn connector`

fyrn connector list

List all connectors (catalog + instances).

fyrn connector list

fyrn connector catalog

List available connector types from the catalog.

fyrn connector catalog

fyrn connector instances

List configured instances only.

fyrn connector instances

fyrn connector test <id>

Test an instance’s connection.

fyrn connector test abc123

fyrn connector build [url-or-description]

Build a private connector from an API spec URL or plain-English description.

Flag	Description
`--name <slug>`	Connector name
`--spec <file>`	Path to a local 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>

Run OAuth2 connect flow for an instance. Opens a browser.

fyrn connector connect shopify-main

fyrn connector status <instance>

Show OAuth / connection status — token validity, expiration, and scopes.

fyrn connector status shopify-main

fyrn connector token <instance>

Inspect or refresh an OAuth access token.

fyrn connector token 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>

Historical search across message logs.

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

Duration strings use s/m/h/d suffixes. Non-matching values are treated as ISO date-time strings.

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

fyrn logs replay <message-id>

Re-run a specific message through the flow.

fyrn logs replay msg-abc123

Schedules — `fyrn schedules`

fyrn schedules list

List scheduled flows with cron, next run, and enabled state.

fyrn schedules list

fyrn schedules trigger <flow-name-or-id>

Manually trigger a schedule now.

fyrn schedules trigger my-flow

Adapters — `fyrn adapters`

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

fyrn adapters list

fyrn adapters list

fyrn adapters generate “<description>”

Generate an adapter with AI.

Flag	Description	Default
`--type <type>`	`transform` or `auth`	`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 test <adapter-id>

Test in a sandboxed V8 isolate.

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

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

fyrn adapters templates

List pre-built adapter templates.

fyrn adapters templates

Lookup tables — `fyrn lookup`

Lookup tables are account-scoped — shared across all environments in the account — so flow clone preserves their references without rewiring.

fyrn lookup list

fyrn lookup list

fyrn lookup show <id>

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

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

fyrn lookup create <name>

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

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

fyrn lookup delete <id>

fyrn lookup delete abc123

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

Upsert a single entry.

fyrn lookup set abc123 US "United States"

fyrn lookup remove <id> <key>

fyrn lookup remove abc123 US

fyrn lookup import <id> <file>

Bulk-import from CSV. Requires key and value columns.

fyrn lookup import abc123 country-codes.csv

fyrn lookup export <id>

Export entries as CSV to stdout.

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>

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

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

fyrn bundle import <file>

fyrn bundle import my-flow.zip

Batch processing — `fyrn batch`

Run a flow over a large dataset with progress tracking and failure handling.

fyrn batch submit <flow-id>

Submit a batch job.

Flag	Description	Default
`--file <path>`	JSON array or CSV file of records	Required
`--concurrency <n>`	Max concurrent records
`--on-failure <mode>`	`continue` or `stop`	`continue`
`--max-failures <n>`	Stop after N failures
`--retry`	Retry failed records automatically

fyrn batch submit abc123 --file orders.csv --concurrency 10
fyrn batch submit abc123 --file records.json --on-failure stop --max-failures 5

fyrn batch list

List batch jobs.

Flag	Description
`--flow <flow-id>`	Filter by flow

fyrn batch list
fyrn batch list --flow abc123

fyrn batch show <job-id>

Show job status and record-level stats.

fyrn batch show job-abc123

fyrn batch cancel <job-id>

Cancel a running job.

fyrn batch cancel job-abc123

fyrn batch retry <job-id>

Retry failed records in a completed job at lower concurrency.

fyrn batch retry job-abc123

fyrn batch errors <job-id>

Export error details for failed records.

fyrn batch errors job-abc123

Self-healing — `fyrn healing`

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

fyrn healing list

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

fyrn healing list --status pending

fyrn healing show <event-id>

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

fyrn healing show heal-abc123

fyrn healing approve <event-id>

Approve a healing event and apply the proposed fix.

fyrn healing approve heal-abc123

fyrn healing reject <event-id>

fyrn healing reject heal-abc123

Governance — `fyrn governance`

Alias: fyrn gov.

fyrn governance list

fyrn governance list

fyrn governance show <policy-id>

fyrn governance show policy-abc123

fyrn governance check [flow-id]

Check a flow (or all flows) against all policies.

Flag	Description
`--all`	Check all flows

fyrn governance check abc123
fyrn gov check --all

AI agent keys — `fyrn agents`

Manage agent API keys and monitor agent activity.

fyrn agents keys list

fyrn agents keys list

fyrn agents keys create

Flag	Description
`--name <name>`	Key name
`--tier <tier>`	`standard` or `premium` (rate-limit tier)
`--rate-limit <rpm>`	Requests per minute
`--daily-quota <n>`	Daily request quota
`--sandbox`	Sandbox mode — blocks `deploy_flow`
`--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>

fyrn agents keys update ak-abc123 --tier premium

fyrn agents keys revoke <key-id>

Revoke a key. Immediate and irreversible.

fyrn agents keys revoke ak-abc123

fyrn agents activity

Show agent tool-call audit log.

Flag	Description
`--key <id>`	Filter by key
`--tool <name>`	Filter by tool
`--status <status>`	Filter by status (e.g., `failed`)
`--limit <n>`	Max results

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

fyrn apis list

fyrn apis docs <name>

Show rendered API docs.

fyrn apis docs orders-api

fyrn apis spec <name>

Fetch the OpenAPI spec.

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

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

fyrn apis update <name>

Update a published API endpoint.

fyrn apis update orders-api

fyrn apis delete <name>

Delete a published API endpoint.

fyrn apis delete orders-api

fyrn apis services list

List published services (groupings of API actions).

fyrn apis services list

fyrn apis services show <name>

Show a service with its actions.

fyrn apis services show orders-service

fyrn apis services docs <name>

Show rendered service docs.

fyrn apis services docs orders-service

Environments — `fyrn env`

fyrn env list

fyrn env list

fyrn env switch <name-or-slug>

fyrn env switch staging

fyrn env current

fyrn env current

fyrn env create <name>

Flag	Description
`--color <hex>`	Dashboard color
`--production`	Mark as a production environment

fyrn env create qa --color "#f59e0b"
fyrn env create prod --production

Accounts — `fyrn accounts`

For users with access to multiple accounts.

fyrn accounts list

fyrn accounts list

fyrn accounts switch <name-or-id>

fyrn accounts switch acme-corp

fyrn accounts current

fyrn accounts current

Billing — `fyrn billing`

fyrn billing status

Show plan, seats, and current billing period.

fyrn billing status

fyrn billing upgrade <plan>

Flag	Description
`--annual`	Switch to annual billing

fyrn billing upgrade pro
fyrn billing upgrade enterprise --annual

fyrn billing portal

Open the Stripe billing portal.

fyrn billing portal

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

fyrn usage

Usage metrics (messages, AI calls, etc.).

fyrn usage

fyrn plan

Show plan limits.

fyrn plan

Interactive mode

Running fyrn with no arguments starts a conversational assistant backed by Claude. It can execute any CLI command on your behalf with your permission and uses the same authentication context as the CLI.

fyrn

Requires ANTHROPIC_API_KEY. History persists in ~/.fyrn/history (max 500 lines).

CI/CD usage

The simplest CI setup is: generate an agent key, set FYRN_API_KEY, run CLI commands. No fyrn auth api-key step is needed — the env var is read directly.

GitHub Actions

name: Deploy flows
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Deploy via fyrn CLI
        env:
          FYRN_API_KEY: ${{ secrets.FYRN_API_KEY }}
        run: |
          npx -y @fyrn/cli push
          npx -y @fyrn/cli flow deploy my-flow

GitLab CI

deploy_flows:
  image: node:22
  variables:
    FYRN_API_KEY: $FYRN_API_KEY
  script:
    - npx -y @fyrn/cli push
    - npx -y @fyrn/cli flow deploy my-flow

Choosing an agent-key tier

Tier	Good for
1 (Use)	Read-only CI jobs (lint / validation)
2 (Build)	Deploy pipelines that push & deploy flows
3 (Manage)	Ops runbooks that pause/resume flows, retry messages

Create CI keys with --sandbox to block deploy_flow in the pipeline if you only want validation.

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

Run a flow over a large dataset

fyrn batch submit <flow-id> --file orders.csv --concurrency 10
fyrn batch show <job-id>
fyrn batch errors <job-id>      # inspect failures
fyrn batch retry <job-id>       # retry failed records