# Secrets and Configuration

Secrets and config let you parameterize values that services need. Use them to avoid hardcoding values in your `specific.hcl`.

## When to use which

- **Secrets** - For sensitive information that should never be committed to version control: API keys, database passwords, signing keys, etc.
- **Config** - For non-sensitive values that may vary between environments: log levels, feature flags, URLs, etc.

## Secrets

Declare secrets that your application needs. Values are stored separately from configuration in `specific.secrets` (gitignored).

```hcl
secret "stripe_api_key" {}

secret "jwt_secret" {
  generated = true
}

service "api" {
  build = build.api
  command = "./api"

  endpoint {
    public = true
  }

  env = {
    STRIPE_API_KEY = secret.stripe_api_key
    JWT_SECRET = secret.jwt_secret
  }
}
```

### Secret fields

- `generated` - When `true`, auto-generates a random 64-character string if not manually set. Useful for internal secrets like JWT signing keys.
- `length` - Custom length for generated secrets (default: 64). Only applies when `generated = true`.

### Setting secret values

For local development with `specific dev` or `specific exec`, use the CLI:

```bash
specific secrets set stripe_api_key
```

This prompts for the value interactively and stores it in `specific.secrets`. Production secrets are configured separately during deployment.

### Generated vs manual secrets

- **Manual secrets** (no `generated` flag) - Must be set via `specific secrets set`. Error on startup if missing.
- **Generated secrets** (`generated = true`) - Auto-created on first run if not set. You can still override manually.

## Config

Parameterize non-sensitive configuration values across environments.

```hcl
config "log_level" {
  default = "info"
}

service "api" {
  build = build.api
  command = "./api"

  endpoint {
    public = true
  }

  env = {
    LOG_LEVEL = config.log_level
  }
}
```

### Config fields

- `default` - Default value used if not overridden by an environment.

### Environment overrides

Override config values per environment:

```hcl
config "log_level" {
  default = "info"
}

environment "production" {
  config = {
    log_level = "warn"
  }
}

environment "staging" {
  config = {
    log_level = "debug"
  }
}
```

## Example

```hcl
# External API key - must be set manually, sensitive
secret "stripe_api_key" {}

# Internal signing key - auto-generate, sensitive
secret "jwt_secret" {
  generated = true
}

# Log level - not sensitive, varies by environment
config "log_level" {
  default = "info"
}

service "api" {
  build = build.api
  command = "./api"

  endpoint {
    public = true
  }

  env = {
    STRIPE_API_KEY = secret.stripe_api_key
    JWT_SECRET = secret.jwt_secret
    LOG_LEVEL = config.log_level
  }
}

environment "production" {
  config = {
    log_level = "warn"
  }
}
```