# Secrets Management Commands
Source: https://docs.chain.link/cre/reference/cli/secrets
Last Updated: 2026-04-10

> For the complete documentation index, see [llms.txt](/llms.txt).

> **NOTE: Authentication required**
>
> Running the commands on this page requires you to be logged in with the CRE CLI. Run `cre whoami` in your terminal to
> verify you're logged in, or run `cre login` to authenticate. See [Creating Your
> Account](/cre/account/creating-account) and [Logging in with the CLI](/cre/account/cli-login) for further details.

The `cre secrets` commands manage secrets stored in the Vault DON (Decentralized Oracle Network) for deployed workflows. These commands allow you to create, update, delete, and list secrets that your workflows can access at runtime.

## Auth modes

`cre secrets` supports two authorization modes, mirroring the [private vs. public workflow management split](/cre/guides/operations/deploying-workflows#private-vs-public-workflow-management) used for workflow deployment:

- **Web3-keyed.** Each operation is tied to your linked `workflow-owner-address`. Use this when your workflow is deployed to the onchain registry (`deployment-registry: "onchain:ethereum-mainnet"`).
- **Browser auth (`--secrets-auth=browser`).** Each operation is authorized through a browser-based OAuth (PKCE) flow against the Vault DON gateway, using your CRE login session. No wallet or `workflow-owner-address` required. Use this when your workflow is deployed to the `private` registry, or when secrets are owned at the organization level.

Pass `--secrets-auth=browser` on any of `cre secrets create | update | delete | list` to opt into browser auth for that command. If omitted, the CLI uses the default for your target.

## Authorization flow

Secrets operations use your **workflow owner address** to authorize Vault DON access:

1. The CLI verifies that your workflow owner address is linked to your account on-chain.
2. The CLI submits an allowlist request transaction on the workflow registry chain (signed by your private key, or via multi-sig with `--unsigned`).
3. Once the allowlist entry is confirmed, the CLI encrypts your secrets with the Vault master public key and submits them directly to the Vault DON gateway (CLI v1.8.2+).

This requires a configured `workflow-owner-address` in your project and a linked workflow owner (see `cre account link-key`).

## Org-owned secrets

Starting with CLI v1.10.0, secrets can optionally be owned by your **organization** instead of your individual workflow owner address. When the `CRE_CLI_SECRETS_ORG_OWNED` environment variable is set to `true` in your target configuration, all secrets operations use your org ID (from your authenticated session) as the owner identifier rather than your workflow owner address.

This is useful for teams that share secrets across multiple workflows within an organization, as it decouples secret ownership from individual wallet addresses.

**How it works:**

- When `CRE_CLI_SECRETS_ORG_OWNED=true`, the CLI uses your org ID as the TDH2 encryption label and vault secret owner
- When `CRE_CLI_SECRETS_ORG_OWNED=false` (the default), behavior is unchanged — the workflow owner address is used

**Configuration:**

Add `CRE_CLI_SECRETS_ORG_OWNED: true` to your target environment in your `.env.public` or configuration YAML:

```yaml
CRE_CLI_SECRETS_ORG_OWNED: true
```

You must be authenticated with `cre login` and your session must include a valid org ID for this to work.

## Namespaces

Secrets are organized into **namespaces**, which act as logical groupings (e.g., `"main"`, `"staging"`, `"production"`). All secrets are stored in the `"main"` namespace by default. Currently, `create`, `update`, and `delete` commands only support the default namespace. Custom namespace support may be added in future CLI versions.

> **NOTE: Prerequisites**
>
> - You must be logged in with `cre login` (interactive login required; API keys are not supported for secrets operations)

- Your `workflow-owner-address` must be configured in your project for web3-keyed/onchain registry flows. It is not required for browser-auth private registry flows or when `CRE_CLI_SECRETS_ORG_OWNED=true`.
- If browser auth is not enabled for your CRE environment, use the web3-keyed flow with a linked workflow owner address. See [Using Secrets with Deployed Workflows](/cre/guides/workflow/secrets/using-secrets-deployed).
- For comprehensive guides on using secrets, see [Managing Secrets](/cre/guides/workflow/secrets)

> **NOTE: Global flags**
>
> All `cre` commands support [global flags](/cre/reference/cli#global-flags) like `--env`, `--target`, `--project-root`, and `--verbose`.

## cre secrets create

Creates new secrets in the Vault DON from a YAML file.

### Usage

```bash
cre secrets create [SECRETS_FILE_PATH] [flags]
```

### Arguments

- `SECRETS_FILE_PATH` — (Required) Path to a YAML file containing the secrets to create

### Flags

| Flag             | Type     | Default | Description                                                                                                                                   |
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--timeout`      | duration | `48h`   | Timeout for the operation (e.g., `30m`, `2h`, `48h`). Max: `7d`                                                                               |
| `--unsigned`     | boolean  | `false` | Generate raw transaction data for multi-sig wallets                                                                                           |
| `--secrets-auth` | string   | *auto*  | Authorization mode. Set to `browser` to authorize via browser-based OAuth (PKCE) using your CRE login session. See [Auth modes](#auth-modes). |

### Input file format

YAML file with `secretsNames` structure:

```yaml
secretsNames:
  API_KEY:
    - API_KEY_VALUE

  DATABASE_URL:
    - DATABASE_URL_VALUE
```

- `secretsNames` — Top-level key containing all secrets
- Each secret key (e.g., `API_KEY`) maps to an array containing an environment variable name
- Secret values are read from environment variables or `.env` file

> **NOTE: Default namespace**
>
> Secrets are stored in the `"main"` namespace automatically. Custom namespace support may be added in future CLI versions.

### Examples

- Create secrets from YAML file

  ```bash
  cre secrets create my-secrets.yaml --target production-settings
  ```

- Create secrets with custom timeout

  ```bash
  cre secrets create my-secrets.yaml --timeout 1h
  ```

- Create secrets for multi-sig wallets

  ```bash
  cre secrets create my-secrets.yaml --unsigned
  ```

## cre secrets update

Updates existing secrets in the Vault DON from a YAML file.

### Usage

```bash
cre secrets update [SECRETS_FILE_PATH] [flags]
```

### Arguments

- `SECRETS_FILE_PATH` — (Required) Path to a YAML file containing the secrets to update

### Flags

| Flag             | Type     | Default | Description                                                                                                                                   |
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--timeout`      | duration | `48h`   | Timeout for the operation (e.g., `30m`, `2h`, `48h`). Max: `7d`                                                                               |
| `--unsigned`     | boolean  | `false` | Generate raw transaction data for multi-sig wallets                                                                                           |
| `--secrets-auth` | string   | *auto*  | Authorization mode. Set to `browser` to authorize via browser-based OAuth (PKCE) using your CRE login session. See [Auth modes](#auth-modes). |

### Input file format

Same YAML format as `create`.

### Examples

- Update secrets

  ```bash
  cre secrets update my-secrets.yaml --target production-settings
  ```

- Update secrets with custom timeout

  ```bash
  cre secrets update my-secrets.yaml --timeout 6h
  ```

> **NOTE: Update behavior**
>
> Only modifies secrets that already exist. To create new secrets, use `cre secrets create`.

## cre secrets delete

Deletes secrets from the Vault DON based on a YAML file.

### Usage

```bash
cre secrets delete [SECRETS_FILE_PATH] [flags]
```

### Arguments

- `SECRETS_FILE_PATH` — (Required) Path to a YAML file containing the secrets to delete

### Flags

| Flag             | Type     | Default | Description                                                                                                                                   |
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--timeout`      | duration | `48h`   | Timeout for the operation (e.g., `30m`, `2h`, `48h`). Max: `7d`                                                                               |
| `--unsigned`     | boolean  | `false` | Generate raw transaction data for multi-sig wallets                                                                                           |
| `--secrets-auth` | string   | *auto*  | Authorization mode. Set to `browser` to authorize via browser-based OAuth (PKCE) using your CRE login session. See [Auth modes](#auth-modes). |

### Input file format

YAML file with a simple list of secret identifiers to delete:

```yaml
secretsNames:
  - API_KEY
  - OLD_SECRET
```

> **NOTE: Deletion format**
>
> The `delete` command uses a simpler format than `create`/`update`: just a list of secret IDs. All secrets are deleted from the `"main"` namespace.

### Example

```bash
cre secrets delete secrets-to-delete.yaml --target production-settings
```

> **CAUTION: Permanent deletion**
>
> Deleting secrets is permanent and cannot be undone.

## cre secrets list

Lists all secret identifiers for your owner address (or org ID, when `CRE_CLI_SECRETS_ORG_OWNED=true`) in a specific namespace.

### Usage

```bash
cre secrets list [flags]
```

### Flags

| Flag             | Type     | Default  | Description                                                                                                                                   |
| ---------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `--namespace`    | string   | `"main"` | Namespace to list secrets from                                                                                                                |
| `--timeout`      | duration | `48h`    | Timeout for the operation (e.g., `30m`, `2h`, `48h`). Max: `7d`                                                                               |
| `--unsigned`     | boolean  | `false`  | Generate raw transaction data for multi-sig wallets                                                                                           |
| `--secrets-auth` | string   | *auto*   | Authorization mode. Set to `browser` to authorize via browser-based OAuth (PKCE) using your CRE login session. See [Auth modes](#auth-modes). |

### Example

- List secrets in default namespace

  ```bash
  cre secrets list --target production-settings
  ```

- List secrets in specific namespace

  ```bash
  cre secrets list --namespace production
  ```

### Output

Returns secret identifiers (not values) for the specified namespace:

```
Secret identifiers in namespace 'main':
  - API_KEY
  - DATABASE_URL
  - WEBHOOK_SECRET
```

> **NOTE: Security**
>
> Only returns secret identifiers, never the actual values. Secret values are only accessible to workflows at runtime.

## Using with multi-sig wallets

All commands support the `--unsigned` flag for multi-sig operations:

```bash
cre secrets create my-secrets.yaml --unsigned
```

When `--unsigned` is used:

1. CLI generates raw transaction data instead of broadcasting
2. Transaction payload is returned for submission through your multi-sig interface
3. After multi-sig confirmation, the secrets operation proceeds

For details, see [Using Multi-sig Wallets](/cre/guides/operations/using-multisig-wallets).

## Learn more

- [Managing Secrets](/cre/guides/workflow/secrets) — Overview and decision tree for secrets management
- [Using Secrets in Simulation](/cre/guides/workflow/secrets/using-secrets-simulation) — For local development
- [Using Secrets with Deployed Workflows](/cre/guides/workflow/secrets/using-secrets-deployed) — Complete guide with examples
- [Managing Secrets with 1Password](/cre/guides/workflow/secrets/managing-secrets-1password) — Best practice for secure management
- [Using Multi-sig Wallets](/cre/guides/operations/using-multisig-wallets) — Multi-sig configuration