Skip to content

Built-in commands

A tool built with rtb_cli::Application::builder() inherits a command suite it did not write. rtb itself is such a tool, so the flags below are what rtb <command> --help prints, and equally what your tool prints once the matching feature is on.

The implementations live outside this repository, in the runtime-family module that carries rtb-cli, rtb-update, rtb-docs and rtb-mcp (https://cli.rust.phpboyscout.uk). Those crates version independently; the surface described here is the one rtb 0.9.0 pins — rtb-cli 0.9.0, rtb-update 0.9.0, rtb-docs 0.9.0 and rtb-mcp 0.9.0.

Which commands appear

Two switches decide, and both must allow it:

  1. A Cargo feature must compile the module in — see Cargo features.
  2. A runtime Feature must be enabled in the Features set the tool builds. Every built-in declares which one gates it.

rtb's own selection disables Init and enables Ai, leaving Version, Update, Docs, Mcp, Doctor, Credentials, Config and Telemetry on. That is why rtb init does not exist while rtb docs ask does.

version

Prints the tool name, version, and target triple; also commit and build date when the binary was stamped with them.

$ rtb version
rtb 0.9.0
  target: x86_64-linux

The version comes from version_info!() at the tool's call site, not from the framework — a tool that uses VersionInfo::from_env() instead reports the framework's version, and update will then refuse to swap the binary because its self-test compares the reported version against the release tag.

doctor

Runs every registered health check and prints a report. Exits 1 if any check fails.

Checks are registered by the tool; a tool that registers none — rtb included — prints nothing and exits 0. Empty output means "no checks were registered", not "everything passed".

update

Subcommand Purpose
update check Report whether a newer version exists. No download.
update run Download, verify and swap the binary.

update run flags:

Flag Default Notes
--target <VERSION> latest Pin a specific version. Semver, no v prefix. A downgrade also needs --force.
--force off Re-install even when already current; also bypasses the downgrade check. Use it to repair a corrupted binary.
--include-prereleases off Let a prerelease count as "latest".
--dry-run off Download, verify and stage, but do not swap. Prints the staged binary's path.
--progress off Emit progress events to stderr.

docs

Subcommand Flags Purpose
docs list --root <ROOT> (default docs) List every page in the embedded doc tree.
docs show <PATH> --format <plain\|html> (default plain), --root Render one page to stdout.
docs browse — Interactive TUI browser; q quits.
docs serve --bind <BIND> (default 127.0.0.1:0), --root Serve the doc tree over loopback HTTP. Ctrl+C stops it.
docs ask <QUESTION>… — Put a question to the configured AI provider. Requires the ai Cargo feature on rtb-docs.

The default bind address ends in :0, so the port is chosen by the OS and printed at startup — there is no fixed default port. --bind is the only way to pin one.

mcp

Subcommand Flags Purpose
mcp serve --transport <stdio\|sse\|http> (default stdio), --bind <ADDR> Run the MCP server.
mcp list — Print every MCP-exposed command with its JSON Schema.

--bind is required whenever the transport is not stdio.

mcp list prints only commands that opt in. rtb's scaffolder verbs do not, so rtb mcp list produces no output — again, empty means "none exposed", not "failed".

config

Subcommand Flags Purpose
config show — Print the resolved configuration. The default subcommand.
config get <PATH> — Read a JSON-pointer path from the user config file. The leading / is optional.
config set <PATH> <VALUE> --config-file <PATH> Write a value. VALUE is parsed as JSON and falls back to a string.
config schema — Print the JSON Schema of the tool's typed config.
config validate --config-file <PATH> Validate a candidate file, or the merged result when no file is given.

A tool that never called .config(C) has no typed configuration, and config show says so rather than printing an empty document:

$ rtb config show
# no typed configuration is installed on this App
# (call `Application::builder().config(C)` to wire it)

credentials

Subcommand Purpose
credentials list Every declared credential and how the resolver currently sees it.
credentials add <NAME> Interactive wizard to store or overwrite one.
credentials remove <NAME> Delete a keychain-stored credential.
credentials test <NAME> Probe one credential and print which source answered.
credentials doctor test across every declared credential.

list, test and doctor are the commands that honour the global --output json flag. NAME is the name registered through the tool's CredentialBearing implementation, so a tool that declares none — rtb — lists an empty table.

telemetry

Subcommand Purpose
telemetry status State, where the decision came from, when it was made, and the consent-file path.
telemetry enable Opt in. Refused when CI=true.
telemetry disable Opt out.
telemetry reset Delete the consent file. Idempotent.

Telemetry is off until a consent decision exists; status reports state unset and policy Disabled until then.

init

Runs each registered initialiser that reports itself unconfigured, and prints no initialisers registered — nothing to do when there are none. Gated on the Init runtime feature, which rtb disables — so rtb init is not a command, though it is one in a tool that leaves Init on.