# Secrets Commands

Manage secrets on local or remote Gordon instances.

Remote targeting uses client config or an active remote by default.
When you provide a concrete domain and no remote is selected, Gordon can also
auto-infer a saved remote when exactly one match is found.
Use `--remote` and `--token` to override. See [CLI Overview](./index.md).

Storage depends on the secrets backend:
- `pass`: secrets are stored in pass under `gordon/env/<domain>/<KEY>`
- `sops`: secrets live in domain `.env` files and can reference SOPS-encrypted values
- `unsafe`: secrets are stored in plain-text domain `.env` files

## gordon secrets

### Subcommands

| Subcommand | Description |
|------------|-------------|
| `list` | List all secrets for a domain |
| `set` | Set a secret value |
| `remove` | Remove a secret |

---

## gordon secrets list

List all secrets for a specific domain. When attachment secrets are present, they are displayed in a tree view below the domain secrets.

```bash
gordon secrets list <domain>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<domain>` | The domain name to list secrets for |

### Options

| Option | Description |
|--------|-------------|
| `--json` | Output secrets as JSON |
| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
| `--token` | Authentication token for remote |

### Examples

```bash
# Local
gordon secrets list myapp.example.com

# Remote (override)
gordon secrets list myapp.example.com --remote https://gordon.mydomain.com --token $TOKEN
```

### Output

```
Secrets for app.mydomain.com

Key                       Value
DATABASE_URL              ****
API_KEY                   ****
├─ [postgres]
│  ├─ POSTGRES_USER       ****
│  └─ POSTGRES_PASSWORD   ****
└─ [redis]
   └─ REDIS_PASSWORD      ****
```

### JSON Output

```bash
gordon secrets list app.mydomain.com --json
```

```json
{
  "domain": "app.mydomain.com",
  "secrets": {
    "DATABASE_URL": "****",
    "API_KEY": "****"
  },
  "attachments": {
    "postgres": {
      "POSTGRES_USER": "****",
      "POSTGRES_PASSWORD": "****"
    },
    "redis": {
      "REDIS_PASSWORD": "****"
    }
  }
}
```

---

## gordon secrets set

Set a secret value for a domain.

```bash
gordon secrets set <domain> <KEY=value>...
gordon secrets set myapp.example.com DATABASE_URL="postgres://..."
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<domain>` | The domain name to set the secret for |
| `<KEY=value>...` | One or more secret key/value pairs |

### Options

| Option | Description |
|--------|-------------|
| `--attachment` / `-a` | Target an attachment service (e.g., postgres, redis) |
| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
| `--token` | Authentication token for remote |

### Examples

```bash
# Local
gordon secrets set myapp.example.com DATABASE_URL="postgres://user:pass@postgres:5432/db"
gordon secrets set myapp.example.com API_KEY="your-api-key"

# Remote (override)
gordon secrets set myapp.example.com DATABASE_URL="$DATABASE_URL" --remote https://gordon.mydomain.com --token $TOKEN

# Set attachment secrets
gordon secrets set app.mydomain.com --attachment postgres POSTGRES_PASSWORD=secret
gordon secrets set app.mydomain.com -a redis REDIS_PASSWORD=mysecret

# Multiple secrets at once
gordon secrets set app.mydomain.com -a postgres POSTGRES_USER=admin POSTGRES_PASSWORD=secret
```

---

## gordon secrets remove

Remove a secret from a domain.

```bash
gordon secrets remove <domain> <key>
```

### Arguments

| Argument | Description |
|----------|-------------|
| `<domain>` | The domain name |
| `<key>` | The secret key to remove |

### Options

| Option | Description |
|--------|-------------|
| `--attachment` / `-a` | Target an attachment service (e.g., postgres, redis) |
| `--force` | Remove without confirmation |
| `--remote, -r` | Remote name or URL (e.g., prod, https://gordon.mydomain.com) |
| `--token` | Authentication token for remote |

### Examples

```bash
# Local
gordon secrets remove myapp.example.com DATABASE_URL

# Remote (override)
gordon secrets remove myapp.example.com DATABASE_URL --remote https://gordon.mydomain.com --token $TOKEN

# Remove attachment secret
gordon secrets remove app.mydomain.com --attachment postgres POSTGRES_PASSWORD
```

---

## Workflow Examples

### Setting Up Application Secrets

```bash
# Database connection
gordon secrets set myapp.example.com DATABASE_URL="postgres://user:pass@postgres:5432/mydb"

# API keys
gordon secrets set myapp.example.com STRIPE_KEY="sk_live_..."
gordon secrets set myapp.example.com SENDGRID_KEY="SG..."

# JWT secret
gordon secrets set myapp.example.com JWT_SECRET="your-jwt-secret-here"

# Verify
gordon secrets list myapp.example.com
```

### CI/CD Secret Management

```bash
# In your CI/CD pipeline
export GORDON_REMOTE=https://gordon.mydomain.com
export GORDON_TOKEN=$GORDON_TOKEN

# Update secrets before deploy
gordon secrets set myapp.example.com DATABASE_URL="$DATABASE_URL"
gordon secrets set myapp.example.com API_KEY="$API_KEY"

# Deploy
gordon deploy myapp.example.com
```

### Rotating Secrets

```bash
# Generate new secret
NEW_JWT_SECRET=$(openssl rand -base64 32)

# Update the secret
gordon secrets set myapp.example.com JWT_SECRET="$NEW_JWT_SECRET"

# Redeploy to pick up new secret
gordon deploy myapp.example.com
```

### Attachment Secrets

```bash
# Configure database credentials
gordon secrets set app.mydomain.com -a postgres POSTGRES_USER=admin POSTGRES_PASSWORD=secret

# Configure cache credentials
gordon secrets set app.mydomain.com -a redis REDIS_PASSWORD=cache-secret

# Verify
gordon secrets list app.mydomain.com

# Redeploy to pick up new secrets
gordon deploy app.mydomain.com
```

## Related

- [CLI Overview](./index.md)
- [Secrets Configuration](../config/secrets.md)
- [Environment Variables](../config/env.md)