Automatic update checks¶

Separate from the update subcommand, rtb-update registers a pre-run hook that can check for a newer release at the start of every invocation. It is off by default; this page documents what turning it on does.

The hook is registered into rtb_app::command::BUILTIN_PRERUN_HOOKS and awaited by Application::run_with_args after clap parsing and before the matched command runs. A hook returning an error aborts the run.

The three policy values¶

Set through ToolMetadata::update_policy, a build-time value chosen by the tool author.

Value	Behaviour on a newer release	Default
`UpdatePolicy::Disabled`	Nothing. The hook returns before any I/O	✔
`UpdatePolicy::Prompt`	Prints a two-line notice to stderr and continues
`UpdatePolicy::Enabled`	Runs the full update before the command, printing a notice first

The Prompt notice:

mytool: a newer version is available: 0.4.1 -> 0.5.0
  run `mytool update run` to install

Enabled prints mytool: updating 0.4.1 -> 0.5.0 before running… and then runs Updater::run(RunOptions::default()) — no dry run, no force, and progress silenced.

When the hook does nothing at all¶

The check is skipped, with no network access, if any of these hold:

update_policy is Disabled.
ToolMetadata::release_source is None.
A check ran within update_check_interval (see the throttle below).
The invocation was --help or -h, because clap short-circuits before hooks run.

Runtime Features are not consulted. App does not carry the active feature set, so disabling Feature::Update hides the update subcommand but does not disable the automatic check. The Disabled default is what keeps the hook inert for tools that have not opted in.

The throttle¶

ToolMetadata::update_check_interval is the minimum gap between automatic checks. It defaults to 24 hours.

State lives in <config_dir>/update.toml — see environment and files. The timestamp is recorded whenever a check actually runs, including when the check finds nothing new, so a failed lookup does not cause a retry storm.

A clock that has moved backwards makes the check due immediately rather than locking it out until the clock catches up.

What happens when the check fails¶

Failure handling differs by policy, and the difference is the point of having two values:

Policy	Provider cannot be built	Check itself fails
`Prompt`	Logged at debug, run continues	Logged at debug, run continues
`Enabled`	The command fails	The command fails

Prompt is advisory: a network outage must not stop the user's command. Enabled promised an up-to-date binary before running, so it cannot quietly proceed with an old one.

Under Enabled, any update failure — a bad signature, a self-test failure, a swap error — also fails the invocation the user actually asked for.

Turning it off¶

There is no environment variable, config key or flag. The policy is compiled in via ToolMetadata::update_policy, and a user cannot override it.

The nearest thing to an off switch a user has is deleting the release source, which they cannot do either. If you are shipping a tool, treat Enabled as a decision you are making on every user's behalf on every invocation, and prefer Prompt.