Configuration Resolution

🚀Configuration Resolution

Essential

Understand which value Custy uses when the CLI, project configuration, and application defaults overlap.

CommandCLI → config.toml → default

📦Category

Core Concepts

🚀Quick Command

custy [GLOBAL OPTIONS] COMMAND [OPTIONS]

---

configuration priorityproject defaultsCLI overrides

---

💻

Highest Priority

Explicit CLI value

⚙️

Project File

.config/custy/config.toml

📄

Root Table

[tool.custy]

📦

Load Scope

Once per process

Overview

Custy resolves configurable values in a predictable order. An explicit CLI value wins, the project configuration supplies a reusable value when the CLI does not, and a built-in default is used when neither source provides one.

💡Use configuration for repeatability

Keep stable project choices in .config/custy/config.toml. Use CLI options for intentional one-run overrides that should not change the project's normal behavior.

---

Resolution Priority

📋Properties

Property	Type	Description	Default	Required
1. Explicit CLI value	Highest priority	A value supplied for the current invocation overrides the corresponding project setting.	-	No
2. Project configuration	.config/custy/config.toml	The value under [tool.custy] is used when the matching CLI value is unspecified.	-	No
3. Built-in default	Fallback	The command's default is used when neither the CLI nor configuration supplies a value.	-	No

---

How Resolution Works

🕒Value Selection

1

Read the CLI value

Use an explicit value immediately when the command supplied one.

current

2

Read project configuration

When the CLI value is unspecified, look up the corresponding path under [tool.custy].

pending

3

Apply the built-in default

Use the command's fallback when the configuration path is also absent.

pending

4

Validate the result

A required value that remains unresolved raises a configuration error.

pending

---

Configuration File Shape

Custy extracts its settings from the [tool.custy] table. Nested configuration paths become nested TOML tables.

.config/custy/config.toml

toml

[tool.custy.cli.execution]
dry_run = true

[tool.custy.logging]
level = "INFO"

With this configuration, supported commands inherit dry-run behavior and the INFO log level when the current invocation does not explicitly override those values.

---

⚠️Not every option uses all three sources

Resolution is defined by each command's resolver. Some inputs are CLI-only, some configuration values use a built-in fallback, and required values may fail instead of receiving a default. Read the affected command's configuration and options pages before relying on a fallback.

---

Missing and Invalid Configuration

• A missing configuration file is treated as an empty project configuration; commands can continue when their remaining values have defaults.
• Invalid TOML or an invalid value is an error and should be corrected rather than silently ignored.
• The configuration object is cached for the lifetime of the Custy process. A new CLI invocation reads the file again.
• An unspecified option normally falls through to configuration. An explicit Boolean choice can remain an intentional CLI override.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Init Configuration

Generate and understand project-specific Custy resources.

All Configuration Properties

Find every full TOML path, default, and implementation status.

Run Options

Review public pipeline option behavior.

Changelog Configuration

Configure generated changelog content and paths.

Version Configuration

Configure strategy and version synchronization behavior.