# Settings Reference

{/* This file is generated by `pnpm generate:config`. */}

This page is generated from Shuck's Rust configuration metadata and lists the supported `shuck.toml` and `.shuck.toml` settings.

Use [Configuration](/docs/configuration) for discovery, precedence, and examples of how config files are resolved.

## `[check]`

File-level analysis behavior for `shuck check`.

#### `embedded`

Lint supported embedded shell scripts in non-shell files, including GitHub Actions workflow `run` blocks and composite action steps.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[check]
embedded = false
```

---

## `[format]`

Formatter style options for `shuck format`.

#### `binary-next-line`

Place binary list and pipeline operators at the start of continuation lines when a command is split.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[format]
binary-next-line = true
```

---

#### `function-next-line`

Place function opening braces on the line after the function name.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[format]
function-next-line = true
```

---

#### `indent-style`

Indent with tabs or spaces. Supported values are `tab` and `space`.

**Default value**: `"tab"`

**Type**: `string`

**Example usage**:

```toml
[format]
indent-style = "space"
```

---

#### `indent-width`

Number of spaces to use for each indentation level when `indent-style = "space"`.

**Default value**: `8`

**Type**: `integer`

**Example usage**:

```toml
[format]
indent-width = 2
```

---

#### `keep-padding`

Preserve existing horizontal padding in source regions where the formatter can do so safely.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[format]
keep-padding = true
```

---

#### `never-split`

Prefer compact layouts and avoid optional line splitting.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[format]
never-split = true
```

---

#### `space-redirects`

Insert spaces between redirection operators and their targets where the shell grammar allows it.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[format]
space-redirects = true
```

---

#### `switch-case-indent`

Indent `case` branch bodies one level deeper than the branch pattern.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[format]
switch-case-indent = true
```

---

## `[lint]`

Rule selection, per-file ignores, fix eligibility, and rule-specific behavior for `shuck check`.

#### `extend-fixable`

Add rules to the set that can receive automatic fixes when `shuck check --fix` is enabled.

**Default value**: `[]`

**Type**: `list[selector]`

**Example usage**:

```toml
[lint]
extend-fixable = ["S074"]
```

---

#### `extend-per-file-ignores`

Add more per-file ignores without replacing the existing `per-file-ignores` table.

**Default value**: `{}`

**Type**: `table[str, list[selector]]`

**Example usage**:

```toml
[lint]
extend-per-file-ignores = { "vendor/**" = ["ALL"] }
```

---

#### `extend-select`

Enable additional rules or named selectors on top of the default or explicitly selected rule set.

**Default value**: `[]`

**Type**: `list[selector]`

**Example usage**:

```toml
[lint]
extend-select = ["google"]
```

---

#### `fixable`

Replace the set of rules that can receive automatic fixes when fixes are available.

**Default value**: `["ALL"]`

**Type**: `list[selector]`

**Example usage**:

```toml
[lint]
fixable = ["C", "S074"]
```

---

#### `ignore`

Remove rules from the active rule set.

**Default value**: `[]`

**Type**: `list[selector]`

**Example usage**:

```toml
[lint]
ignore = ["S074"]
```

---

#### `per-file-ignores`

Ignore selected rules for files that match a glob pattern.

**Default value**: `{}`

**Type**: `table[str, list[selector]]`

**Example usage**:

```toml
[lint]
per-file-ignores = { "scripts/*.sh" = ["S074"] }
```

---

#### `select`

Replace the default rule set with the selectors listed here, including named selectors such as `google`.

**Default value**: `all implemented non-style rules`

**Type**: `list[selector]`

**Example usage**:

```toml
[lint]
select = ["google"]
```

---

#### `unfixable`

Prevent selected rules from receiving automatic fixes, even when `--fix` is enabled.

**Default value**: `[]`

**Type**: `list[selector]`

**Example usage**:

```toml
[lint]
unfixable = ["C001"]
```

---

### `[lint.contracts]`

Ambient contract settings for runtime behavior that cannot be recovered from the source graph alone.

#### `well-known`

Enable or disable Shuck's built-in ambient contract registry.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.contracts]
well-known = false
```

---

#### `disabled`

Disable built-in ambient contracts by exact ID, by group selector, or with `*` for every built-in contract.

**Default value**: `[]`

**Type**: `list[string]`

**Example usage**:

