Supaflow CLI

The Supaflow CLI (@getsupaflow/cli) lets you manage datasources, pipelines, syncs, schedules, and jobs from your terminal. Use it for automation, scripting, and as the foundation for the Claude Code plugin.

Install

npm install -g @getsupaflow/cli

Requires Node.js 18 or later.

Authenticate

1. Log in to app.supa-flow.io and go to Settings > API Keys.
2. Create an API key and copy the value.
3. Run the login command and paste your key when prompted:

supaflow auth login

4. Verify authentication:

supaflow auth status

Select a Workspace

List available workspaces and select one:

supaflow workspaces list
supaflow workspaces select <workspace-name>

The selected workspace persists across commands until you change it.

Run Your First Command

Try these to confirm everything is working:

# Check auth and workspace
supaflow auth status --json

# List available connectors
supaflow connectors list --json

# Browse connector documentation
supaflow docs sqlserver

Command Groups

Command	Description
supaflow auth	Log in, log out, check authentication status
supaflow workspaces	List and select workspaces
supaflow connectors	List available connector types
supaflow datasources	Create, edit, test, and manage datasource connections
supaflow projects	List and create projects
supaflow pipelines	Create, edit, sync, and manage data pipelines
supaflow schedules	Create, edit, and manage recurring sync schedules
supaflow jobs	Check job status, view logs, and inspect results
supaflow agent	Start, stop, and manage a local Docker agent; safe upgrades require CLI 0.5.0+
supaflow encrypt	Encrypt sensitive values for datasource configuration
supaflow docs	Browse connector-specific documentation
supaflow mcp	Start the stdio MCP server (used by Claude Desktop and other MCP clients)

Run a Local Agent

Deploy a private agent on your own machine or server with one command -- the agent executes your pipelines inside your network, and only encrypted metadata reaches Supaflow Cloud:

supaflow agent start

The command checks its dependencies first (Docker installed and running, about 5 GB of free disk, agent image availability), then either enrolls a new agent -- issuing a registration token behind the scenes and asking whether to approve the agent for jobs -- or resumes an existing one. A restarted or recreated agent keeps its identity, so it reconnects in seconds without a new token or re-approval.

Command	What it does
supaflow agent start	Enroll a new agent or resume an existing one
supaflow agent upgrade	Pull and install a newer image while preserving the agent identity and keystore volume (CLI 0.5.0+)
supaflow agent stop	Stop the agent container (identity preserved)
supaflow agent status	Container state plus lifecycle, connectivity, and last heartbeat
supaflow agent logs	Agent container logs (-f to follow)
supaflow agent remove	Remove the container; --purge also deletes the identity so the next start enrolls fresh

agent start defaults to supaflow/supaflow-agent:latest and refuses to replace an existing container that uses a different image. In CLI 0.5.0+, use agent upgrade for image changes. The upgrade pulls and validates the requested image before stopping the current container, preserves its bootstrap URL and identity volume, checks that the replacement starts, and attempts to restore the previous immutable image if startup fails.

An upgrade briefly interrupts the local agent because its container is replaced. Use --name for a non-default container, --image for a specific image, and --no-pull only when that image already exists on the host. Legacy containers without a saved SUPAFLOW_API_URL require an explicit --api-url.

Enrolling requires an API key created by an organization admin. To re-enroll after revoking an agent, run supaflow agent remove --purge first, then supaflow agent start. For the wizard-based deployment and production guidance, see Agents.

Help and Documentation

# Global help
supaflow --help

# Help for a specific command group
supaflow pipelines --help

# Help for a subcommand
supaflow pipelines create --help

# Connector-specific documentation
supaflow docs <connector>
supaflow docs --list

Common Flags

These flags work across most commands:

Flag	Description
--json	Output results as JSON
--workspace <name>	Override the selected workspace for this command

CLI vs Claude Code Plugin

Use case	Recommended tool
Shell scripts and automation	CLI directly
CI/CD pipelines	CLI directly
Guided, interactive workflows	Claude Code plugin
First-time setup with guardrails	Claude Code plugin

The Claude Code plugin uses the CLI under the hood. It adds guardrailed slash commands, parser contracts, and confirmation gates to prevent common AI agent failure modes.

Further Reading

• Full CLI reference on npm
• Claude Code plugin for AI-powered pipeline management