Skip to content

Environment variables and on-disk files

Complete list for the four crates in this repo. A tool built on them may read more of its own; these are the ones the framework itself touches.

Environment variables

Variable Read by Effect When unset
RUST_LOG rtb-cli tracing setup Standard tracing_subscriber::EnvFilter directive string Filter defaults to info
CI telemetry enable Exactly true refuses the opt-in Opt-in allowed
<TOOLNAME>_TELEMETRY telemetry status and the consent chain 1/true/on enable, 0/false/off disable Falls through to the default (disabled)
ANTHROPIC_API_KEY docs ask with the ai feature The API key for the hard-coded Anthropic provider docs ask fails, naming the variable
XDG_CONFIG_HOME, XDG_CACHE_HOME, HOME directories Locate the config and cache directories Platform defaults; an unresolvable home makes path-using commands fail

RUST_LOG is parsed once per process. An unparseable value is not an error — the filter silently falls back to info.

<TOOLNAME> is ToolMetadata::name upper-cased with no other transformation, so a hyphenated tool name produces a variable name most shells cannot export. See telemetry.

There is no environment variable for the output format

--output is a flag only. Nothing reads an environment variable to set the default rendering mode.

There is no --log-format flag

The log format is chosen automatically: LogFormat::auto() picks Pretty when stderr is a terminal and Json when it is not. Some API documentation mentions a --log-format flag and a log.format config key; neither exists in this release. Redirect stderr to a file or a pipe to get JSON logs.

Files this family writes

All paths derive from directories::ProjectDirs. Three of the four use the qualifier dev with an empty organisation; the update cache uses an empty qualifier, which changes the macOS path.

config.yaml — user configuration

Platform Path
Linux $XDG_CONFIG_HOME/<tool>/config.yaml, else ~/.config/<tool>/config.yaml
macOS ~/Library/Application Support/dev.<tool>/config.yaml
Windows %APPDATA%\<tool>\config\config.yaml

Written by config set. Read by config get, config validate and config show in the untyped path. Created on first write, parent directories included. See config.

Same directory as config.yaml. Written by telemetry enable and telemetry disable; deleted by telemetry reset. See telemetry.

update.toml — automatic update-check throttle

Same directory again. Written by the pre-run update policy hook to record when the last automatic check ran and the newest version it saw.

The file is read fail-open: missing, unreadable or malformed all mean "never checked", so a corrupt file causes an extra check rather than an error. Writes are best-effort — a failure is logged at debug level and swallowed, because throttling is an optimisation, not a correctness gate. See self-update policy.

<cache>/update/<tag>/ — staged update artefacts

Platform Path
Linux $XDG_CACHE_HOME/<tool>/update/<tag>/, else ~/.cache/<tool>/update/<tag>/
macOS ~/Library/Caches/<tool>/update/<tag>/
Windows %LOCALAPPDATA%\<tool>\cache\update\<tag>\

Holds the downloaded archive and, under bin/, the extracted binary. If no cache directory can be resolved, the system temp directory is used instead.

Nothing prunes this. Each update leaves an archive and an extracted binary behind under its own tag directory; clearing them is a manual job.

What this family never writes

  • No files in the current working directory. No .mytool.yaml, no lockfile, no dotfile beside the project.
  • No data or state directory. ProjectDirs::data_dir and state_dir are not used.
  • No log files. Tracing output goes to stderr and nowhere else. Persisting logs is the operator's job, through shell redirection or a supervisor.
  • Nothing into your shell's environment. credentials add prints an export line for you to run; it cannot set a variable in the calling shell.