> ## Documentation Index
> Fetch the complete documentation index at: https://daily-main.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# pipecat cloud agent

> pipecat cloud agent subcommands manage deployed Pipecat Cloud agents: view status and control agent lifecycle from the CLI.

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:**

```shell theme={null}
pipecat cloud agent start [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--config-file" type="string">
  Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.
</ParamField>

<ParamField path="--api-key / -k" type="string">
  Public API key to authenticate the agent deployment. Will default to any key
  set in your config.

  For more information, see [API keys](/pipecat-cloud/fundamentals/accounts-and-organizations#api-keys).
</ParamField>

<ParamField path="--data / -d" type="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](/pipecat-cloud/fundamentals/active-sessions#running-an-agent).
</ParamField>

<ParamField path="--force / -f" type="boolean" default="false">
  Skip summary confirmation before issuing start request.
</ParamField>

<ParamField path="--use-daily / -D" type="boolean" default="false">
  Create a Daily WebRTC session for the agent.
</ParamField>

<ParamField path="--daily-properties / -p" type="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](https://docs.daily.co/reference/rest-api/rooms/config) for
  available properties.
</ParamField>

<ParamField path="--organization / -o" type="str">
  Organization to start the agent for. If not provided, uses the current
  organization from your configuration.
</ParamField>

## stop

Stop an active agent session and clean up its resources.

**Usage:**

```shell theme={null}
pipecat cloud agent stop [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Name of the agent. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--config-file" type="string">
  Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.
</ParamField>

<ParamField path="--session-id / -s" type="string" required>
  ID of the session to stop.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization which the agent belongs to. If not provided, uses the current
  organization from your configuration.
</ParamField>

<ParamField path="--force / -f" type="boolean" default="false">
  Bypass prompt for confirmation before stopping the session.
</ParamField>

## status

Shows the current status of an agent deployment, including health and conditions.

**Usage:**

```shell theme={null}
pipecat cloud agent status [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--organization / -o" type="string">
  Organization the agent belongs to. If not provided, uses the current
  organization from your configuration.
</ParamField>

For a [GitHub-linked agent](#link), 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.

<Tip>
  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`](#deploy).
</Tip>

## deployments

Lists deployment history for an agent, including image versions and timestamps.

**Usage:**

```shell theme={null}
pipecat cloud agent deployments [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--organization / -o" type="string">
  Organization the agent belongs to. If not provided, uses the current
  organization from your configuration.
</ParamField>

## logs

Displays combined logs from all agent instances, useful for debugging issues.

**Usage:**

```shell theme={null}
pipecat cloud agent logs [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--level / -l" type="string">
  Filter logs by severity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`.
  Omit it to return every level.
</ParamField>

<ParamField path="--format / -f" type="string" default="TEXT">
  Output format for the log lines: `TEXT` or `JSON`.
</ParamField>

<ParamField path="--limit / -n" type="int" default="100">
  Limit the number of log lines to display.
</ParamField>

<ParamField path="--deployment / -d" type="str">
  Filter results for specific agent deployment ID (obtainable from `pipecat
      cloud agent deployments [agent-name]`).
</ParamField>

<ParamField path="--session-id / -s" type="str">
  Filter results for specific session ID (obtainable from `pipecat cloud agent
      sessions [agent-name]`).
</ParamField>

## link

Link an agent to a GitHub repository and branch, or re-point an existing link. Requires the organization to be [connected to GitHub](/api-reference/cli/cloud/github#connect).

**Usage:**

```shell theme={null}
pipecat cloud agent link [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Name of the agent to link.
</ParamField>

**Options:**

<ParamField path="--repo" type="string" required>
  Repository as `owner/repo`.
</ParamField>

<ParamField path="--branch" type="string" required>
  Branch to build and deploy from.
</ParamField>

<ParamField path="--dockerfile-path" type="string" default="Dockerfile">
  Path to the Dockerfile within the repository.
</ParamField>

<ParamField path="--subdirectory" type="string">
  Build context subdirectory within the repository.
</ParamField>

<ParamField path="--auto-deploy / --no-auto-deploy" type="boolean" default="--auto-deploy">
  Whether a push to the branch deploys the agent.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization the agent belongs to. If not provided, uses the current
  organization from your configuration.
</ParamField>

```shell theme={null}
pipecat cloud agent link my-agent --repo my-org/my-bot --branch main
```

<Note>
  Linking never changes what is running. It sets where the *next* deploy comes
  from — use [`agent deploy --github`](#deploy) to ship the branch now.
</Note>

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.

## unlink

Remove an agent's GitHub repository link.

**Usage:**

```shell theme={null}
pipecat cloud agent unlink [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Name of the agent to unlink.
</ParamField>

**Options:**

<ParamField path="--organization / -o" type="string">
  Organization the agent belongs to. If not provided, uses the current
  organization from your configuration.
</ParamField>

<ParamField path="--force / -f" type="boolean" default="false">
  Skip the confirmation prompt.
</ParamField>

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:**

```shell theme={null}
pipecat cloud agent deploy [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Name of the agent to deploy.
</ParamField>

**Options:**

<ParamField path="--github" type="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`.
</ParamField>

<ParamField path="--wait" type="boolean" default="false">
  Follow the deploy rather than returning as soon as it is queued.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization the agent belongs to. If not provided, uses the current
  organization from your configuration.
</ParamField>

```shell theme={null}
pipecat cloud agent deploy my-agent --github --wait
```

<Note>
  `--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`](/api-reference/cli/cloud/deploy).
</Note>

### 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:

| Outcome        | Meaning                                                                          | Exit |
| -------------- | -------------------------------------------------------------------------------- | ---- |
| Succeeded      | The deploy reached a terminal state and succeeded.                               | 0    |
| Failed         | The deploy reached a terminal state and failed. The reason is printed.           | 1    |
| Superseded     | A newer push took over as the latest attempt, so this one is no longer reported. | 0    |
| Still building | Observed and still moving when the wait ran out. It continues server-side.       | 0    |
| Never observed | The wait never saw the attempt at all.                                           | 1    |

<Warning>
  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`.
</Warning>

"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:**

```shell theme={null}
pipecat cloud agent list [OPTIONS]
```

**Options:**

<ParamField path="--organization / -o" type="string">
  Organization to list agents for. If not provided, uses the current
  organization from your configuration.
</ParamField>

<ParamField path="--region / -r" type="string">
  Filter agents by region. Only agents deployed in the specified region will be
  shown. If not provided, agents from all regions are listed.
</ParamField>

## sessions

Lists active sessions for a specified agent. When there are no active sessions, it suggests how to start a new session.

The Status column distinguishes how each session ended: sessions that ended before reaching an agent ("Ended before agent start"), activation timeouts ("Timeout"), and agent errors are shown separately from completed sessions.

When used with the `--id` option, displays detailed information about a specific session including CPU and memory usage with sparkline visualizations and percentile summaries, plus lifecycle events showing when the request arrived, when the agent started serving it, and when the session ended.

**Usage:**

```shell theme={null}
pipecat cloud agent sessions [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Name of the agent to list active sessions for.
</ParamField>

**Options:**

<ParamField path="--config-file" type="string">
  Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.
</ParamField>

<ParamField path="--id / -i" type="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).
</ParamField>

<ParamField path="--end-state" type="string">
  Filter sessions by how they ended. Known values: `active`, `completed`,
  `ended_before_agent_start`, `agent_start_timeout`, `terminated`,
  `agent_error`, `unknown`. Other values are passed to the API, so states added
  after this CLI release still filter.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization to list sessions for. If not provided, uses the current
  organization from your configuration.
</ParamField>

## delete

Deletes an agent deployment. This will prevent starting new agents and remove all associated data.

<Warning>This action is irreversible. All data will be lost.</Warning>

**Usage:**

```shell theme={null}
pipecat cloud agent delete [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--force / -f" type="boolean" default="false">
  Do not prompt for confirmation before deleting the agent.
</ParamField>