Configuration

gest uses hierarchical TOML configuration files that are merged together at runtime. Settings closer to your working directory take precedence over global defaults, giving you fine-grained control per project.

Config file locations

gest searches for configuration in two layers: a global config and project-level configs.

Global config

The global config lives at your platform's config home:

Platform	Path
Linux	~/.config/gest/config.toml
macOS	~/Library/Application Support/gest/config.toml

You can override this location with the GEST_CONFIG environment variable.

Project config

Within each directory from the filesystem root down to your working directory, gest checks for project config files in the following order (first match wins):

1. .config/gest.toml
2. .gest/config.toml
3. .gest.toml

When multiple config files are found at different directory levels, they are deep-merged with files closer to the working directory taking precedence.

Data storage: global vs local

gest stores its data (tasks, artifacts, iterations) in a project directory inside a global data root. Each is resolved independently.

Global data root

The global data root is the parent directory that contains all project-specific subdirectories. It is resolved with this precedence:

1. $GEST_DATA_DIR environment variable (must be an absolute path)
2. storage.data_dir in config (must be an absolute path)
3. The platform's global data home: ~/.local/share/gest/

Project directory

The project directory is where entity data for the current project is actually stored. It is resolved with this precedence:

1. $GEST_PROJECT_DIR environment variable (must be an absolute path)
2. storage.project_dir in config (must be an absolute path)
3. A .gest/ directory found by walking up from the working directory
4. <data_dir>/<hash>/ (a subdirectory of the global data root derived from a hash of your project path)

Global store (default)

By default, gest init sets up the global store. Data is kept under ~/.local/share/gest/ in a subdirectory derived from a hash of your project path. This keeps your project directory clean and works well for personal use.

# Initialize with the global store (default)
gest init

Local store

Use gest init --local to create a .gest/ directory inside your project. This is useful when you want to commit gest data alongside your code or share it with collaborators.

# Initialize with a local .gest/ directory
gest init --local

State storage (event store)

Separately from entity data, gest maintains a state directory for local operational state such as the undo event store. The state directory is always global (never inside the repo) and is resolved with this precedence:

1. $GEST_STATE_DIR environment variable (must be an absolute path)
2. storage.state_dir in config (must be an absolute path)
3. The platform's global state home: ~/.local/state/gest/<hash>/

The state directory is created automatically on first use. It is not version-controlled and does not sync between machines — undo history is local to each workstation.

Per-entity directory overrides

By default, all entity types (artifacts, tasks, iterations) are stored under the resolved data directory. You can override the storage location for each entity type independently using environment variables or config settings.

The resolution precedence for each entity type is:

1. Entity-specific environment variable (e.g. GEST_ARTIFACT_DIR)
2. Entity-specific config setting (e.g. storage.artifact_dir)
3. <project_dir>/<entity>/ (default fallback)

For example, to keep artifacts in your project's docs/ directory and tasks in tasks/ while letting iterations use the default:

[storage]
artifact_dir = "./docs"
task_dir = "./tasks"

This produces the following layout:

docs/<id>.md
docs/archive/<id>.md
tasks/<id>.toml
tasks/resolved/<id>.toml
<project_dir>/iterations/<id>.toml
<project_dir>/iterations/resolved/<id>.toml

gest init respects these overrides and creates directories at the resolved paths.

Configuration settings

For a dedicated guide to terminal UI color customization, see Theming.

[storage]

Key	Type	Default	Description
data_dir	string (absolute path)	(auto-resolved)	Override the global data root directory. Must be an absolute path.
project_dir	string (absolute path)	(auto-resolved)	Override the project-specific data directory. Must be an absolute path.
state_dir	string (absolute path)	(auto-resolved)	Override the state directory (event store). Must be an absolute path.
artifact_dir	string (path)	<project_dir>/artifacts	Override the artifact storage directory.
iteration_dir	string (path)	<project_dir>/iterations	Override the iteration storage directory.
task_dir	string (path)	<project_dir>/tasks	Override the task storage directory.

[serve]

Key	Type	Default	Description
bind_address	string (IP address)	"127.0.0.1"	IP address the web server binds to.
port	integer	2300	Port the web server listens on.
open	boolean	true	Whether to automatically open the browser when the server starts.
debounce_ms	integer	2000	File-watcher debounce window in milliseconds. Controls how long the server waits before triggering a live reload.
log_level	string	"info"	Log level for the server process. Overrides the global [log].level when running gest serve. Same valid values.

[log]

Key	Type	Default	Description
level	string	"warn"	Log level filter. Valid values: "error", "warn", "info", "debug", "trace".

[colors]

The [colors] section controls terminal UI colors through palette slots and per-token overrides. See the Theming guide for the full reference, including palette slots, token overrides, color formats, and the complete token list.

Example config file

[storage]
project_dir = "/home/user/projects/myapp/.gest"
artifact_dir = "./docs"
task_dir = "./tasks"

[serve]
port = 8080
open = false
debounce_ms = 1000
log_level = "debug"

[log]
level = "info"

[colors.palette]
primary = "#5AB0FF"

[colors.overrides]
"log.error" = "#D23434"

Environment variables

Variable	Description
GEST_CONFIG	Override the path to the global config file.
GEST_DATA_DIR	Override the global data root directory (must be an absolute path).
GEST_PROJECT_DIR	Override the project-specific data directory (must be an absolute path).
GEST_STATE_DIR	Override the state directory for the event store (must be an absolute path).
GEST_ARTIFACT_DIR	Override the artifact storage directory.
GEST_ITERATION_DIR	Override the iteration storage directory.
GEST_TASK_DIR	Override the task storage directory.
GEST_LOG_LEVEL	Override the log level filter (e.g. debug, trace). Takes precedence over the config file.
VISUAL	Preferred editor for interactive editing (checked before EDITOR).
EDITOR	Fallback editor for interactive editing.
PAGER	Preferred pager program (falls back to less).

Managing config from the CLI

gest provides subcommands to inspect and modify configuration without editing files by hand.

gest config show

Displays the merged configuration and the config file sources that were discovered:

gest config show

gest config get <KEY>

Retrieve a single value by its dot-delimited key:

gest config get storage.project_dir
gest config get log.level

gest config set <KEY> <VALUE>

Persist a value to the project config file (or use --global for the global config):

# Set in the project config
gest config set log.level debug

# Set in the global config
gest config set --global log.level warn