Configuration

PySH v1 uses layered declarative and programmable configuration with deterministic load order.

Configuration model

PySH supports five user startup layers. Declarative TOML is the primary safe configuration format, while~/.pyshrc.py is the advanced trusted Python layer.

✓${XDG_CONFIG_HOME}/pysh/config.toml or ~/.config/pysh/config.toml — primary declarative TOML
✓~/.config/pysh/conf.d/*.toml — deterministic lexical TOML drop-ins
✓~/.pyshrc — legacy PySH shell-syntax startup file
✓~/.pyshrc.d/*.pysh — legacy shell-syntax drop-ins
✓~/.pyshrc.py — trusted Python-native configuration through ShellConfigAPI

Load order

✓Built-in defaults
✓~/.pyshrc
✓~/.pyshrc.d/*.pysh in lexical order
✓Primary config.toml
✓conf.d/*.toml in lexical order
✓~/.pyshrc.py
✓Python configuration startup hooks
✓Plugin API startup hooks after plugin discovery

Safe startup and recovery

Strict no-user-configuration startup

$ pysh --no-rc

$ python -m pysh --no-rc

$ pysh --no-rc -c "echo recovery-ok"

Info: --no-rc skips executable rc files, declarative user and plugin TOML, plugin discovery/import, and user/plugin startup hooks. It uses built-in defaults and does not create configuration files.

Declarative TOML

The primary file is ~/.config/pysh/config.toml when XDG_CONFIG_HOME is unset. TOML is data only: it does not execute commands, evaluate shell or Python expressions, load plugins, or run hooks.

~/.config/pysh/config.toml

[profile]

active = "developer"

[theme]

active = "default"

[prompt]

prompt_layout = "two_line"

show_git_branch = true

show_python_version = true

show_last_status = true

[editor]

line_editor = "auto"

autosuggest = true

syntax_highlight = true

[history]

max_length = 10000

dedup_mode = "consecutive"

ignore_space_prefix = true

[alias_packs]

enabled = ["git", "python", "files"]

Prompt, profiles, and themes

Profiles define behavior and prompt layout; themes define visual style. They are independent and can be combined. Built-in profiles include default, minimal, developer,server, presentation, and plain.

Prompt and color settings

[prompt]

prompt_layout = "two_line"

show_user = true

show_host = true

show_cwd = true

show_git_branch = true

show_last_status = true

[colors.prompt]

cwd = "yellow"

git = "green"

symbol = "white"

History

History behavior is configured declaratively with max_length, dedup_mode, and related options. Interactive Ctrl+R reverse search uses the loaded history database.

Advanced ~/.pyshrc.py

~/.pyshrc.py is trusted user Python. It may override TOML-applied settings and register startup hooks through ShellConfigAPI.

~/.pyshrc.py

def configure(shell):

shell.alias("ll", "ls -la --color=auto -F")

shell.env("EDITOR", "nano")

shell.set_prompt_option("show_git_branch", True)

shell.set_prompt_color("cwd", "yellow")

shell.set_editor_option("syntax_highlight", True)

Plugin configuration files

Optional plugin-specific TOML lives under ~/.config/pysh/plugins/<plugin-name>.toml. These files configure plugins but do not load or enable plugin code by themselves.

Warning: Trusted plugins and ~/.pyshrc.pyexecute with the user's authority. Only enable code you trust.