Configuration Reference¶

Complete reference for every field in ~/.config/yak/config.toml (or config.yaml).

Global defaults¶

Top-level fields that apply to all accounts unless overridden at the account level.

1
2
3

default_account = "dev"
default_role    = "admin"
use_active_role = false

[aws]¶

Paths for the AWS files that yak generates and writes to.

1
2
3
4
5
6

[aws]
credentials_path = "~/.aws/credentials"
config_path      = "~/.aws/config"
region           = "eu-west-1"
sso_start_url    = "${AWS_SSO_URL}"
sso_session_name = "yak"

[paths]¶

Overrides yak runtime directories. If omitted, yak falls back to ~/.local/share/yak.

1
2
3
4

[paths]
cache_dir = "~/.local/share/yak"
state_dir = "~/.local/share/yak"
log_dir   = "~/.local/share/yak"

[secrets]¶

Controls caching of op:// values. Has no effect on ${VAR} or plain text values.

1
2

[secrets]
cache_ttl = 60

[safeguards]¶

Guards against accidentally using elevated roles on production-like accounts.

1
2
3
4
5

[safeguards]
enabled                 = true
protected_accounts      = ["prod", "mgmt"]
protected_pattern       = ""
max_power_grade_allowed = "developer"

[roles]¶

Defines the role tiers available across all accounts. Role names are used in yak role, allowed_roles, and role_overrides.

Each role has a built-in power grade — a numeric value yak uses to compare role privilege levels for safeguard enforcement. You cannot assign a power grade to a role that is not in this built-in list.

Plain string (recommended)¶

1
2
3
4
5

[roles]
read_only = "${AWS_VIEWER_ROLE}"
developer = "${AWS_DEVELOPER_ROLE}"
admin     = "${AWS_ELEVATED_ROLE}"
root      = "${AWS_GODMODE_ROLE}"

Table form (only needed to override the built-in power grade)¶

1
2
3
4
5

[roles]
read_only = { value = "${AWS_VIEWER_ROLE}", power_grade = 100 }
developer = { value = "${AWS_DEVELOPER_ROLE}", power_grade = 200 }
admin     = { value = "${AWS_ELEVATED_ROLE}", power_grade = 300 }
root      = { value = "${AWS_GODMODE_ROLE}", power_grade = 400 }

You do not need to use the table form unless you have a specific reason to deviate from the built-in power grades.

[[accounts]]¶

Defines an AWS account. Repeat the [[accounts]] block for each account.

Minimal account (inherits all global defaults)¶

1
2
3

[[accounts]]
name       = "dev"
account_id = "${AWS_DEV_ACCOUNT_ID}"

Account with restrictions and role overrides¶

1
2
3
4
5
6

[[accounts]]
name           = "prod"
account_id     = "${AWS_PROD_ACCOUNT_ID}"
default_role   = "developer"
allowed_roles  = ["read_only", "developer", "admin"]  # root intentionally excluded
role_overrides = { admin = "${AWS_ADMIN_ROLE}", read_only = "${AWS_READ_ROLE}" }

Role resolution order¶

When yak needs to resolve the role ARN for an account, it applies these rules in order:

1. Determine active role tier — from CLI flag; otherwise from yak role state when use_active_role = true; otherwise account default_role, falling back to global default_role
2. Check allowed_roles — if defined, the active tier must be listed or yak exits with an error
3. Check safeguards — if the account is protected and the tier's power grade exceeds max_power_grade_allowed, yak blocks the operation (unless --bypass-safeguards is passed)
4. Check role_overrides — if the account has an override for the active tier, use that role value
5. Fall back to global [roles] — use the global value for this tier
6. Construct the ARN — arn:aws:iam::{account_id}:role/{resolved_role_name}

[aliases.accounts]¶

Short aliases that map to account names. Defined once, applies globally.

1
2
3
4
5
6

[aliases.accounts]
d      = "dev"
sb     = "sandbox"
t      = "test"
p      = "prod"
m      = "mgmt"

Usage: yak account p is equivalent to yak account prod.

[aliases.roles]¶

Short aliases that map to role tier names.

1
2
3
4
5

[aliases.roles]
ro  = "read_only"
dev = "developer"
adm = "admin"
rt  = "root"

Usage: yak role adm is equivalent to yak role admin.

Full example¶

See the examples section for complete configs in all four format and secret provider combinations.