Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:
Environment variables in cargo-cooldown serve as the highest priority layer in the configuration stack. They allow developers and CI/CD systems to override settings defined in global, workspace, or member-specific cooldown.toml files without modifying the source code or persistent configuration files.
The system uses these variables to control core logic such as the length of the cooldown period, enforcement strictness, registry skipping, and terminal output behavior. Sources: src/config.rs:114-118, README.md:65-71
Configuration Hierarchy and Precedence
The application follows a specific merge precedence when loading its runtime configuration. Environment variables are applied last, meaning they override all other sources.
The diagram above illustrates the order in which configuration is layered, with the bottom layer (Environment Variables) taking the highest precedence. Sources: src/config.rs:88-97, README.md:73-78
Core Functional Variables
These variables directly influence the cooldown resolution logic and how the tool interacts with Cargo's dependency graph.
| Variable | Type | Description |
|---|---|---|
COOLDOWN_MINUTES | u64 | The age requirement (in minutes) for a crate version to be accepted. Sources: src/config.rs:153-155, README.md:66 |
COOLDOWN_ENFORCEMENT | String | Determines behavior when fresh versions cannot be cooled. Options: strict, cargo_compatible, off. Sources: src/config.rs:24-34, src/config.rs:156-158 |
COOLDOWN_LOCKFILE_BASELINE | String | Controls if the initial Cargo.lock is a version floor. Options: floor, ignore. Sources: src/config.rs:60-70, src/config.rs:162-164 |
COOLDOWN_SKIP_REGISTRIES | CSV | Comma-separated list of registry names or URLs to ignore. Sources: src/config.rs:175-177, README.md:121-125 |
Enforcement Modes
The COOLDOWN_ENFORCEMENT variable accepts three specific values that change the executor's exit strategy:
- strict: Fails the command and restores the original lockfile if any fresh versions remain.
- cargo_compatible: Allows the command to proceed with fresh versions if they are strictly required by Cargo's resolver, but issues a warning.
- off: Bypasses all cooldown checks.
Sources: src/config.rs:24-34, src/executor.rs:200-213
Integration and Tooling Variables
These variables manage how cargo-cooldown integrates with the environment, handles networking, and communicates with the user.
Terminal and UI Control
cargo-cooldown respects standard Cargo environment variables to manage terminal output.
CARGO_TERM_COLOR: Controls ANSI color output. Values:always,never,auto. Sources: src/ui.rs:149-155CARGO_TERM_PROGRESS_WHEN: Controls the display of progress bars. Valueneverdisables the spinner and bar. Sources: src/ui.rs:163-166NO_COLOR: If set, disables all colored output regardless of other settings. Sources: src/ui.rs:145-147COOLDOWN_VERBOSE: Set totrueor1to enable detailed debug logging. This also disables the progress spinner to prevent log corruption. Sources: src/config.rs:172-174, src/ui.rs:72-75
Networking and Caching
COOLDOWN_HTTP_RETRIES: Number of times to retry registry API requests (0 to 8). Sources: src/config.rs:169-171, src/config.rs:228-234COOLDOWN_CACHE_DIR: Path to the directory where registry metadata is cached. Sources: src/config.rs:165-168COOLDOWN_TTL_SECONDS: Time-to-live for cached registry metadata. Sources: src/config.rs:160-162
Internal and Testing Overrides
Several variables are primarily used for testing or specific edge-case manual overrides.
COOLDOWN_NOW: Overrides the current system time. Expects an RFC 3339 formatted string (e.g.,2026-04-03T00:00:00Z). This is extensively used in integration tests to ensure deterministic results. Sources: src/config.rs:159-161, tests/integration.rs:146-148COOLDOWN_CARGO_COMPATIBLE_ACCEPT: Sets the policy for accepting fresh versions incargo_compatiblemode.prompt(default) asks the user;autoaccepts them automatically. Sources: src/config.rs:44-54, src/config.rs:159-161
Data Flow for Environment Loading
The MergedConfig::apply_env function is responsible for pulling these values into the runtime configuration structure.
This diagram demonstrates the internal process where the application queries the OS environment and parses strings into strongly-typed internal structures. Sources: src/config.rs:152-179
Summary
Environment variables provide the ultimate control layer for cargo-cooldown, enabling seamless integration into automated environments like CI/CD pipelines while allowing developers to quickly toggle enforcement or timing policies. By adhering to the COOLDOWN_ prefix and supporting standard CARGO_ terminal variables, the tool maintains consistency with the Rust ecosystem's configuration patterns.