# Variables

Variables store configuration values that can be referenced throughout your HCL files.

Anything you set via `squadron vars set` is automatically available as `vars.<name>` — no `variable` block required. Declaring a `variable` block is only needed when you want to attach metadata like `secret` (for masking) or `default` (fallback when the vault has no value).

## Setting Values

Use the CLI to set variable values:

```bash
squadron vars set api_key sk-ant-...
squadron vars set app_name production-app
```

Values are encrypted at rest in `.squadron/vars.vault`. The vault is initialized automatically the first time you run `squadron engage`. Once set, reference them as `vars.api_key` / `vars.app_name` from any HCL file.

## Defining Variables (optional)

Use `variable` blocks when you want to mark a value as a secret or supply a default:

```hcl
variable "api_key" {
  secret = true  # Mask value in CLI / UI output
}

variable "app_name" {
  default = "myapp"  # Used only if the vault has no value
}

variable "max_retries" {
  default = 3
}
```

## Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `secret` | bool | If true, value is masked in CLI / UI output |
| `default` | any | Default value if not set via `squadron vars set` |

## Referencing Variables

Use `vars.name` to reference a variable:

```hcl
model "anthropic" {
  api_key = vars.api_key
}

agent "assistant" {
  personality = "Assistant for ${vars.app_name}"
}
```

## Resolution Order

1. Value set via `squadron vars set` (encrypted in `.squadron/vars.vault`)
2. Default value from `variable` block (if declared)
3. Empty string if a `variable` block is declared with no default and no vault value
4. HCL evaluation error if `vars.<name>` is referenced but neither the vault nor a `variable` block has it

## Best Practices

### Secrets

Always mark sensitive values as secrets:

```hcl
variable "anthropic_api_key" {
  secret = true
}

variable "database_password" {
  secret = true
}
```

### Defaults for Non-Sensitive Values

Provide defaults for convenience:

```hcl
variable "environment" {
  default = "development"
}

variable "log_level" {
  default = "info"
}
```

### Naming Convention

Use snake_case for variable names:

```hcl
variable "anthropic_api_key" { }  # Good
variable "anthropicApiKey" { }    # Avoid
```