```toml
[lint.contracts]
disabled = ["zsh/oh-my-zsh", "runtime/github-actions/env"]
```

---

### `[[lint.contracts.custom]]`

User-authored ambient contracts layered on top of, or in place of, the built-in registry.

#### `id`

Stable identifier for the custom contract.

**Default value**: `required`

**Type**: `string`

**Example usage**:

```toml
[[lint.contracts.custom]]
id = "github-actions-env"
```

---

#### `replaces`

Built-in contract selectors that this custom contract replaces.

**Default value**: `[]`

**Type**: `list[string]`

**Example usage**:

```toml
[[lint.contracts.custom]]
replaces = ["zsh/oh-my-zsh/plugin/tmux"]
```

---

#### `when`

Activation for the contract, either `"always"` or an object such as `{ type = "zsh_plugin", framework = "oh-my-zsh", plugin = "tmux" }`.

**Default value**: `required`

**Type**: `string | table`

**Example usage**:

```toml
[[lint.contracts.custom]]
when = { type = "zsh_plugin", framework = "oh-my-zsh", plugin = "tmux" }
```

---

#### `files`

Optional file globs that limit where the contract applies.

**Default value**: `[]`

**Type**: `list[glob]`

**Example usage**:

```toml
[[lint.contracts.custom]]
files = ["**/.zshrc"]
```

---

#### `reads`

Ambient names the activated runtime reads from the caller environment.

**Default value**: `[]`

**Type**: `list[name]`

**Example usage**:

```toml
[[lint.contracts.custom]]
reads = ["GITHUB_ENV", "GITHUB_OUTPUT"]
```

---

#### `functions`

Provided function contracts with caller reads and caller-visible sets.

**Default value**: `[]`

**Type**: `list[{ name, reads?, sets? }]`

**Example usage**:

```toml
[[lint.contracts.custom]]
functions = [{ name = "helper", reads = ["CALLER_VALUE"], sets = ["REPLY"] }]
```

---

### `[lint.contracts.custom.consumes]`

Assignments that stay live because external runtime behavior consumes them.

#### `names`

Exact names consumed by external runtime behavior.

**Default value**: `[]`

**Type**: `list[name]`

**Example usage**:

```toml
[[lint.contracts.custom]]
[lint.contracts.custom.consumes]
names = ["HISTFILE", "SAVEHIST"]
```

---

#### `prefixes`

Name prefixes consumed by external runtime behavior.

**Default value**: `[]`

**Type**: `list[prefix]`

**Example usage**:

```toml
[[lint.contracts.custom]]
[lint.contracts.custom.consumes]
prefixes = ["ZSH_TMUX_"]
```

---

#### `all`

Treat every assignment in the file as externally consumed.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[[lint.contracts.custom]]
[lint.contracts.custom.consumes]
all = true
```

---

### `[lint.contracts.custom.provides]`

Bindings made available by the activated runtime at file entry or activation time.

#### `variables`

Variables provided by the contract.

**Default value**: `[]`

**Type**: `list[name]`

**Example usage**:

```toml
[[lint.contracts.custom]]
[lint.contracts.custom.provides]
variables = ["reply", "REPLY"]
```

---

#### `functions`

Callable function names provided by the contract.

**Default value**: `[]`

**Type**: `list[name]`

**Example usage**:

```toml
[[lint.contracts.custom]]
[lint.contracts.custom.provides]
functions = ["helper"]
```

---

### `[lint.rule-options]`

Rule-specific behavior overrides for diagnostics that intentionally support more than one analysis mode.

### `[lint.rule-options.c001]`

Behavior overrides for `C001` unused assignment analysis.

#### `treat-indirect-expansion-targets-as-used`

Treat scalar indirect-expansion targets such as `${!name}` as a use of the referenced target.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.c001]
treat-indirect-expansion-targets-as-used = true
```

---

### `[lint.rule-options.c063]`

Behavior overrides for `C063` overwritten and unreached function analysis.

#### `report-unreached-nested-definitions`

