> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Secrets commands
description: Reference for creating, listing, and deleting project secrets from the CLI.
category: CLI
last_verified: 2026-07-24
hideRightSidebar: true
---

**`agnt5 secrets`** manages secure, project-scoped storage for API keys, database URLs, and other credentials your workers need at runtime. Secrets can optionally be scoped to a single environment.


**Commands**: `agnt5 secrets list`, `agnt5 secrets set`, `agnt5 secrets get <name>`, `agnt5 secrets delete <name>`
**Aliases**: `agnt5 secret` for `agnt5 secrets`
**Required**: `--name`/`-n` and `--type`/`-t` on `set`; project resolved from `--project`/`-p` or the linked directory
**Side effects**: `set` creates or overwrites a secret; `delete` is permanent and irreversible


## Command summary

| Command | Purpose |
| --- | --- |
| `secrets list` | List secrets for a project (values masked). |
| `secrets set` | Create or update a secret. |
| `secrets get <name>` | Get details of a secret. |
| `secrets delete <name>` | Permanently delete a secret. |

## `agnt5 secrets list`

```bash
agnt5 secrets list [options]
```

Lists secrets for a project. Values are always masked.

| Flag | Description |
| --- | --- |
| `--project <id\|ref>`, `-p` | Project ID or ref. Optional if run from a linked project directory. |
| `--environment <id>`, `-e` | Filter by environment ID. |
| `--type <type>`, `-t` | Filter by type: `api_key`, `database_url`, `oauth_token`, `ssh_key`, `certificate`, `other`. |
| `--page <n>` | Page number. Default: `1`. |
| `--page-size <n>` | Results per page. Default: `20`. |

```bash
agnt5 secrets list
agnt5 secrets list --type api_key --environment env_prod
```

## `agnt5 secrets set`

```bash
agnt5 secrets set --name <name> --type <type> [options]
```

Creates or updates a secret. The value is **not** a positional argument — provide it interactively (default, hidden input), inline with `--secret` (not recommended), or via `--stdin`.

| Flag | Description |
| --- | --- |
| `--project <id\|ref>`, `-p` | Project ID or ref. Optional if run from a linked project directory. |
| `--name <name>`, `-n` | Secret name. **Required.** |
| `--type <type>`, `-t` | `api_key`, `database_url`, `oauth_token`, `ssh_key`, `certificate`, or `other`. **Required.** |
| `--secret <value>`, `-s` | Secret value, inline. Not recommended — visible in shell history. |
| `--environment <id>`, `-e` | Scope the secret to one environment. |
| `--stdin` | Read the secret value from stdin. |
| `--dry-run` | Show the request that would be sent without creating or updating. |

```bash
agnt5 secrets set --name STRIPE_API_KEY --type api_key
echo -n "$STRIPE_KEY" | agnt5 secrets set --name STRIPE_API_KEY --type api_key --stdin
agnt5 secrets set --name DATABASE_URL --type database_url --environment env_prod
```

## `agnt5 secrets get`

```bash
agnt5 secrets get <secret-id-or-name> [options]
```

Gets details of a secret. The value is masked unless `--reveal` is set and the backend supports it.

| Flag | Description |
| --- | --- |
| `--project <id\|ref>`, `-p` | Project ID or ref. Optional if run from a linked project directory. |
| `--reveal` | Show the full secret value. |

```bash
agnt5 secrets get STRIPE_API_KEY
agnt5 secrets get STRIPE_API_KEY --reveal
```

## `agnt5 secrets delete`

```bash
agnt5 secrets delete <secret-id-or-name> [options]
```

Permanently deletes a secret. This cannot be undone.

| Flag | Description |
| --- | --- |
| `--project <id\|ref>`, `-p` | Project ID or ref. Optional if run from a linked project directory. |
| `--force`, `-f` | Skip the confirmation prompt. |
| `--dry-run` | Show what would be deleted without executing. |

```bash
agnt5 secrets delete old-webhook-secret
agnt5 secrets delete old-webhook-secret --force
```

## Next steps

- [Service keys](/docs/cli/service-keys.md): programmatic API keys for CI/CD, distinct from project secrets.
- [Deploy commands](/docs/cli/deploy.md): secrets are available to workers once deployed.
- [Configuration](/docs/cli/configuration.md): environment resolution and where credentials live locally.
- [Auth commands](/docs/cli/auth.md): log in before managing secrets.