Skip to main content
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.
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.
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:
Arguments:
string
Unique string identifier for the agent deployment. Must not contain spaces. Defaults to agent_name in pcc-deploy.toml.
Options:
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.
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
Name of the agent. Must not contain spaces. Defaults to agent_name in pcc-deploy.toml.
Options:
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.
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, 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:
Arguments:
string
required
Unique string identifier for the agent deployment. Must not contain spaces.
Options:
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.
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 project link and the first project deploy --github.
For a project with a repository connected, the output also carries its watch paths, whether PR previews 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.

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
Act on this environment of the project rather than on the project itself. Addressing an agent by its own name works just as well.
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
Act on this environment of the project rather than on the project itself. Addressing an agent by its own name works just as well.
string
Organization the agent belongs to. If not provided, uses the current organization from your configuration.
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 project deployments [project]).
str
Filter results for specific session ID (obtainable from pipecat cloud project sessions [project]).
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
Act on this environment of the project rather than on the project itself. Addressing an agent by its own name works just as well.
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 project 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
Act on this environment of the project rather than on the project itself. Addressing an agent by its own name works just as well.
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:
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.
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. 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:
Options:
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.
string
Organization to list projects for. If not provided, uses the current organization from your configuration.
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:
Arguments:
string
Name of the agent to list active sessions for. Defaults to agent_name in pcc-deploy.toml.
Options:
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.
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
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.
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:
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.
string
Organization to delete the agent from. If not provided, uses the current organization from your configuration.
boolean
default:"false"
Do not prompt for confirmation before deleting the agent.

env

Manage a project’s environments. See Projects and environments.

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:
Arguments:
string
required
Name of the project.
Options:
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:
Arguments:
string
required
Name of the project the environment belongs to.
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:
string
required
Name of the existing agent to link as this environment.
string
Organization the project belongs to. If not provided, uses the current organization from your configuration.
The agent has to exist already. Create it with pipecat cloud deploy, 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:
Arguments:
string
required
Name of the project.
string
required
Environment to unlink, by its environment name.
Options:
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. 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:
Arguments:
string
required
Name of the project to deploy onto.
string
required
Environment to promote, by its environment name.
Options:
boolean
default:"false"
Skip the confirmation prompt.
string
Organization the project belongs to. If not provided, uses the current organization from your configuration.
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.

previews status

Show whether a project’s PR previews are on, and the previews that are open. Usage:
Arguments:
string
required
Name of the project.
Options:
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:
Arguments:
string
required
Name of the project.
Options:
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.
boolean
default:"--no-bot-pull-requests"
Whether pull requests opened by bots get previews too. Left out, the stored setting is kept.
string
Organization the project belongs to. If not provided, uses the current organization from your configuration.
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:
Arguments:
string
required
Name of the project.
Options:
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. 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:
Arguments:
string
required
Name of the project.
Options:
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:
Arguments:
string
required
Name of the project.
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.
Options:
string
Organization the project belongs to. If not provided, uses the current organization from your configuration.
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:
Arguments:
string
required
Name of the project.
Options:
string
Organization the project belongs to. If not provided, uses the current organization from your configuration.

profiles

The profiles sub-commands manage organization-defined agent profiles for self-hosted regions. 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:
Options:
string
Organization to list profiles for. If not provided, uses the current organization from your configuration.

profiles create

Create an organization-defined profile. Usage:
Arguments:
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:
string
required
CPU quantity, e.g. 2 or 500m.
string
required
Memory quantity, e.g. 4Gi.
string
Human-readable name shown in the dashboard. Defaults to the profile name.
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:
Options:
string
New CPU quantity. Requires --memory.
string
New memory quantity. Requires --cpu.
string
New human-readable name.
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:
Options:
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:
Options:
string
Organization the profile belongs to. If not provided, uses the current organization from your configuration.