> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# pipecat cloud project

> pipecat cloud project subcommands manage Pipecat Cloud projects: status, logs, sessions, environments, promotion, PR previews, and watch paths.

The `project` command manages everything you deploy and run. A project is an agent with environments, and each environment is an agent of its own, so one group covers both: a command names the project, and `--env` reaches one of its environments.

```shell theme={null}
pipecat cloud project status my-bot
pipecat cloud project status my-bot --env staging
pipecat cloud project logs my-bot --env pr-7
```

An agent's own name works anywhere a project name does, so `project status my-bot-pr-7` addresses the same preview as `--env pr-7`. The project is its own `production` environment, so `--env production` means the project itself, exactly as naming it with no `--env` does.

For the concepts behind the environment commands, see [Projects and environments](https://docs.pipecat.ai/pipecat-cloud/fundamentals/projects-and-environments.md).

> [!WARNING]
>
> `pipecat cloud agent` is deprecated. Every command below still works under
> that name and prints a notice on stderr. Use `project`, with `--env` to
> address an environment.

## start

Start a deployed agent instance, creating an active session.

**Usage:**

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

**Arguments:**

**agent-name** `string`

Unique string identifier for the agent deployment. Must not contain spaces.
Defaults to `agent_name` in `pcc-deploy.toml`.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--config-file** `string`

Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.

**--api-key / -k** `string`

Public API key to authenticate the agent deployment. Will default to any key
set in your config.

For more information, see [API keys](https://docs.pipecat.ai/pipecat-cloud/fundamentals/accounts-and-organizations.md#api-keys).

**--data / -d** `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](https://docs.pipecat.ai/pipecat-cloud/fundamentals/active-sessions.md#running-an-agent).

**--force / -f** `boolean` (default: false)

Skip summary confirmation before issuing start request.

**--use-daily / -D** `boolean` (default: false)

Create a Daily WebRTC session for the agent.

**--daily-properties / -p** `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.

**--organization / -o** `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:**

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

**Arguments:**

**agent-name** `string`

Name of the agent. Must not contain spaces. Defaults to `agent_name` in
`pcc-deploy.toml`.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--config-file** `string`

Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.

**--session-id / -s** `string` *required*

ID of the session to stop.

**--organization / -o** `string`

Organization which the agent belongs to. If not provided, uses the current
organization from your configuration.

**--force / -f** `boolean` (default: false)

Bypass prompt for confirmation before stopping the session.

## status

Shows the current status of an agent deployment, including health and conditions, the deployment's CPU architecture, and its resolved resources (CPU and memory). For agents deployed with explicit resources rather than a profile, this is where the sizing is shown.

**Usage:**

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

**Arguments:**

**agent-name** `string` *required*

Unique string identifier for the agent deployment. Must not contain spaces.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--organization / -o** `string`

Organization the agent belongs to. If not provided, uses the current
organization from your configuration.

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 `project link` and the first [`project
>     deploy --github`](#deploy).

For a project with a repository connected, the output also carries its [watch
paths](https://docs.pipecat.ai/pipecat-cloud/guides/deploy-from-github.md#watch-paths), whether [PR
previews](https://docs.pipecat.ai/pipecat-cloud/guides/pr-previews.md) are on and which secret set they
mount, and whether pull requests opened by bots get previews.

For an environment it carries the project it belongs to and its environment
name instead, and for a PR preview the pull request it deploys.

Its environments are a listing of their own: see [`env list`](#env-list).

## deployments

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

**Usage:**

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

**Arguments:**

**agent-name** `string` *required*

Unique string identifier for the agent deployment. Must not contain spaces.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--organization / -o** `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:**

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

**Arguments:**

**agent-name** `string` *required*

Unique string identifier for the agent deployment. Must not contain spaces.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--organization / -o** `string`

Organization the agent belongs to. If not provided, uses the current
organization from your configuration.

**--level / -l** `string`

Filter logs by severity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`.
Omit it to return every level.

**--format / -f** `string` (default: TEXT)

Output format for the log lines: `TEXT` or `JSON`.

**--limit / -n** `int` (default: 100)

Limit the number of log lines to display.

**--deployment / -d** `str`

Filter results for specific agent deployment ID (obtainable from `pipecat
    cloud project deployments [project]`).

**--session-id / -s** `str`

Filter results for specific session ID (obtainable from `pipecat cloud project
    sessions [project]`).

## link

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

**Usage:**

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

**Arguments:**

**agent-name** `string` *required*

Name of the agent to link.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--repo** `string` *required*

Repository as `owner/repo`.

**--branch** `string` *required*

Branch to build and deploy from.

**--dockerfile-path** `string` (default: Dockerfile)

Path to the Dockerfile within the repository.

**--subdirectory** `string`

Build context subdirectory within the repository.

**--auto-deploy / --no-auto-deploy** `boolean` (default: --auto-deploy)

Whether a push to the branch deploys the agent.

**--organization / -o** `string`

Organization the agent belongs to. If not provided, uses the current
organization from your configuration.

```shell theme={null}
pipecat cloud project 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 [`project deploy --github`](#deploy) 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.

## unlink

Remove an agent's GitHub repository link.

**Usage:**

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

**Arguments:**

**agent-name** `string` *required*

Name of the agent to unlink.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--organization / -o** `string`

Organization the agent belongs to. If not provided, uses the current
organization from your configuration.

**--force / -f** `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:**

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

**Arguments:**

**agent-name** `string` *required*

Name of the agent to deploy.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--github** `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`.

**--wait** `boolean` (default: false)

Follow the deploy rather than returning as soon as it is queued.

**--organization / -o** `string`

Organization the agent belongs to. If not provided, uses the current
organization from your configuration.

```shell theme={null}
pipecat cloud project 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`](https://docs.pipecat.ai/api-reference/cli/cloud/deploy.md).

### 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 (0 with `--output json`) |
| 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. With `--output json`, a failed deploy exits 0 as well: `waitOutcome`
> is `terminal` for both a success and a failure, so gate on
> `latestDeploy.status` being `succeeded`.

"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 the organization's projects: the agents that are not environments of
another agent. Each row carries the project's region, how many named
environments it has, whether PR previews are on and how many are open, and its
GitHub repository and branch.

**Usage:**

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

**Options:**

**--all** `boolean` (default: false)

Include environments and PR previews, not only projects. Each row then also
names the project an environment belongs to, as `my-bot > staging`.

**--organization / -o** `string`

Organization to list projects for. If not provided, uses the current
organization from your configuration.

**--region / -r** `string`

Filter by region. If not provided, projects from all regions are listed. Must
be a region of the organization in use. An environment is always in its
project's region.

## 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 project sessions [ARGS] [OPTIONS]
```

**Arguments:**

**agent-name** `string`

Name of the agent to list active sessions for. Defaults to `agent_name` in
`pcc-deploy.toml`.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--config-file** `string`

Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.

**--id / -i** `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).

**--end-state** `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.

**--organization / -o** `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.

> [!WARNING]
>
> This action is irreversible. All data will be lost.

**Usage:**

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

**Arguments:**

**agent-name** `string` *required*

Unique string identifier for the agent deployment. Must not contain spaces.

**Options:**

**--env** `string`

Act on this environment of the project rather than on the project itself.
Addressing an agent by its own name works just as well.

**--organization / -o** `string`

Organization to delete the agent from. If not provided, uses the current
organization from your configuration.

**--force / -f** `boolean` (default: false)

Do not prompt for confirmation before deleting the agent.

## env

Manage a project's environments. See [Projects and
environments](https://docs.pipecat.ai/pipecat-cloud/fundamentals/projects-and-environments.md).

### env list

List a project's environments, starting with `production`, which is the
project's own agent. Then come the named environments, and then the PR
previews, newest pull request first. Each row carries the environment's agent
name, the branch it deploys, the commit it is running, and the pull request it
previews.

**Usage:**

```shell theme={null}
pipecat cloud project env list [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project.

**Options:**

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

### env add

Link an existing agent as an environment of a project.

**Usage:**

```shell theme={null}
pipecat cloud project env add [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project the environment belongs to.

**name** `string` *required*

What to call it among the project's environments. Two to 50 lowercase letters,
digits and dashes, starting and ending with a letter or digit. `production` is
the project itself, and names starting with `pr-` are reserved for PR
previews.

**Options:**

**--agent** `string` *required*

Name of the existing agent to link as this environment.

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

```shell theme={null}
pipecat cloud project env add my-bot staging --agent my-bot-staging
```

The agent has to exist already. Create it with [`pipecat cloud
deploy`](https://docs.pipecat.ai/api-reference/cli/cloud/deploy.md), then link it.

Linking changes nothing about what the agent runs: it keeps its own repository
link, secret sets and scaling, and follows the project's watch paths from here.
Re-running `env add` with a different name renames the environment, and with a
different project moves it.

The name is checked locally against the same rules the API applies, so a typo
fails immediately rather than after a round trip. The API refuses the link when
the agent is in another region than the project, when either side already has
environments, when the project has PR previews on, when the name is taken by
another environment, or when the agent is a PR preview.

### env remove

Unlink an environment from its project.

**Usage:**

```shell theme={null}
pipecat cloud project env remove [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project.

**name** `string` *required*

Environment to unlink, by its environment name.

**Options:**

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

The agent stays, running exactly as it was, and becomes a project of its own.
The project's watch paths it followed become its own, so it goes on deploying
as before. To stop it running as well, delete it with [`delete`](#delete).

A PR preview cannot be unlinked: its link belongs to its pull request.

### env promote

Deploy an environment's running code onto the project.

**Usage:**

```shell theme={null}
pipecat cloud project env promote [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project to deploy onto.

**name** `string` *required*

Environment to promote, by its environment name.

**Options:**

**--force / -f** `boolean` (default: false)

Skip the confirmation prompt.

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

```shell theme={null}
pipecat cloud project env promote my-bot staging
```

It deploys the build behind the environment's active deployment, or the image it
was deployed from. Nothing is rebuilt.

Promotion moves code only: the project keeps its own secrets, scaling and agent
profile. An environment with nothing deployed has nothing to promote, and the
command says so and exits 1.

The command returns once the API has accepted the deploy; the rollout follows.
Watch it with `pipecat cloud project status my-bot`.

## previews

Manage a project's [PR previews](https://docs.pipecat.ai/pipecat-cloud/guides/pr-previews.md).

### previews status

Show whether a project's PR previews are on, and the previews that are open.

**Usage:**

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

**Arguments:**

**project** `string` *required*

Name of the project.

**Options:**

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

With previews on it reports the secret set they mount, whether bot pull requests
are included, and the project's watch paths, then lists the open previews.

### previews enable

Turn a project's PR previews on, with the secret set they mount.

**Usage:**

```shell theme={null}
pipecat cloud project previews enable [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project.

**Options:**

**--secret-set** `string` *required*

Secret set every preview mounts in place of the project's own sets. It has to
exist, be a secret set rather than an image pull secret, and be in the
project's region.

**--bot-pull-requests / --no-bot-pull-requests** `boolean` (default: --no-bot-pull-requests)

Whether pull requests opened by bots get previews too. Left out, the stored
setting is kept.

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

```shell theme={null}
pipecat cloud project previews enable my-bot --secret-set preview-secrets
```

Choosing the secret set is what turns previews on. The project needs a GitHub
repository connected, and an agent that is itself an environment cannot have
previews.

### previews disable

Turn a project's PR previews off.

**Usage:**

```shell theme={null}
pipecat cloud project previews disable [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project.

**Options:**

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

The previews that exist are deleted within a few minutes. Turning previews off
always succeeds, whatever state the project is in.

## watch-paths

Manage a project's [watch
paths](https://docs.pipecat.ai/pipecat-cloud/guides/deploy-from-github.md#watch-paths). They are a project
setting: the project, its environments and its PR previews all follow the same
list.

### watch-paths show

Print a project's watch paths.

**Usage:**

```shell theme={null}
pipecat cloud project watch-paths show [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project.

**Options:**

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

A project with no watch paths deploys every change, and the command says so. A
project with no repository connected has no watch paths, and the command exits 1.

### watch-paths set

Set a project's watch paths, replacing the ones it has.

**Usage:**

```shell theme={null}
pipecat cloud project watch-paths set [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project.

**paths** `string...` *required*

One or more glob patterns a change has to match to deploy, relative to the
repository root. A leading `!` excludes. Write `bot` or `bot/**` for a folder:
a trailing slash is refused. See [writing
patterns](https://docs.pipecat.ai/pipecat-cloud/guides/deploy-from-github.md#writing-patterns).

**Options:**

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

```shell theme={null}
pipecat cloud project watch-paths set my-bot 'bot/**' 'shared/**'
```

Setting them on an environment is refused, with a pointer to the project.

### watch-paths clear

Clear a project's watch paths, so every change deploys.

**Usage:**

```shell theme={null}
pipecat cloud project watch-paths clear [ARGS] [OPTIONS]
```

**Arguments:**

**project** `string` *required*

Name of the project.

**Options:**

**--organization / -o** `string`

Organization the project belongs to. If not provided, uses the current
organization from your configuration.

## profiles

> [!NOTE]
>
> Available in `pipecatcloud` 1.2.0 or later, for
> organizations with self-hosted regions enabled. See
> [Pipecat Enterprise](https://docs.pipecat.ai/pipecat-cloud/enterprise/overview.md).

The `profiles` sub-commands manage organization-defined agent profiles for [self-hosted regions](https://docs.pipecat.ai/pipecat-cloud/enterprise/sizing.md#organization-agent-profiles). A profile is a named CPU and memory shape selected with `--profile` on deploy. Profile edits apply to future deploys only: running agents keep the resources their deployment captured.

### profiles list

Lists the platform's agent profiles plus any your organization has defined, with CPU, memory, source, and whether each is enabled.

**Usage:**

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

**Options:**

**--organization / -o** `string`

Organization to list profiles for. If not provided, uses the current
organization from your configuration.

### profiles create

Create an organization-defined profile.

**Usage:**

```shell theme={null}
pipecat cloud project profiles create [NAME] --cpu [CPU] --memory [MEMORY] [OPTIONS]
```

**Arguments:**

**name** `string` *required*

The profile's name, used with `--profile` on deploy. Lowercase letters,
numbers, and hyphens; must not collide with a platform profile name.

**Options:**

**--cpu** `string` *required*

CPU quantity, e.g. `2` or `500m`.

**--memory** `string` *required*

Memory quantity, e.g. `4Gi`.

**--display-name** `string`

Human-readable name shown in the dashboard. Defaults to the profile name.

**--organization / -o** `string`

Organization to create the profile in. If not provided, uses the current
organization from your configuration.

### profiles update

Change a profile's sizing or display name. CPU and memory are updated together.

**Usage:**

```shell theme={null}
pipecat cloud project profiles update [NAME] [OPTIONS]
```

**Options:**

**--cpu** `string`

New CPU quantity. Requires `--memory`.

**--memory** `string`

New memory quantity. Requires `--cpu`.

**--display-name** `string`

New human-readable name.

**--organization / -o** `string`

Organization the profile belongs to. If not provided, uses the current
organization from your configuration.

### profiles disable

Retire a profile from new deploys. Existing deployments are unaffected. Disabling is reversible with `enable`.

**Usage:**

```shell theme={null}
pipecat cloud project profiles disable [NAME] [OPTIONS]
```

**Options:**

**--organization / -o** `string`

Organization the profile belongs to. If not provided, uses the current
organization from your configuration.

### profiles enable

Re-enable a disabled profile for new deploys.

**Usage:**

```shell theme={null}
pipecat cloud project profiles enable [NAME] [OPTIONS]
```

**Options:**

**--organization / -o** `string`

Organization the profile belongs to. If not provided, uses the current
organization from your configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.