Report nested function definitions when no reachable direct call reaches the enclosing function scope before it exits.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.c063]
report-unreached-nested-definitions = true
```

---

### `[lint.rule-options.s078]`

Behavior overrides for `S078` shebang shell policy.

#### `allowed-shells`

Interpreter names accepted in shebangs for this project.

**Default value**: `["bash"]`

**Type**: `list[string]`

**Example usage**:

```toml
[lint.rule-options.s078]
allowed-shells = ["bash", "zsh"]
```

---

### `[lint.rule-options.s079]`

Behavior overrides for `S079` shebang invocation form policy.

#### `allowed-forms`

Shebang invocation forms accepted for this project. Supported values are `absolute-path` and `env-lookup`.

**Default value**: `["env-lookup"]`

**Type**: `list[string]`

**Example usage**:

```toml
[lint.rule-options.s079]
allowed-forms = ["env-lookup"]
```

---

#### `allowed-paths`

Exact shebang invocation strings accepted regardless of invocation form.

**Default value**: `["/bin/bash", "/usr/bin/env bash"]`

**Type**: `list[string]`

**Example usage**:

```toml
[lint.rule-options.s079]
allowed-paths = ["/usr/bin/env bash"]
```

---

### `[lint.rule-options.s080]`

Behavior overrides for `S080` script size policy.

#### `max-lines`

Maximum accepted line count for one script.

**Default value**: `100`

**Type**: `integer`

**Example usage**:

```toml
[lint.rule-options.s080]
max-lines = 100
```

---

#### `count`

Line-counting mode. Supported values are `physical` and `non-comment-non-blank`.

**Default value**: `"physical"`

**Type**: `string`

**Example usage**:

```toml
[lint.rule-options.s080]
count = "non-comment-non-blank"
```

---

### `[lint.rule-options.s081]`

Behavior overrides for `S081` file description comments.

#### `ignore-shebang-only-files`

Do not report scripts whose only content is a shebang line.

**Default value**: `false`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.s081]
ignore-shebang-only-files = true
```

---

### `[lint.rule-options.s082]`

Behavior overrides for `S082` action comment formatting.

#### `kinds`

Comment markers checked at the start of a comment.

**Default value**: `["TODO", "FIXME", "XXX"]`

**Type**: `list[string]`

**Example usage**:

```toml
[lint.rule-options.s082]
kinds = ["TODO", "FIXME"]
```

---

#### `require-owner`

Require a checked marker to be followed immediately by a parenthesized owner.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.s082]
require-owner = false
```

---

#### `require-message`

Require a checked marker to include non-empty explanatory text.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.s082]
require-message = false
```

---

### `[lint.rule-options.s083]`

Behavior overrides for `S083` missing function documentation.

#### `require-for`

Choose which functions require a leading documentation comment: all, exported, long, or parameterized.

**Default value**: `long`

**Type**: `string`

**Example usage**:

```toml
[lint.rule-options.s083]
require-for = "exported"
```

---

#### `long-function-line-threshold`

Minimum body line count for `require-for = "long"`.

**Default value**: `10`

**Type**: `integer`

**Example usage**:

```toml
[lint.rule-options.s083]
long-function-line-threshold = 20
```

---

### `[lint.rule-options.s084]`

Behavior overrides for `S084` function documentation content.

#### `require-globals`

Require a Globals section when a documented function reads or writes non-local variables.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.s084]
require-globals = false
```

---

#### `require-arguments`

Require an Arguments section when a documented function uses positional parameters.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.s084]
require-arguments = false
```

---

#### `require-outputs`

Require an Outputs section when a documented function writes with echo or printf.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.s084]
require-outputs = false
```

---

#### `require-returns`

Require a Returns section when a documented function has an explicit return code.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.s084]
require-returns = false
```

---

### `[lint.rule-options.s085]`

Behavior overrides for `S085` missing main entrypoint analysis.

#### `non-trivial-line-threshold`

Minimum source line count before the script is checked.

**Default value**: `30`

**Type**: `int`

**Example usage**:

```toml
[lint.rule-options.s085]
non-trivial-line-threshold = 20
```

---

#### `non-trivial-function-count`

Minimum function definition count before the script is checked.

**Default value**: `2`

**Type**: `int`

**Example usage**:

```toml
[lint.rule-options.s085]
non-trivial-function-count = 3
```

---

#### `main-name`

Function name expected as the final top-level call in non-trivial scripts.

**Default value**: `"main"`

**Type**: `string`

**Example usage**:

```toml
[lint.rule-options.s085]
main-name = "run"
```

---

### `[lint.rule-options.c158]`

Behavior overrides for `C158` implicit global assignment analysis.

#### `treat-readonly-as-documented`

