Agents commands

List agents, approve, revoke and remove them, mint join codes, and link or unlink standby agents with the sqlflow CLI.

These commands manage the agents of the account you are signed in to. They do what the Agents page does. Set up the CLI first: see Overview and authentication.

Commands that take <name|id> accept an agent's name or its ID, ignoring capitalization. If two agents share a name, the command stops and lists their IDs: Agent '<name>' is ambiguous; use one of these ids: …. Use the ID then.

List agents

sqlflow agents [--verbose]

sqlflow agents --verbose

NAME                 STATUS   PIPES CAPABILITIES             POSTURE       ID
orders-agent         online       2 sqlserver,postgres       unprivileged  agent-3f9c0a7e1b
      host=ORDERS-VM  version=2026.9.27.418  lastSeen=2026-10-15 08:12:44Z  runAs=NT SERVICE\SqlFlow.Agent

When no agent is registered, the command says so and how to add one.

Approve an agent

sqlflow agent approve <name|id>

Approves a pending agent so it can pull configuration and run pipelines. Check the agent's name and ID against the install command's output first. See Approve an agent.

sqlflow agent approve orders-agent

Revoke an agent

sqlflow agent revoke <name|id>

Rejects the agent's credential from now on, whether the agent is online or not, and prints revoked agent '<name>' [<id>]; its token no longer authenticates. It does the same as Revoke on the Agents page. The agent stops on its next contact with the control plane, and the installation must be installed again with install --reset and a new join code.

A revoked agent counts as stopped: its pipelines pause, or move to its standby agent if it has one. That makes revoke the way to recover the pipelines of an agent that is lost for good, which can't acknowledge a pause. Afterwards, assign them to another agent or archive them. See Remove an agent.

Remove an agent

sqlflow agent remove <name|id>

Deletes the record of an agent that is no longer online, and unassigns its pipelines. It prints removed agent '<name>' [<id>]. It refuses in four cases:

• a pipeline assigned to the agent isn't paused: Refusing to remove agent '<name>' [<id>]: <n> assigned pipeline(s) are not paused (…). Pause or stop them, reassign them to another agent, or archive them first. Revoke the agent first if it is lost for good;
• the agent is online: Agent '<name>' [<id>] is online. Stop the agent process (or `agent revoke` it) first, then remove it once it drops offline.;
• the agent belongs to a standby pair: Remove this agent's HA link before deleting its identity. [agent_ha_member_linked]. Run agent unlink-standby first;
• the agent isn't revoked and still holds a pipeline whose stop it never acknowledged: [agent_remove_requires_revoke]. Bring it back online and pause its pipelines, or revoke it first.

Create a join code

sqlflow agent join-code [--uses <n>]

Creates a join code, the credential that installs and enrolls an agent or a log broker. The code is valid for 15 minutes, and every agent or broker that registers with it still needs approval.

The code is the only thing written to standard output, so a script can capture it. The explanation goes to standard error.

$code = sqlflow agent join-code --uses 20
.\SqlFlow.Agent.exe install --account $code

The code admits agents to the account the CLI works in. See Agents and Log brokers.

List standby pairs

sqlflow agent ha-pairs

Prints the standby pairs of the account as one line of JSON. Each pair has its id, primaryAgentId, standbyAgentId, revision, status and statusReason, the activeAgentId, the protectedPipelineCount, and the pair's readiness and pipelines.

sqlflow agent ha-pairs | ConvertFrom-Json | Format-List

Link a standby agent

sqlflow agent standby <name|id> --for <primary-name|id>

Makes the first agent the standby of the agent named by --for. The standby must be approved and online, run no pipeline work of its own, and be on a release inside the control plane's version window. The command prints the new pair as JSON.

sqlflow agent standby orders-agent-b --for orders-agent-a

See High availability: Agents for what a standby protects and what refusals mean.

Unlink a standby pair

sqlflow agent unlink-standby <name|id>

Dissolves the pair that the named agent belongs to, whether it is the primary or the standby. Both agents stay enrolled and approved, and each protected pipeline stays with the agent that runs it now. The command prints Removed standby link <pair id>., or This agent has no HA link. if the agent isn't in a pair. If a takeover is due, the control plane refuses and says which agent to wait for.

See also

• Agents
• Agents and brokers
• High availability: Agents
• Pipelines commands