# Secret Commands

CLI commands for managing secrets.

Source: https://keyenv.dev/docs/cli/secrets/

Commands for managing secrets within a project.

## pull

Pull secrets from the server to a local `.env` file.

```bash
keyenv pull [OPTIONS]
```

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment to pull from (default: development) |
| <code>-f, --force</code> | Overwrite existing file without confirmation |

### Examples

```bash
# Pull development secrets to .env
keyenv pull

# Pull production secrets to .env
keyenv pull -e production

# Pull staging secrets, overwrite existing
keyenv pull -e staging --force
```

---

## push

Push local secrets from a `.env` file to the server.

```bash
keyenv push [OPTIONS]
```

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment to push to (default: development) |
| <code>-f, --force</code> | Overwrite existing secrets |

### Examples

```bash
# Push .env to development
keyenv push

# Force overwrite existing secrets
keyenv push --force
```

### Behavior

Without `--force`:
- New secrets are created
- Existing secrets are skipped
- You'll see a summary: "Created: 5, Skipped: 3"

With `--force`:
- New secrets are created
- Existing secrets are updated
- You'll see: "Created: 2, Updated: 6"

---

## list

List all secrets in the current project (keys only, values hidden).

```bash
keyenv list [OPTIONS]
```

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment (default: development) |

### Examples

```bash
keyenv list

# Secrets (development):
#   • DATABASE_URL (v3)
#   • STRIPE_KEY (v1)
#   • API_SECRET (v2)
#
# 3 secrets
```

### JSON Output

```bash
keyenv list --json
```

```json
{
  "environment": "development",
  "secrets": [
    { "key": "DATABASE_URL", "version": 3 },
    { "key": "STRIPE_KEY", "version": 1 }
  ],
  "count": 2
}
```

---

## get

Get a specific secret value.

```bash
keyenv get <KEY> [OPTIONS]
```

### Arguments

| Argument | Description |
|----------|-------------|
| <code>KEY</code> | The secret key to retrieve |

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment (default: development) |

### Examples

```bash
# Get a secret value
keyenv get DATABASE_URL

# Get from production
keyenv get DATABASE_URL -e production

# Use in scripts
export DB=$(keyenv get DATABASE_URL -q)
```

---

## set

Set a secret value (creates or updates).

```bash
keyenv set <KEY> <VALUE> [OPTIONS]
```

### Arguments

| Argument | Description |
|----------|-------------|
| <code>KEY</code> | The secret key |
| <code>VALUE</code> | The secret value (use <code>-</code> to read from stdin) |

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment (default: development) |
| <code>-g, --generate &lt;TYPE&gt;</code> | Generate a random secret value (type: password, uuid, hex, base64, alphanumeric) |
| <code>-l, --length &lt;N&gt;</code> | Length of generated secret in characters (default: 32, requires --generate) |

### Examples

```bash
# Set a secret
keyenv set DATABASE_URL "postgres://localhost/mydb"

# Set in production
keyenv set API_KEY "sk_live_..." -e production

# Read from stdin (for sensitive values)
echo "super-secret" | keyenv set MY_SECRET -

# Pipe from a command
op read "op://vault/item/password" | keyenv set PASSWORD -

# Generate a random password
keyenv set API_SECRET --generate password

# Generate a UUID
keyenv set REQUEST_ID --generate uuid

# Generate a 64-character hex secret
keyenv set ENCRYPTION_KEY --generate hex --length 64
```

---

## delete

Delete a secret.

```bash
keyenv delete <KEY> [OPTIONS]
```

### Arguments

| Argument | Description |
|----------|-------------|
| <code>KEY</code> | The secret key to delete |

### Options

| Option | Description |
|--------|-------------|
| <code>-e, --env &lt;ENV&gt;</code> | Environment (default: development) |
| <code>-y, --yes</code> | Skip confirmation prompt |

### Examples

```bash
# Delete with confirmation
keyenv delete OLD_API_KEY

# Delete without confirmation
keyenv delete OLD_API_KEY --yes

# Delete from production
keyenv delete DEPRECATED_KEY -e production -y
```

> **Warning**
>
> Deletion is permanent. Consider using version history before deleting if you might need the value later.