Treat top-level readonly declarations as documented intentional globals.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.c158]
treat-readonly-as-documented = false
```

---

#### `treat-export-as-intentional`

Treat top-level exported bindings as intentional globals.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.c158]
treat-export-as-intentional = false
```

---

### `[lint.rule-options.c159]`

Behavior overrides for `C159` mutable global analysis.

#### `allow-conditional-init`

Allow self-referential default initializers such as `name=${name:-value}` without treating them as global mutations.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.c159]
allow-conditional-init = false
```

---

### `[lint.rule-options.c160]`

Behavior overrides for `C160` unanchored source path analysis.

#### `allowed-anchors`

Path prefix expressions accepted as script-directory anchors for source or dot commands.

**Default value**: `["${BASH_SOURCE[0]%/*}", "$(dirname \"$0\")", "$(dirname \"${BASH_SOURCE[0]}\")"]`

**Type**: `list[string]`

**Example usage**:

```toml
[lint.rule-options.c160]
allowed-anchors = ["$SCRIPT_DIR"]
```

---

### `[lint.rule-options.c161]`

Behavior overrides for `C161` function call ordering analysis.

#### `ignore-after-source`

Ignore later calls after a source command because the sourced file may define functions.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.rule-options.c161]
ignore-after-source = false
```

---

### `[lint.zsh]`

Zsh-specific lint behavior for `shuck check`.

### `[lint.zsh.plugins]`

Zsh plugin-resolution settings used to import real plugin entrypoints into semantic analysis.

#### `resolution`

Enable or disable zsh plugin resolution while leaving ordinary source closure enabled.

**Default value**: `true`

**Type**: `bool`

**Example usage**:

```toml
[lint.zsh.plugins]
resolution = false
```

---

#### `roots`

Fallback framework roots keyed by logical framework name.

**Default value**: `{}`

**Type**: `table[str, path]`

**Example usage**:

```toml
[lint.zsh.plugins]
roots = { oh-my-zsh = "~/.oh-my-zsh" }
```

---

#### `plugin-loads`

Additional logical plugin loads to attach to matching files.

**Default value**: `[]`

**Type**: `list[{ pattern, framework, name }]`

**Example usage**:

```toml
[lint.zsh.plugins]
plugin-loads = [{ pattern = "**/.zshrc", framework = "oh-my-zsh", name = "git" }]
```

---

#### `theme-loads`

Additional logical theme loads to attach to matching files.

**Default value**: `[]`

**Type**: `list[{ pattern, framework, name }]`

**Example usage**:

```toml
[lint.zsh.plugins]
theme-loads = [{ pattern = "**/.zshrc", framework = "oh-my-zsh", name = "agnoster" }]
```

---

#### `entrypoints`

Raw plugin entrypoint paths to import for matching files.

**Default value**: `[]`

**Type**: `list[{ pattern, paths }]`

**Example usage**:

```toml
[lint.zsh.plugins]
entrypoints = [{ pattern = "**/.zshrc", paths = ["./vendor/prompt/prompt.plugin.zsh"] }]
```

---

## `[run]`

Interpreter defaults and managed shell version pins for `shuck run` and related commands.

#### `shell`

Default managed shell to use when a script does not declare its own shell.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run]
shell = "bash"
```

---

#### `shell-version`

Default version constraint to use when no script metadata or per-shell pin is more specific.

**Default value**: `"latest"`

**Type**: `string`

**Example usage**:

```toml
[run]
shell-version = "5.2"
```

---

### `[run.shells]`

Per-shell version pins applied after the shell has been resolved for the current script.

#### `bash`

Version constraint for Bash scripts.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run.shells]
bash = "5.2"
```

---

#### `gbash`

Version constraint for gbash scripts.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run.shells]
gbash = "0.0.32"
```

---

#### `bashkit`

Version constraint for Bashkit scripts.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run.shells]
bashkit = "0.2.1"
```

---

#### `zsh`

Version constraint for Zsh scripts.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run.shells]
zsh = "5.9"
```

---

#### `dash`

Version constraint for Dash scripts.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run.shells]
dash = "0.5.12"
```

---

#### `mksh`

Version constraint for mksh scripts.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run.shells]
mksh = "59c"
```

---

#### `busybox`

Version constraint for BusyBox scripts on Linux hosts.

**Default value**: `none`

**Type**: `string`

**Example usage**:

```toml
[run.shells]
busybox = "1.36.1"
```

---

