On this page ↓

Operate Shoal

Configuration and prompt

Layer Shoal configuration safely, tune history and rendering, and build a fast structured prompt.

Status
Current implementation, with wiring gaps called out
For
Interactive users and administrators
On this page
  1. Main configuration precedence
  2. A practical user configuration
  3. Validation and diagnostics
    1. Unknown keys are warnings
    2. Type mismatches are hard errors
    3. Malformed TOML is a hard error
    4. Semantic constraints
  4. Main configuration reference
    1. Adapter-directory precedence
  5. Environment overrides
  6. Rich prompt configuration
    1. Prompt precedence
  7. Format placeholders
  8. Module configuration map
  9. Prompt performance model
  10. Troubleshooting configuration

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:

  1. /etc/shoal/shoal.toml
  2. $XDG_CONFIG_HOME/shoal/shoal.toml, or ~/.config/shoal/shoal.toml
  3. the nearest .shoal.toml found by walking from the current directory toward the filesystem root
  4. 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"]
    end

A 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 string

Array 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:

KeyRequirement
versionexactly 1
history.max_entriesgreater than zero
editor.modeemacs or vi
render.pagingnever or auto
render.echoquiet, commands, or all when present
completion.max_resultsgreater than zero
alias namesnonempty and contain no whitespace
environment namesnonempty
every history.ignore patternnonempty

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 whitespace

The 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.

KeyType and defaultRuntime note
versioninteger, 1Configuration format version.
prompt.templatestring, "{cwd}"Legacy prompt form; prefer prompt.toml.
history.enabledboolean, trueInteractive history only.
history.max_entriesinteger, 10000Caps retained file entries.
history.pathpath, platform defaultExplicit history file.
history.dedupboolean, trueSkips a line identical to the immediately previous entry.
history.ignorestring list, emptyWhole-line shell-style */? patterns excluded from history.
history.ignore_spaceboolean, trueA line beginning with a space is not recorded.
render.colorboolean, trueNO_COLOR can disable it.
render.widthpositive integer or absentOverrides 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.pagercommand string or absentFalls back to $PAGER, then less -R.
render.echo"quiet", "commands", "all", or absentSurface default: all in the REPL, quiet for scripts and -c.
editor.mode"emacs" or "vi", "emacs"Selects the interactive editing mode.
editor.bracketed_pasteboolean, trueControls paste handling.
editor.keybindingschord-to-action table, emptyExtends or replaces actions for named chords.
completion.fuzzyboolean, trueAllows non-prefix matching.
completion.case_insensitiveboolean, trueApplies to candidate matching.
completion.max_resultsinteger, 100Bounds the candidate set.
completion.menuboolean, truefalse enables quick/shared-prefix completion, but a popup can still appear when ambiguous candidates have no common prefix.
adapters.dirspath list, emptyAdds adapter catalogs; see the caveat below.
init.filespath list, emptyInteractive startup scripts, in order.
aliasesstring table, emptyPersistent session aliases.
envstring table, emptyInitial session environment.
reef.toolsconstraint table, emptyUser-scope Reef constraints.
reef.runnersrunner table, emptyUser-scope script runners.
reef.options.hermeticboolean, falseRemoves the ambient PATH tail when engaged.
kernel.enabledboolean, trueThe default interactive REPL runs through an isolated private shoal-kernel child. Set false (or pass --standalone) for the local evaluator path.
kernel.sessionstring, "default"Names the principal-private Session inside the default REPL’s private kernel. It does not attach to a durable public kernel socket.
journal.enabledboolean, trueEnables language-facing history/journal/undo; it never disables mandatory kernel security/approval/event audit.
journal.state_dirpath or absentLocal language journal/jump and embedded-kernel state root; relative paths resolve from startup cwd.
leash.policypath or absentLoaded 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 variableConfiguration target
NO_COLORdisables render.color
SHOAL_PROMPT_TEMPLATEprompt.template
SHOAL_PROMPTlegacy prompt.template; also a deprecated rich-prompt left-format alias
SHOAL_HISTORY_ENABLED / SHOAL_HISTORYhistory.enabled
SHOAL_HISTORY_MAX_ENTRIEShistory.max_entries
SHOAL_HISTORY_FILEhistory.path
SHOAL_HISTORY_DEDUPhistory.dedup
SHOAL_RENDER_COLORrender.color
SHOAL_RENDER_WIDTHrender.width
SHOAL_RENDER_PAGINGrender.paging
SHOAL_RENDER_PAGERrender.pager
SHOAL_RENDER_ECHOrender.echo
SHOAL_EDITOR_MODEeditor.mode
SHOAL_EDITOR_BRACKETED_PASTEeditor.bracketed_paste
SHOAL_KERNEL_ENABLED / SHOAL_KERNELkernel.enabled
SHOAL_KERNEL_SESSIONkernel.session
SHOAL_JOURNAL_ENABLEDjournal.enabled
SHOAL_LEASH_POLICYleash.policy
SHOAL_COMPLETION_FUZZYcompletion.fuzzy
SHOAL_COMPLETION_CASE_INSENSITIVEcompletion.case_insensitive
SHOAL_COMPLETION_MAX_RESULTScompletion.max_results
SHOAL_COMPLETION_MENUcompletion.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.toml

Its 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:

  1. the named built-in theme
  2. /etc/shoal/shoal.toml’s [prompt] table
  3. the user shoal.toml’s [prompt] table
  4. the user prompt.toml root
  5. the nearest ancestor .shoal.toml’s [prompt] table
  6. 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:

TableImportant keys
module.charactersuccess_symbol, error_symbol, vicmd_symbol, and their styles
module.directorytruncate_to, truncate_style, repo_relative, read_only_symbol, symbol, style, home_symbol
module.git_branchsymbol, ascii_symbol, style, truncate_to, truncate_symbol, format
module.git_statusahead, behind, diverged, staged, unstaged, untracked, conflicted, stashed, stale_symbol, style
module.git_statelabels for rebase, merge, cherry_pick, bisect, revert, plus style
module.cmd_durationmin_ms, style
module.exit_statusshow_on_success, format, style
module.jobssymbol, threshold, format, style; formats may use active ${total}, ${running}, ${suspended}, and bounded-history ${completed}
module.timeformat, style
module.usernameshow_always, style, root_style
module.hostnameshow_always, symbol, style
module.reefformat, show_when_empty, show_ambient, style
module.principalhuman_symbol, agent_symbol, show_agent_name, style, agent_style
module.leashstyle_by_tier, symbol_by_tier, hide_when_enforced
module.batterycharging/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 1000

If 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.toml seems ignored, check that it is the nearest ancestor project file; Shoal does not merge multiple ancestor .shoal.toml files.
  • If rich prompt keys warn from shoal.toml, move them to the root of prompt.toml.
  • If a legacy {cwd} template appears, migrate it to format.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.dirs entry.
  • If a schema-valid setting has no effect, check the runtime-note column above and Current status and limits.
Type to search every guide↑↓ navigate ↵ open esc close
Diagram