Estuary Flowctl Setup

flowctl Setup — Install, Authenticate, and Update

flowctl is Estuary's CLI for managing captures, materializations, collections, and derivations from the command line.

Install

Mac (Homebrew — recommended)

brew tap estuary/flowctl
brew install flowctl

Mac (direct download)

sudo curl -o /usr/local/bin/flowctl -L 'https://github.com/estuary/flow/releases/latest/download/flowctl-multiarch-macos' && sudo chmod +x /usr/local/bin/flowctl

Linux (x86-64)

sudo curl -o /usr/local/bin/flowctl -L 'https://github.com/estuary/flow/releases/latest/download/flowctl-x86_64-linux' && sudo chmod +x /usr/local/bin/flowctl

Windows

No native Windows build exists. Use one of:

1. WSL (recommended) — Install Windows Subsystem for Linux, then use the Linux install command above inside your WSL shell.
2. Remote dev environment — Run flowctl on a cloud Linux VM and connect via your IDE's remote development features.

Note: On ARM-based Windows machines (e.g., Snapdragon/aarch64 under WSL), the x86-64 binary won't work (Exec format error). There is no official ARM build yet — use a remote x86-64 environment or build from source.

Authenticate

Interactive login (local development)

flowctl auth login

This opens your browser to the Estuary dashboard's CLI-API tab. Copy the access token and paste it into the terminal.

Note: Access tokens are short-lived (~1 hour). You'll need to repeat this when the token expires.

Programmatic access (CI/CD and automation)

For non-interactive environments, use a long-lived refresh token:

1. Go to https://dashboard.estuary.dev/admin/api and generate a refresh token
2. Set the environment variable:

``bash export FLOW_AUTH_TOKEN= ``

1. Run flowctl commands normally — authentication is handled automatically

Important: If a config file exists for the current profile, flowctl ignores FLOW_AUTH_TOKEN. Use a separate profile to avoid conflicts:

flowctl --profile ci catalog list

The refresh token expires after 90 days of inactivity — each use resets the clock.

Common CI mistake: Don't run flowctl auth token --token $FLOW_AUTH_TOKEN in your scripts — that command is for interactive token exchange only. Just set the env var and run flowctl commands directly.

Verify Installation

flowctl --version

Quick test that authentication works:

flowctl catalog list --output json | head -5

Update

Homebrew

brew update && brew upgrade flowctl

Direct download

Re-run the install command for your platform — it overwrites the existing binary.

Troubleshooting

| Problem | Solution | |---------|----------| | command not found: flowctl | Re-run the install command, or check that /usr/local/bin is in your PATH | | You are not authenticated | Run flowctl auth login — your token likely expired | | Exec format error | Wrong binary for your architecture — ARM machines need an x86-64 environment (see Windows section) | | FLOW_AUTH_TOKEN ignored | An existing profile config takes precedence — use flowctl --profile ci | | Header of type authorization was missing | Token didn't save correctly — re-run flowctl auth login and paste carefully | | Failed to locate sops | Only needed for local secret encryption — install sops if using encrypted configs |

Check for the latest releases and changelogs: https://github.com/estuary/flow/releases

Related Skills

• estuary-logs — Search and analyze task logs with flowctl
• estuary-catalog-status — Check whether tasks are running, disabled, or failed
• estuary-connector-restart — Pause and restart connectors via flowctl

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: estuary
• Source: estuary/agent-skills
• License: Apache-2.0
• Homepage: https://estuary.dev

Install and usage instructions live in the source repository linked above.