> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-pr-5482.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.

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

```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="--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>