Configuration Reference

🚀Configuration Reference

Reflow 1.0.2

Map the shipped Reflow configuration to the commands and boundaries that consume it.

Command.config/reflow/config.toml

📦Category

Configuration

🚀Quick Command

[tool.reflow.*]

---

TOMLcommand defaultsrepository targeting

---

Resolution and ownership

When a setting has a matching CLI option, Reflow resolves it in this order:

1. Explicit CLI argument
2. .config/reflow/config.toml
3. Internal default

The file created by reflow init belongs to the target project. Review it before committing it, and do not place credentials or tokens in repository URLs or image names.

⚠️Configure either path or URL—not both

Within [tool.reflow.repository], keep only one active target form. If both path and url are present, Reflow reports a configuration error. Omitting both falls back to the current working directory unless an explicit CLI target is supplied.

Repository and Git

📋Target settings

Property	Type	Description	Default	Required
repository.path	path	Existing local directory. Relative values resolve from the invocation directory.	.	No
repository.url	Git URL	Remote repository materialized in a managed temporary clone. Do not embed credentials.	unset	No
git.default_remote	string	Remote name used for remote tag replacement and release-recovery pushes.	origin	No

Command	path target	url target	Persistent scope
reflow init	Supported	Rejected	Project configuration files
reflow tags convert local	Supported	Rejected	Local tag refs only
reflow tags convert remote	Uses the checkout's remote	Uses a temporary clone	Guarded atomic remote push
reflow releases recover	Uses the checkout's remote	Uses a temporary clone	Delete and re-push selected remote tags
reflow dockerize	Uses the checkout as source	Uses a temporary clone as source	Docker and registry operations

Registry values such as github.image and gitlab.image never select the Git repository.

Shared CLI Execution

📋[tool.reflow.cli.execution]

Property	Type	Description	Default	Required
debug	boolean	Enable detailed diagnostic output when the CLI flag is omitted.	false	No
dry_run	boolean	Simulate persistent local, remote, Docker, and registry mutations while allowing discovery and validation.	false	No

📋[tool.reflow.cli.progress]

Property	Type	Description	Default	Required
enabled	boolean	Show Rich spinners and progress bars. This changes presentation, not live or dry-run behavior.	true	No

ℹ️Dry-run can still read and log

Read-only Git or provider discovery and temporary-clone setup may execute in a dry run. Diagnostic logging may also write to the configured log file; the workflow's persistent project, remote, Docker, and registry mutations remain simulated.

Initialization

📋[tool.reflow.initialization]

Property	Type	Description	Default	Required
force	boolean	Default overwrite behavior for reflow init when --force/--no-force is omitted.	false	No
ask	boolean	Prompt before supported creation or replacement decisions when --ask is omitted.	false	No

These settings are consumed only by reflow init. The active command accepts the all and config modes and requires a persistent local target.

Tag Conversion

📋[tool.reflow.cli.tags.convert]

Property	Type	Description	Default	Required
target_format	semver | pep440	Destination format shared by local and remote tag conversion when --to is omitted.	semver	No
yes	boolean	Bypass the live replacement confirmation after the full plan is displayed. Dry-run never prompts.	false	No

The same defaults feed reflow tags convert local and reflow tags convert remote; the selected subcommand still controls whether local or remote refs can change.

Release Recovery and the Deprecated Alias

📋[tool.reflow.cli.releases.recover]

Property	Type	Description	Default	Required
delay	integer >= 0	Seconds between selected remote tag re-push operations.	2	No
only_stable	boolean	Exclude prerelease tags when selecting releases to recover.	false	No
limit	integer >= 1 | unset	Maximum number of selected missing-release tags.	unlimited	No

--yes for reflow releases recover is intentionally CLI-only. Recovery checks GitHub releases, then deletes and re-pushes selected remote tags to retrigger tag-based CI/CD; it does not create release records through an API.

📋[tool.reflow.cli.tags.replay] (deprecated)

Property	Type	Description	Default	Required
delay	integer >= 0	Legacy fallback when the canonical recovery delay is not configured.	2	No
only_stable	boolean	Legacy fallback for the canonical stable-only filter.	false	No
limit	integer >= 1 | unset	Legacy fallback for the canonical recovery limit.	unlimited	No

Keep legacy values only while migrating existing configuration. New configuration and automation should use [tool.reflow.cli.releases.recover] and reflow releases recover.

Docker and Registry Images

📋Container publishing

Property	Type	Description	Default	Required
docker.provider	github | gitlab | both	Select which configured registry destinations reflow dockerize publishes to.	github	No
docker.keep_local_images	boolean	Keep all built tag images locally instead of removing non-latest images after push.	false	No
github.image	image name	GHCR destination, for example ghcr.io/acme/project. Required for github or both.	template placeholder	No
gitlab.image	image name	GitLab Container Registry destination. Required for gitlab or both.	template placeholder	No

reflow dockerize has no command-specific provider or image flags in Reflow 1.0.2; configure these values in TOML. Live mode builds and pushes one image per repository tag, tags the latest ordered tag as latest, and may remove non-latest local images.

Console and File Logging

📋[tool.reflow.logging]

Property	Type	Description	Default	Required
level	log level	Console logging threshold; --log-level overrides it.	INFO	No
markup	boolean	Enable Rich markup in console logging.	true	No
rich_tracebacks	boolean	Enable Rich traceback rendering.	true	No
show_time	boolean	Show timestamps in console log records.	false	No
show_level	boolean	Show severity labels in console log records.	false	No
console_format	format string	Python logging format used for console records.	%(message)s	No

📋[tool.reflow.logging.file]

Property	Type	Description	Default	Required
level	log level	File logging threshold.	DEBUG	No
log_dir	path	Directory for persistent logs.	logs	No
log_file	filename	Active log filename.	reflow.log	No
max_bytes	size	Rotate the log after this approximate size.	10MB	No
backup_count	integer	Number of rotated log files retained.	5	No
file_format	format string	Python logging format used for file records.	timestamp | level | logger | message	No

Never include credentials, tokens, or secret-bearing URLs in configuration or diagnostic output.

Minimal Target Examples

Local target

toml

[tool.reflow.repository]
path = "../project"

[tool.reflow.cli.tags.convert]
target_format = "semver"
yes = false

Remote URL target

toml

[tool.reflow.repository]
url = "https://github.com/acme/project.git"

[tool.reflow.git]
default_remote = "origin"

Do not combine the path and url examples in one active configuration.

ℹ️Use exact supported keys

Unknown or misspelled keys do not replace supported CLI options or defaults. Compare the generated file with the packaged Reflow 1.0.2 template when upgrading an existing project-owned configuration.

🚀Related Commands

Commands commonly used together with this command.

Configuration Overview

Understand precedence and project ownership.

Repository Targeting

Choose a path or URL safely.

Command Overview

Match configuration to command mutation scopes.