estuary 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:
- WSL (recommended) — Install Windows Subsystem for Linux, then use the Linux install command above inside your WSL shell.
- 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:
- Go to https://dashboard.estuary.dev/admin/api and generate a refresh token
- Set the environment variable:
export FLOW_AUTH_TOKEN=<your-refresh-token> - 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 <command> |
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