Skip to main content
The agent command provides sub-commands for managing your deployed agents. These commands allow you to view status, start agents, see logs, and manage deployments.

​
start

Start a deployed agent instance, creating an active session. Usage:
Arguments:
​
string
required
Unique string identifier for the agent deployment. Must not contain spaces.
Options:
​
string
Path to an alternate deploy config file. Defaults to pcc-deploy.toml.
​
string
Public API key to authenticate the agent deployment. Will default to any key set in your config.For more information, see API keys.
​
string
Stringified JSON object to pass to the agent deployment. This data will be available to the agent as a data parameter in your bot() method.More information here.
​
boolean
default:"false"
Skip summary confirmation before issuing start request.
​
boolean
default:"false"
Create a Daily WebRTC session for the agent.
​
string
Stringified JSON object with Daily room properties to customize the WebRTC session. Only used when --use-daily is set to true.See Daily API documentation for available properties.
​
str
Organization to start the agent for. If not provided, uses the current organization from your configuration.

​
stop

Stop an active agent session and clean up its resources. Usage:
Arguments:
​
string
required
Name of the agent. Must not contain spaces.
Options:
​
string
Path to an alternate deploy config file. Defaults to pcc-deploy.toml.
​
string
required
ID of the session to stop.
​
string
Organization which the agent belongs to. If not provided, uses the current organization from your configuration.
​
boolean
default:"false"
Bypass prompt for confirmation before stopping the session.

​
status

Shows the current status of an agent deployment, including health and conditions. Usage:
Arguments:
​
string
required
Unique string identifier for the agent deployment. Must not contain spaces.
Options:
​
string
Organization the agent belongs to. If not provided, uses the current organization from your configuration.
For a GitHub-linked agent, the output also carries the linked repository and branch, the Dockerfile path and build subdirectory, whether pushes auto-deploy, the commit actually running, and the latest deploy attempt with its failure reason if it has one. The running commit and the linked branch can legitimately differ — right after you link a repository, after you re-point an agent, or when auto-deploy is off and there are unshipped commits. When the running commit didn’t come from the current link, status says so and names the repository and branch it did come from.
Nothing live from the current link shows as — (nothing from this link is live yet), which is what you’ll see between agent link and the first agent deploy --github.

​
deployments

Lists deployment history for an agent, including image versions and timestamps. Usage:
Arguments:
​
string
required
Unique string identifier for the agent deployment. Must not contain spaces.
Options:
​
string
Organization the agent belongs to. If not provided, uses the current organization from your configuration.

​
logs

Displays combined logs from all agent instances, useful for debugging issues. Usage:
Arguments:
​
string
required
Unique string identifier for the agent deployment. Must not contain spaces.
Options:
​
string
Filter logs by severity: DEBUG, INFO, WARNING, ERROR, or CRITICAL. Omit it to return every level.
​
string
default:"TEXT"
Output format for the log lines: TEXT or JSON.
​
int
default:"100"
Limit the number of log lines to display.
​
str
Filter results for specific agent deployment ID (obtainable from pipecat cloud agent deployments [agent-name]).
​
str
Filter results for specific session ID (obtainable from pipecat cloud agent sessions [agent-name]).
Link an agent to a GitHub repository and branch, or re-point an existing link. Requires the organization to be connected to GitHub. Usage:
Arguments:
​
string
required
Name of the agent to link.
Options:
​
string
required
Repository as owner/repo.
​
string
required
Branch to build and deploy from.
​
string
default:"Dockerfile"
Path to the Dockerfile within the repository.
​
string
Build context subdirectory within the repository.
​
boolean
default:"--auto-deploy"
Whether a push to the branch deploys the agent.
​
string
Organization the agent belongs to. If not provided, uses the current organization from your configuration.
Linking never changes what is running. It sets where the next deploy comes from — use agent deploy --github to ship the branch now.
Re-running link on an already-linked agent re-points it. Options you leave out keep their stored values, so changing only the branch won’t reset a Dockerfile path you set earlier. The repository and branch are validated locally against the same rules the API applies, so a typo fails immediately rather than after a round trip. Remove an agent’s GitHub repository link. Usage:
Arguments:
​
string
required
Name of the agent to unlink.
Options:
​
string
Organization the agent belongs to. If not provided, uses the current organization from your configuration.
​
boolean
default:"false"
Skip the confirmation prompt.
Pushes stop deploying the agent. The running agent is not touched and its current deployment stays live.

​
deploy

Build and deploy a GitHub-linked agent from its branch’s current HEAD, without waiting for a push. Usage:
Arguments:
​
string
required
Name of the agent to deploy.
Options:
​
boolean
default:"false"
Deploy the agent’s linked GitHub branch. Currently the only mode this command supports, so it has to be passed — without it the command exits 1 and points you at pipecat cloud deploy.
​
boolean
default:"false"
Follow the deploy rather than returning as soon as it is queued.
​
string
Organization the agent belongs to. If not provided, uses the current organization from your configuration.
--github is explicit rather than implied so that adding image-based deploys to this command later can’t change what an existing script does. To deploy an image or a cloud build, use pipecat cloud deploy.

​
What --wait reports

Without --wait, the command returns once the deploy is queued, printing the branch and commit it will build. With --wait, it follows the deploy and reports one of these:
A zero exit from --wait means the deploy was observed and did not fail — not that it finished. A deploy still building, or superseded by a newer push, also exits 0. Check the outcome itself if you need to gate on completion; in --output json it is reported as waitOutcome.
“Never observed” exits non-zero on purpose: a wait that saw nothing can’t tell a healthy build from an API that was down the whole time, and calling that success is what would make --wait unsafe as a deploy gate.

​
list

Lists all agents in an organization with their details, including a GitHub column for agents built from a repository. Usage:
Options:
​
string
Organization to list agents for. If not provided, uses the current organization from your configuration.
​
string
Filter agents by region. Only agents deployed in the specified region will be shown. If not provided, agents from all regions are listed.

​
sessions

Lists active sessions for a specified agent. When there are no active sessions, it suggests how to start a new session. When used with the --id option, displays detailed information about a specific session including CPU and memory usage with sparkline visualizations and percentile summaries. Usage:
Arguments:
​
string
required
Name of the agent to list active sessions for.
Options:
​
string
Path to an alternate deploy config file. Defaults to pcc-deploy.toml.
​
string
Session ID to view detailed metrics for. When provided, displays CPU and memory usage statistics including sparkline visualizations and percentile summaries (p50, p90, p99).
​
string
Organization to list sessions for. If not provided, uses the current organization from your configuration.

​
delete

Deletes an agent deployment. This will prevent starting new agents and remove all associated data.
This action is irreversible. All data will be lost.
Usage:
Arguments:
​
string
required
Unique string identifier for the agent deployment. Must not contain spaces.
Options:
​
boolean
default:"false"
Do not prompt for confirmation before deleting the agent.