> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta vault

> Store write-only credentials that agents use but never see.

A vault holds credentials an agent can *use* without ever reading. Values are injected at the network boundary; the agent sees a placeholder reference, never the secret.

## Commands

| Command                         | Description                                       |
| ------------------------------- | ------------------------------------------------- |
| `vetta vault create`            | Create a vault, owned by a persona or by the org. |
| `vetta vault list`              | List vaults.                                      |
| `vetta vault show <vault-id>`   | Show one vault.                                   |
| `vetta vault delete <vault-id>` | Delete a vault.                                   |
| `vetta vault set`               | Seal a credential into a vault.                   |
| `vetta vault credentials`       | List a vault's credentials — metadata only.       |
| `vetta vault rm`                | Delete one credential.                            |

<Warning>
  **There is no reveal command, and there never will be one.** No route returns a credential value and the credential schema has no value field, so a `vault get-value` could only be a lie. If you need the secret, read it from wherever you originally got it.
</Warning>

## create

```bash theme={"system"}
vetta vault create --name "ava-vault" --identity idn_6sc5s97c5jt1ds84qngajv659p
```

| Flag         | Description                                               |
| ------------ | --------------------------------------------------------- |
| `--name`     | Display name (required).                                  |
| `--identity` | Persona that owns the vault. Omit for an org-level vault. |

## list & show

```bash theme={"system"}
vetta vault list --limit 3
```

```json theme={"system"}
{
  "data": [
    {
      "id": "vlt_pdraff46ykspz0cjsdtdjxayck",
      "object": "vault",
      "identity_id": "idn_6sc5s97c5jt1ds84qngajv659p",
      "display_name": "ava-vault",
      "credential_count": 1,
      "created_at": "2026-08-22T23:47:55.443Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

`list` returns **vaults**, not credentials — a vault is a container and reports only how many credentials it holds. Use `vault credentials` for what is inside one.

`show` and `delete` take the vault id as a positional argument and accept no flags.

## set

Three kinds of credential, each named by the flag carrying its destination. Pass **exactly one**:

```bash theme={"system"}
# An environment variable, bound to one exact destination host
printf '%s' "$STRIPE_KEY" | vetta vault set --vault vlt_pdraff46ykspz0cjsdtdjxayck \
  --env PAYMENTS_API_KEY --host api.stripe.com

# A static bearer token for an MCP server
printf '%s' "$TOKEN" | vetta vault set --vault vlt_... --mcp-bearer https://mcp.example.com/mcp

# An OAuth-backed MCP server
printf '%s' "$TOKEN" | vetta vault set --vault vlt_... --mcp-oauth https://mcp.example.com/mcp
```

| Flag           | Description                                                          |
| -------------- | -------------------------------------------------------------------- |
| `--vault`      | Vault id. Also accepted as the first positional argument.            |
| `--env`        | Credential is an env var with this name. Requires `--host`.          |
| `--mcp-bearer` | Credential is a static bearer for this MCP server URL.               |
| `--mcp-oauth`  | Credential is an OAuth token for this MCP server URL.                |
| `--key`        | Label for an MCP credential. Defaults to the MCP URL's host.         |
| `--host`       | Destination host. **Required** with `--env`; optional for MCP kinds. |
| `--value`      | The secret inline. For CI only — see below.                          |
| `--expires-at` | ISO-8601 expiry.                                                     |

<Warning>
  **The secret comes from stdin by default,** because an argv secret is visible in `ps` and lands in shell history. `--value` exists for CI, where the value already comes from a secret store and argv is not shared. Passing neither is an error, not an empty secret.
</Warning>

An `env_var` credential is bound to one exact destination host. The injector never wildcards, which is why `--host` is required: a key scoped to `api.stripe.com` cannot leak to any other host the agent reaches.

## credentials

```bash theme={"system"}
vetta vault credentials --vault vlt_pdraff46ykspz0cjsdtdjxayck
```

```json theme={"system"}
{
  "data": [
    {
      "id": "vcr_a715wa9fhs708x22gtd4gdd05t",
      "object": "vault_credential",
      "vault_id": "vlt_pdraff46ykspz0cjsdtdjxayck",
      "kind": "static_bearer",
      "key": "ava-token",
      "host": null,
      "mcp_server_url": "https://mcp.example.com/mcp",
      "placeholder_ref": "vetta_ref_1gvh481f72n7kv0jx4tzbwxf66",
      "expires_at": null,
      "last_injected_at": null,
      "created_at": "2026-08-22T23:47:56.109Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

`placeholder_ref` is what the agent actually handles. `last_injected_at` is the audit signal: it tells you the credential was used, and when, without telling you what it is.

| Flag                  | Description                                               |
| --------------------- | --------------------------------------------------------- |
| `--vault`             | Vault id. Also accepted as the first positional argument. |
| `--limit` / `--after` | Pagination.                                               |

## rm

```bash theme={"system"}
vetta vault rm --vault vlt_... --credential vcr_a715wa9fhs708x22gtd4gdd05t
```

| Flag           | Description                                                     |
| -------------- | --------------------------------------------------------------- |
| `--vault`      | Vault id. Also accepted as the first positional argument.       |
| `--credential` | Credential id. Also accepted as the second positional argument. |

## Rotating a credential

There is no update command. **Rotation is `set` a new credential, then `rm` the old one:**

```bash theme={"system"}
printf '%s' "$NEW_KEY" | vetta vault set --vault vlt_... --env PAYMENTS_API_KEY --host api.stripe.com
vetta vault rm --vault vlt_... --credential vcr_old...
```

A credential is immutable by design, so `last_injected_at` stays attributable to exactly one secret. An in-place update would make "when was this value last used?" unanswerable at exactly the moment you most need it — during an incident.