Shoal has two related configuration loaders. The main loader controls shell behavior; the prompt loader understands a richer prompt schema and also reads a dedicated prompt.toml. Knowing where they intentionally differ prevents most surprising configurations.
Main configuration precedence🔗
The main loader deep-merges four layers from lowest to highest precedence:
/etc/shoal/shoal.toml$XDG_CONFIG_HOME/shoal/shoal.toml, or~/.config/shoal/shoal.toml- the nearest
.shoal.tomlfound by walking from the current directory toward the filesystem root - supported environment overrides
Only the nearest project file participates. Tables merge key by key, so a project can replace history.max_entries without copying the rest of [history].
flowchart TB
accTitle: Configuration and prompt precedence
accDescr: Core configuration merges system, user, project, and environment layers; prompt configuration then applies its theme and prompt-specific layers.
subgraph Core["Core configuration"]
S["system shoal.toml"] --> M["deep merge"]
U["user shoal.toml"] --> M
P["nearest ancestor .shoal.toml"] --> M
E["SHOAL_* and NO_COLOR"] --> M
M --> V["validate typed runtime config"]
end
subgraph Prompt["Prompt configuration"]
T["built-in theme"] --> PM["prompt merge"]
V --> PM
PP["prompt-specific project settings"] --> PM
PM --> R["prompt snapshot and renderer"]
endA missing file is normal. Malformed TOML, a wrong value type, or an invalid constrained value is a startup error. Unknown keys produce warnings, including a spelling suggestion when one is close enough; they are not accepted silently.
A practical user configuration🔗
Put this at $XDG_CONFIG_HOME/shoal/shoal.toml (usually ~/.config/shoal/shoal.toml) and trim it to taste:
version = 1
[history]
enabled = true
max_entries = 20000
dedup = true
ignore_space = true
ignore = ["token *", "secret *"]
[render]
color = true
paging = "auto"
pager = "less -R"
echo = "quiet"
[editor]
mode = "emacs"
bracketed_paste = true
[completion]
fuzzy = true
case_insensitive = true
menu = true
max_results = 100
[aliases]
gs = "git status"
la = "ls --all"
[env]
EDITOR = "nvim"
PAGER = "less -R"
[init]
files = ["~/.config/shoal/interactive.shl"]Aliases are parsed as Shoal source at startup, rather than pasted into a Bourne shell. Environment entries populate Shoal’s session environment. Init files run in order at the start of an interactive session; keep machine-dependent setup in the user file and repository conventions in .shoal.toml.
Validation and diagnostics🔗
Configuration loading distinguishes warnings from hard errors. This matters operationally: an unknown future/typo key does not prevent startup, while a value of the wrong type or an invalid constrained value does.
Unknown keys are warnings🔗
Every key actually present in a loaded file is checked against the generic configuration schema. An unrecognized dotted path is preserved as a warning with its source file and, when a sibling key is sufficiently close, a spelling suggestion:
/home/dev/.config/shoal/shoal.toml: unknown config key `editor.bracketde_paste` (did you mean `editor.bracketed_paste`?)When no candidate is close enough, no misleading suggestion is invented. Rich prompt keys under [prompt] are a known exception in practice: the generic loader only formally knows prompt.template, while the separate prompt loader understands the larger schema. Put rich configuration in prompt.toml to avoid those warnings.
Type mismatches are hard errors🔗
The loader reports the exact dotted key and expected shape before falling through to a generic deserializer message:
/home/dev/.config/shoal/shoal.toml: history.max_entries: expected a non-negative integer, found stringArray and map locations include their precise index/key, such as adapters.dirs[1] or aliases.gs. Existing files that cannot be read are also errors; a file that does not exist is simply an absent layer.
Malformed TOML is a hard error🔗
Syntax errors retain TOML’s line/column diagnostic and are prefixed with the source path. User-controlled config parsing returns a structured error rather than panicking.
Semantic constraints🔗
Values that parse and have the right TOML type still must satisfy these rules:
| Key | Requirement |
|---|---|
version | exactly 1 |
history.max_entries | greater than zero |
editor.mode | emacs or vi |
render.paging | never or auto |
render.echo | quiet, commands, or all when present |
completion.max_results | greater than zero |
| alias names | nonempty and contain no whitespace |
| environment names | nonempty |
every history.ignore pattern | nonempty |
Representative messages are stable and actionable:
version: unsupported config version 2 (expected 1)
history.max_entries: must be greater than 0
editor.mode: must be `emacs` or `vi`
aliases: alias name `g s` must not contain whitespaceThe main loader validates the [reef] containers loosely enough for Reef to reparse its richer tool/runner grammar. Consult Reef tool resolution for that contract.
Main configuration reference🔗
The table below reflects the schema and defaults in the current code. An empty “runtime note” means the setting is wired on the relevant shell surface.
| Key | Type and default | Runtime note |
|---|---|---|
version | integer, 1 | Configuration format version. |
prompt.template | string, "{cwd}" | Legacy prompt form; prefer prompt.toml. |
history.enabled | boolean, true | Interactive history only. |
history.max_entries | integer, 10000 | Caps retained file entries. |
history.path | path, platform default | Explicit history file. |
history.dedup | boolean, true | Skips a line identical to the immediately previous entry. |
history.ignore | string list, empty | Whole-line shell-style */? patterns excluded from history. |
history.ignore_space | boolean, true | A line beginning with a space is not recorded. |
render.color | boolean, true | NO_COLOR can disable it. |
render.width | positive integer or absent | Overrides terminal detection for block tables, prompt context, protocol rendering, wrapping, and pager decisions. |
render.paging | "never" or "auto", "never" | Paging is interactive and TTY-sensitive. |
render.pager | command string or absent | Falls back to $PAGER, then less -R. |
render.echo | "quiet", "commands", "all", or absent | Surface default: all in the REPL, quiet for scripts and -c. |
editor.mode | "emacs" or "vi", "emacs" | Selects the interactive editing mode. |
editor.bracketed_paste | boolean, true | Controls paste handling. |
editor.keybindings | chord-to-action table, empty | Extends or replaces actions for named chords. |
completion.fuzzy | boolean, true | Allows non-prefix matching. |
completion.case_insensitive | boolean, true | Applies to candidate matching. |
completion.max_results | integer, 100 | Bounds the candidate set. |
completion.menu | boolean, true | false enables quick/shared-prefix completion, but a popup can still appear when ambiguous candidates have no common prefix. |
adapters.dirs | path list, empty | Adds adapter catalogs; see the caveat below. |
init.files | path list, empty | Interactive startup scripts, in order. |
aliases | string table, empty | Persistent session aliases. |
env | string table, empty | Initial session environment. |
reef.tools | constraint table, empty | User-scope Reef constraints. |
reef.runners | runner table, empty | User-scope script runners. |
reef.options.hermetic | boolean, false | Removes the ambient PATH tail when engaged. |
kernel.enabled | boolean, true | The default interactive REPL runs through an isolated private shoal-kernel child. Set false (or pass --standalone) for the local evaluator path. |
kernel.session | string, "default" | Names the principal-private Session inside the default REPL’s private kernel. It does not attach to a durable public kernel socket. |
journal.enabled | boolean, true | Enables language-facing history/journal/undo; it never disables mandatory kernel security/approval/event audit. |
journal.state_dir | path or absent | Local language journal/jump and embedded-kernel state root; relative paths resolve from startup cwd. |
leash.policy | path or absent | Loaded fail-closed by the shared host bootstrap for local/kernel evaluators and passed to the default private REPL kernel. |
history.dedup compares with the immediately preceding entry, including the last entry read from a previous session. An environment name that is nonempty but cannot be expressed as a Shoal identifier can pass generic validation yet produce a startup warning when the host tries to apply it.
The default interactive REPL spawns a listener-free private kernel and connects over an inherited anonymous descriptor. Each shell gets isolated live bindings, it/out, cwd, jobs, and policy state; it does not join the named-socket kernel used by MCP/agents. shoal --standalone and kernel.enabled = false select the in-process evaluator path. Kernel process flags and token policy are documented in Agents, kernel, and MCP; durable execution history is covered in Filesystem, jobs, and history.
Adapter-directory precedence🔗
adapters.dirs is an ordered extension path. The bundled catalog loads first; each configured directory overlays it, and a later definition replaces only a matching command head. Shoal warns when an overlay shadows an earlier head. Completion and dispatch are assembled from the same ordered catalog set. Use ^command when you deliberately want to bypass the resulting adapter.
Environment overrides🔗
Boolean overrides accept 1, true, yes, or on for true, and 0, false, no, or off for false, case-insensitively.
| Environment variable | Configuration target |
|---|---|
NO_COLOR | disables render.color |
SHOAL_PROMPT_TEMPLATE | prompt.template |
SHOAL_PROMPT | legacy prompt.template; also a deprecated rich-prompt left-format alias |
SHOAL_HISTORY_ENABLED / SHOAL_HISTORY | history.enabled |
SHOAL_HISTORY_MAX_ENTRIES | history.max_entries |
SHOAL_HISTORY_FILE | history.path |
SHOAL_HISTORY_DEDUP | history.dedup |
SHOAL_RENDER_COLOR | render.color |
SHOAL_RENDER_WIDTH | render.width |
SHOAL_RENDER_PAGING | render.paging |
SHOAL_RENDER_PAGER | render.pager |
SHOAL_RENDER_ECHO | render.echo |
SHOAL_EDITOR_MODE | editor.mode |
SHOAL_EDITOR_BRACKETED_PASTE | editor.bracketed_paste |
SHOAL_KERNEL_ENABLED / SHOAL_KERNEL | kernel.enabled |
SHOAL_KERNEL_SESSION | kernel.session |
SHOAL_JOURNAL_ENABLED | journal.enabled |
SHOAL_LEASH_POLICY | leash.policy |
SHOAL_COMPLETION_FUZZY | completion.fuzzy |
SHOAL_COMPLETION_CASE_INSENSITIVE | completion.case_insensitive |
SHOAL_COMPLETION_MAX_RESULTS | completion.max_results |
SHOAL_COMPLETION_MENU | completion.menu |
Avoid SHOAL_PROMPT: the two loaders retain different legacy meanings for it. Use SHOAL_PROMPT_LEFT for the rich prompt or SHOAL_PROMPT_TEMPLATE for the legacy template.
Rich prompt configuration🔗
The safest place for the current prompt schema is:
$XDG_CONFIG_HOME/shoal/prompt.tomlIts root is the prompt configuration itself—do not wrap it in [prompt].
theme = "rich"
nerd_font = "auto"
unicode = true
right_prompt_on_last_line = false
[format]
left = "$directory$git_branch$git_status$reef$character"
right = "$cmd_duration $jobs $time"
continuation = "... "
transient = "$character "
[transient]
enabled = false
[budget]
render_deadline_ms = 5
warn_on_exceed = true
[style]
ok = "green bold"
error = "red bold"
warn = "yellow bold"
info = "blue"
muted = "8"
accent = "purple"
[module.directory]
repo_relative = true
truncate_to = 3
truncate_style = "middle"
style = "cyan bold"
[module.cmd_duration]
min_ms = 500
[module.time]
format = "%H:%M:%S"
style = "dim"Directory truncate_style is exact: start removes leading components, end removes trailing components, and middle retains both edges while favoring the trailing half. Invalid values warn and use middle.
Built-in themes are default, minimal, and rich. A theme is the lowest-precedence prompt layer; your explicit settings override it.
Prompt precedence🔗
The prompt loader merges these sources from low to high:
- the named built-in theme
/etc/shoal/shoal.toml’s[prompt]table- the user
shoal.toml’s[prompt]table - the user
prompt.tomlroot - the nearest ancestor
.shoal.toml’s[prompt]table - prompt environment overrides
Prompt and core project configuration use the same nearest-ancestor discovery function and therefore select the same .shoal.toml. The core loader treats the rich [prompt] subtree as owned by the prompt schema, avoiding false unknown-key warnings; the bounded prompt loader still performs its complete dynamic-key/type validation and strips executable custom modules from this untrusted project layer.
The prompt-specific overrides are SHOAL_PROMPT_LEFT, SHOAL_PROMPT_RIGHT, SHOAL_PROMPT_THEME, and SHOAL_NERD_FONT. For the font variable, 1 means always and 0 means never.
Prompt files are advisory and bounded. A missing file is ignored; an unreadable, non-regular, non-UTF-8, malformed, or larger-than-1-MiB file produces a warning and is skipped without stopping the shell. The loader also rejects excessively deep or wide TOML, strings or recognized prompt environment values above 64 KiB, and more than 128 custom or language modules. Other valid prompt layers and built-in defaults continue to work.
Format placeholders🔗
A format string combines literal text with $module_id placeholders. The fixed IDs are:
character directory git_branch git_status git_state cmd_duration
exit_status jobs time username hostname reef principal leash battery$indent is also recognized. Dynamic modules use $language_NAME and $custom_NAME, where NAME is the table key under [module.language] or [module.custom].
[format]
left = "$directory$git_branch$language_rust$custom_cluster$character"
[module.language.rust]
tool = "rustc"
symbol = "rs "
style = "red"
when = "constrained"
format = "${symbol}${version} "
[module.custom.cluster]
command = "kubectl config current-context"
when = "KUBECONFIG"
cache_ttl = "10s"
style = "blue bold"
format = "${output} "These dynamic tables have a sharp type boundary: language.when, custom.command, custom.when, and custom.cache_ttl are strings, not arrays or numeric durations. A wrong type makes the rich prompt fail deserialization and fall back to the complete default prompt, with a warning.
Language modules render existing Reef bindings rather than launching a second prompt-specific probe. when = "constrained" requires a constrained binding; when = "resolved" requires a resolved version. Any other value warns and falls back to constrained. The former probe_ttl_s field was removed because Reef already owns discovery/cache freshness and the prompt had no independent probe to cache.
When the battery module is enabled, the host samples Linux power-supply attributes directly or a bounded pmset -g batt call on macOS. Sampling happens outside rendering and is cached for sample_interval_s (clamped to one day); zero requests a fresh sample after every command. Multiple batteries are averaged, and unsupported/no-battery systems simply leave the module hidden.
Custom modules are operational in the interactive host and in one-shot shoal prompt print|explain. Because they execute with the UI host’s ambient filesystem/network authority, executable custom tables are accepted only from trusted system/user configuration; module.custom in a project .shoal.toml is removed with a warning before layers merge and cannot add or override a command merely by entering a repository.
command is split as quoted external argv; it is not evaluated by a shell, so redirects, pipelines, substitutions, environment assignments, and shell operators have no special meaning. It admits at most 64 arguments and 4 KiB of command text. when is empty for unconditional execution or one exact environment-variable name; the command runs only while that variable has a nonempty value. cache_ttl accepts a Shoal duration from zero through one hour. Two background workers run probes after command completion with a 250 ms process-group deadline and a 4 KiB combined-output wall. The first refresh is pending, a successful value is cached, and an expired value remains visible as stale while it refreshes. One-shot inspection waits at most 525 ms for the first bounded results. Nonzero, timed-out, truncated, non-UTF-8, multiline, or terminal-control-bearing output is hidden as an error. Rendering itself remains subprocess-free on every keystroke.
Unknown format module IDs and unknown prompt keys warn rather than preventing the shell from starting. Invalid prompt data falls back to defaults with a warning.
Module configuration map🔗
Each static table supports enabled plus module-specific keys:
| Table | Important keys |
|---|---|
module.character | success_symbol, error_symbol, vicmd_symbol, and their styles |
module.directory | truncate_to, truncate_style, repo_relative, read_only_symbol, symbol, style, home_symbol |
module.git_branch | symbol, ascii_symbol, style, truncate_to, truncate_symbol, format |
module.git_status | ahead, behind, diverged, staged, unstaged, untracked, conflicted, stashed, stale_symbol, style |
module.git_state | labels for rebase, merge, cherry_pick, bisect, revert, plus style |
module.cmd_duration | min_ms, style |
module.exit_status | show_on_success, format, style |
module.jobs | symbol, threshold, format, style; formats may use active ${total}, ${running}, ${suspended}, and bounded-history ${completed} |
module.time | format, style |
module.username | show_always, style, root_style |
module.hostname | show_always, symbol, style |
module.reef | format, show_when_empty, show_ambient, style |
module.principal | human_symbol, agent_symbol, show_agent_name, style, agent_style |
module.leash | style_by_tier, symbol_by_tier, hide_when_enforced |
module.battery | charging/discharging symbols, low_threshold, low_style, style, sample_interval_s |
Style strings accept color names and attributes such as bold and dim. A style can also name a palette entry (ok, error, warn, info, muted, or accent).
Prompt performance model🔗
Prompt rendering is snapshot-based. Shoal collects mutable facts once after a command completes and the renderer formats that immutable snapshot while the line editor redraws. A redraw therefore does not repeatedly inspect the filesystem or launch commands. In a Git repository, status collection runs at most one git status subprocess per completed command.
Inspect or benchmark the result without opening an interactive shell:
shoal prompt print --side left
shoal prompt explain --side right
shoal prompt bench --side left --n 1000If the prompt exceeds budget.render_deadline_ms, Shoal warns once per refreshed interactive snapshot when warn_on_exceed is enabled. The warning uses Reedline’s bounded, nonblocking notice queue; saturation is counted and reported by a later warning instead of delaying input. Static/Git/Reef snapshot work should stay cheap. Custom commands run on the bounded post-command scheduler and never inside the renderer; their 250 ms execution budget is separate from the pure render deadline.
Troubleshooting configuration🔗
- If a repository
.shoal.tomlseems ignored, check that it is the nearest ancestor project file; Shoal does not merge multiple ancestor.shoal.tomlfiles. - If rich prompt keys warn from
shoal.toml, move them to the root ofprompt.toml. - If a legacy
{cwd}template appears, migrate it toformat.left = "$directory...". - If output is unexpectedly silent in a script, set
render.echo = "all"temporarily; see CLI and execution modes. - If a configured adapter disappears, consolidate the complete catalog into the last
adapters.dirsentry. - If a schema-valid setting has no effect, check the runtime-note column above and Current status and limits.