Skip to main content
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 (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:
Arguments:
string
Name of the secret set list keys for. Must be a valid string identifier.
Options:
boolean
default:"true"
Has no effect: the list always includes image pull secrets, and there is no --no-sets.
string
Organization to list secrets for. If not provided, uses the current organization from your configuration.
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:
Arguments:
string
required
Name of the secret set to create or modify. Letters, numbers, hyphens, and underscores, starting and ending with a letter or number.
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 on using special characters in secret values.Example:
Options:
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:
boolean
default:"false"
Skip confirmations and proceed with the operation.
string
Organization to create/update the secret set in. If not provided, uses the current organization from your configuration.
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:

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:
Options:
string
required
Region to show the keys of.
string
Organization the keys belong to. If not provided, uses the current organization from your configuration.
Example:

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:
Arguments:
string
required
Name of the secret set to remove the secret from.
string
required
The key of the secret to remove from the set.
Example:
Options:
boolean
default:"false"
Skip confirmations and proceed with the operation.
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 for how to free the set first. Usage:
Arguments:
string
required
Name of the secret set to delete. This action is irreversible.
Options:
boolean
default:"false"
Skip confirmations and proceed with the operation.
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 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:
Arguments:
string
required
Name of the credentials set to create or modify. Must be a valid string identifier.
string
required
Host address of the image repository e.g. https://index.docker.io/v1/.
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:
Options:
boolean
default:"true"
Encode the credentials in base64 format. Always on: there is no --no-encode.
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.
string
Organization to create the image pull secret in. If not provided, uses the current organization from your configuration.
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:

reference

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. 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:
Arguments:
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:
string
required
The self-hosted region containing the Secret. Required; Daily-hosted regions are rejected. Must be a region of the organization in use.
string
Organization to create the reference in. If not provided, uses the current organization from your configuration.
Examples:
To remove a reference, use delete; the Secret in your cluster is untouched. Referenced sets cannot be modified with set or unset.

More about secrets

Learn more about managing application secrets