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

> pipecat cloud secrets manages secret sets for agent deployments: create, update, list, and delete sensitive configuration.

The `secrets` command group helps you manage sensitive information for your agent deployments. You can create and manage secret sets (key-value pairs) and image pull secrets (for private Docker registries).

## list

List secret sets and image pull secrets for active namespace / organization.
Each row includes a
[readiness status](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets.md#provisioning-and-readiness)
(`ready`, `pending`, or `failed`).

If provided with a valid secret set name, will show the keys of that set
alongside its status (values are hidden).

**Usage:**

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

**Arguments:**

**name** `string`

Name of the secret set list keys for. Must be a valid string identifier.

**Options:**

**--sets / -s** `boolean` (default: true)

Has no effect: the list always includes image pull secrets, and there is no
`--no-sets`.

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

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

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

Filter secrets by region. Only secrets in the specified region will be shown.
If not provided, secrets from all regions are listed. Must be a region of the
organization in use.

## set

Create or update a secret set with the given name and key-value pairs. Secrets can be passed directly as key value pairs or loaded from a file.

Several values are written in one request, which the API applies whole or not at all: if the write fails, none of them is stored. Before writing, the command asks you to confirm and shows each key with a fixed mask in place of its value. Without `--skip` and without a terminal, as in CI, it exits 2 before showing any keys.

If the API answers a write with a 503 and a `Retry-After` of up to 30 seconds, the command waits and retries, up to 3 times. A 503 without a usable `Retry-After`, a `Retry-After` above 30 seconds, and other errors are not retried. A write that ends in a 503 may still have reached the region, unless the error says nothing was stored; running the same command again settles it. After any other error, fix it first.

**Usage:**

```shell theme={null}
pipecat cloud secrets set [ARGS] [OPTIONS]
```

**Arguments:**

**name** `string` *required*

Name of the secret set to create or modify. Letters, numbers, hyphens, and
underscores, starting and ending with a letter or number.

**secrets** `string`

List of secret key-value pairs e.g. `KEY1=value1 KEY2="value with spaces"`,
one pair per argument. Can't be combined with `--file`.

See [this note](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets.md#special-characters) on using special
characters in secret values.

Example:

```shell theme={null}
pipecat cloud secrets set my-secrets API_KEY=123 API_KEY_2="value with spaces"
```

**Options:**

**--file / -f** `string`

Relative path to a file with a list of secret key-value pairs. Each line in
the file should be in the format `KEY=value`.

Example:

```shell theme={null}
pipecat cloud secrets set my-secrets --file .env
```

**--skip / -s** `boolean` (default: false)

Skip confirmations and proceed with the operation.

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

Organization to create/update the secret set in. If not provided, uses the
current organization from your configuration.

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

Region where the secret set will be stored. If not specified, uses your
organization's default region (typically `us-west`). Secrets must be in the
same region as the agents that use them. Must be a region of the organization
in use.

**Example:**

Create a secret set in a specific region:

```shell theme={null}
pipecat cloud secrets set my-secrets API_KEY=abc123 --region eu-central
```

## keys

Show your organization's secret keys in a region: each key's fingerprint, state, created and retired times, and how many fields and sets it holds. The fingerprint is the one a security notice names and, in a self-hosted region, the one your cluster shows for the key. Key material is never shown. With `--output json`, prints the full response as JSON.

A key's state is `active` (new values go to it), `pending` (made, not used yet), `retired` (takes no new values and still opens the ones it holds), `compromised`, `destroying`, or `destroyed`. The **Region reports** column is the state the region itself reports, which can also be `missing`.

The command exits 1 if the region is invalid, if the API refuses the request, or if the API does not offer key listing yet.

**Usage:**

```shell theme={null}
pipecat cloud secrets keys --region [REGION] [OPTIONS]
```

**Options:**

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

Region to show the keys of.

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

Organization the keys belong to. If not provided, uses the current
organization from your configuration.

**Example:**

```shell theme={null}
pipecat cloud secrets keys --region us-west --output json
```

## unset

Removes a specific secret key from a secret set.

Like `set`, it waits and retries a 503 with a `Retry-After` of up to 30 seconds, up to 3 times. If a retry finds the key already gone, the attempt before it removed the key, and the command reports it deleted.

**Usage:**

```shell theme={null}
pipecat cloud secrets unset [ARGS] [OPTIONS]
```

**Arguments:**

**name** `string` *required*

Name of the secret set to remove the secret from.

**secret\_key** `string` *required*

The key of the secret to remove from the set.

Example:

```shell theme={null}
pipecat cloud secrets unset my-secret-set SOME_KEY
```

**Options:**

**--skip / -s** `boolean` (default: false)

Skip confirmations and proceed with the operation.

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

Organization containing the secret set. If not provided, uses the current
organization from your configuration.

## delete

Deletes an entire secret set.

A secret set that an agent uses, including as its image pull secret, can't be
deleted: the command fails with an error that names the agents using it. See
[Removing a secret](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets.md#removing-a-secret) for
how to free the set first.

**Usage:**

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

**Arguments:**

**name** `string` *required*

Name of the secret set to delete. This action is irreversible.

**Options:**

**--skip / -s** `boolean` (default: false)

Skip confirmations and proceed with the operation.

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

Organization containing the secret set. If not provided, uses the current
organization from your configuration.

## image-pull-secret

Creates or updates credentials for pulling images from private Docker registries.

This command accepts image repository credentials as `username:password`,
base64-encodes them, and securely stores them. These credentials are used with
the [deploy](https://docs.pipecat.ai/api-reference/cli/cloud/deploy.md) command when pulling images from private repositories. If
a secret with the same name already exists, its credentials will be updated in
place. If you don't provide credentials directly, the command will prompt you for
input. Like `set`, it waits and retries a 503 with a `Retry-After` of up to 30 seconds, up to 3 times.

**Usage:**

```shell theme={null}
pipecat cloud secrets image-pull-secret [ARGS] [OPTIONS]
```

**Arguments:**

**name** `string` *required*

Name of the credentials set to create or modify. Must be a valid string
identifier.

**host** `string` *required*

Host address of the image repository e.g. `https://index.docker.io/v1/`.

**credentials** `string` (default: prompts for input)

Credentials for the image repository in the form of `username:password`.

Will prompt you for the value if not provided.

Example:

```shell theme={null}
pipecat cloud secrets image-pull-secret my-registry-creds https://index.docker.io/v1/ my-username:my-password
```

**Options:**

**--encode / -e** `boolean` (default: true)

Encode the credentials in base64 format. Always on: there is no `--no-encode`.

**--skip / -s** `boolean` (default: false)

Skip the confirmation prompt shown when the image pull secret already exists.
Required in CI — without it an update reaches a prompt with no terminal and
exits 2.

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

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

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

Region where the image pull secret will be stored. If not specified, uses your
organization's default region (typically `us-west`). Image pull secrets must
be in the same region as the agents that use them. Must be a region of the
organization in use.

**Examples:**

Create an image pull secret in a specific region:

```shell theme={null}
pipecat cloud secrets image-pull-secret my-registry-creds https://index.docker.io/v1/ --region eu-central
```

## reference

> [!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).

Reference an existing Kubernetes Secret in your self-hosted region's workloads namespace as a secret set. The Secret's name becomes the secret set name, and agents use it exactly as they use managed sets. The Secret stays in your cluster: Pipecat Cloud records only its name, region, type, and readiness — never its keys or values — and you keep managing its contents with your own tooling. See [Pipecat Enterprise Secrets](https://docs.pipecat.ai/pipecat-cloud/enterprise/secrets.md).

The Secret must already exist; the command verifies this against your region before recording the reference. A `docker-registry` Secret is registered as an image pull secret automatically.

**Usage:**

```shell theme={null}
pipecat cloud secrets reference [NAME] --region [REGION]
```

**Arguments:**

**name** `string` *required*

Name of the Kubernetes Secret in your workloads namespace. Becomes the secret
set name, which must be unique across your organization's managed and
referenced sets.

**Options:**

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

The self-hosted region containing the Secret. Required; Daily-hosted regions
are rejected. Must be a region of the organization in use.

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

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

**Examples:**

```shell theme={null}
# Create the Secret in your cluster, then reference it
kubectl -n pipecat-agents create secret generic my-agent-secrets --from-literal=OPENAI_API_KEY=...
pipecat cloud secrets reference my-agent-secrets --region pce-acme-us-east
```

To remove a reference, use [`delete`](#delete); the Secret in your cluster is untouched. Referenced sets cannot be modified with `set` or `unset`.

***

> [card] [More about secrets](https://docs.pipecat.ai/pipecat-cloud/fundamentals/secrets.md)
>
> Learn more about managing application secrets


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