Skip to main content
gaal reads configuration from up to three files. They merge in a strict order so a workspace gaal.yaml checked into source control can never escalate machine-wide settings.

​
The three scopes

Higher-priority files override lower ones field by field.

​
What overrides what

Most fields are merged with workspace winning over user winning over system:
  • repositories, workspace entries replace user entries with the same map key.
  • skills, the workspace list replaces the user list (no per-entry merging, pick one scope or the other).
  • mcps, same as skills: workspace list replaces user list.
The exception is telemetry, which is scope-restricted.

​
Scope-restricted fields

telemetry can be set in the user or system file but not in a workspace file. If a workspace gaal.yaml sets telemetry:, gaal ignores the value and prints a warning. This rule exists so that committing a gaal.yaml to a public repo can never opt anyone in to telemetry. Telemetry is a per-user choice, made explicitly on first run.

​
Where you’d put what

​
Inspecting the merged config

gaal status reports the resolved configuration as gaal sees it after merging. gaal doctor reports the source file for each entry.

​
Overriding the lookup

Force a specific file with --config:
When --config is set, the user and system files are still merged underneath unless the file you passed sets the same fields.

The gaal.yaml file

Telemetry

Sharing across machines

gaal doctor