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

# secrets

> Secret sets and secret management commands

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](/pipecat-cloud/fundamentals/secrets#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:**

<ParamField path="name" type="string">
  Name of the secret set list keys for. Must be a valid string identifier.
</ParamField>

**Options:**

<ParamField path="--sets / -s" type="boolean" default="true">
  Show secret sets only. Filter out image pull secrets from the results.
</ParamField>

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

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

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

**Usage:**

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

**Arguments:**

<ParamField path="name" type="string" required>
  Name of the secret set to create or modify. Must be a valid string identifier
  containing only characters, numbers, and hyphens.
</ParamField>

<ParamField path="secrets" type="string">
  List of secret key-value pairs e.g. `KEY1=value1 KEY2="value with spaces"`.

  See [this note](/pipecat-cloud/fundamentals/secrets#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"'
  ```
</ParamField>

**Options:**

<ParamField path="--file / -f" type="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
  ```
</ParamField>

<ParamField path="--skip / -s" type="boolean" default="false">
  Skip confirmations and proceed with the operation.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization to create/update the secret set in. If not provided, uses the
  current organization from your configuration.
</ParamField>

<ParamField path="--region / -r" type="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.
</ParamField>

**Example:**

Create a secret set in a specific region:

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

## unset

Removes a specific secret key from a secret set.

**Usage:**

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

**Arguments:**

<ParamField path="name" type="string" required>
  Name of the secret set to remove the secret from.
</ParamField>

<ParamField path="secret_key" type="string" required>
  The key of the secret to remove from the set.
</ParamField>

Example:

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

**Options:**

<ParamField path="--skip / -s" type="boolean" default="false">
  Skip confirmations and proceed with the operation.
</ParamField>

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

## delete

Deletes an entire secret set.

**Usage:**

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

**Arguments:**

<ParamField path="name" type="string" required>
  Name of the secret set to delete. This action is irreversible.
</ParamField>

**Options:**

<ParamField path="--skip / -s" type="boolean" default="false">
  Skip confirmations and proceed with the operation.
</ParamField>

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

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

**Usage:**

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

**Arguments:**

<ParamField path="name" type="string" required>
  Name of the credentials set to create or modify. Must be a valid string
  identifier.
</ParamField>

<ParamField path="host" type="string" required>
  Host address of the image repository e.g. `https://index.docker.io/v1/`.
</ParamField>

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

**Options:**

<ParamField path="--encode" type="boolean" default="true">
  Encode the credentials in base64 format. This is enabled by default.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization to create the image pull secret in. If not provided, uses the
  current organization from your configuration.
</ParamField>

<ParamField path="--region / -r" type="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.
</ParamField>

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

***

<Card title="More about secrets" icon="key" href="/pipecat-cloud/fundamentals/secrets">
  Learn more about managing application secrets
</Card>