Rust Tool Base (RTB)

A batteries-included application framework for building Rust CLI tools — idiomatic, composable, and AI-ready.

Status: pre-1.0. The crates are implemented and published, but the public API is not frozen — expect breaking changes within 0.x. The authoritative contract for each subsystem lives in 0008-rust-tool-base.

RTB is a Rust sibling of Go Tool Base (GTB). It is not a line-for-line port. Go Tool Base leans on Go's idioms (context.Context, functional options, package-level init(), interface{}-keyed containers); RTB leans on Rust's (? + miette, typestate builders, linkme distributed slices, strongly-typed serde config, tokio structured concurrency).

What RTB gives you

• Opinionated application scaffolding — Application::builder() typestate assembler that wires clap, figment, tracing, miette, tokio, and a signal- bound CancellationToken in one call.
• Strongly-typed layered config — env > CLI flags > user file > embedded defaults, materialised into your serde::Deserialize struct. Hot-reload via notify + arc-swap with a watch::Receiver for observers.
• Embedded-assets + overlay FS — rust-embed for compile-time bundling (with dev-mode disk passthrough) + vfs::OverlayFS for user-override layering. Structured formats (YAML/JSON/TOML) are deep-merged; binaries follow last-registered-wins.
• Diagnostic errors, not error handlers — every crate derives thiserror::Error + miette::Diagnostic; main() returns miette::Result<()> and a framework-installed hook renders them with labels, help, and severity.
• Self-update — self-replace + minisign-signed releases (prehashed ED — ed25519(BLAKE2b-512(archive))), verified with minisign-verify, the same crate cargo-binstall uses, so one signature serves both. The staged binary is self-tested before an atomic swap.
• VCS — gix-first Git ops (fallback to git2 for unsupported writes), octocrab for GitHub (Enterprise-capable, GitHub-App-capable), gitlab for self-hosted GitLab with nested groups.
• AI — genai for multi-provider (Claude, OpenAI, Gemini, Ollama), with a direct-reqwest path for Anthropic-only features (prompt caching, managed agents, extended thinking). Structured output validated with jsonschema.
• MCP — official rmcp SDK; commands opt in via Command::mcp_exposed = true and surface their clap::Args schema through Command::mcp_input_schema. mcp serve (stdio default) and mcp list ship as built-in subcommands.
• TUI docs browser — ratatui + termimad, with streaming AI Q&A.
• Credentials — keyring wrapped in a CredentialStore trait; secrecy::SecretString end-to-end, zeroed on drop.
• Telemetry — opt-in, salted machine-uid, pluggable sinks (noop/file/HTTP/OTLP).

Workspace layout

Only the umbrella crate and the rtb binary live here. Every other crate is a standalone module of the phpboyscout Rust toolkit, consumed here as an ordinary dependency:

• Foundations — rtb-error, rtb-redact, rtb-config, rtb-assets, rtb-app, rtb-tui, rtb-credentials, rtb-telemetry, rtb-test-support, rtb-chat (formerly rtb-ai), rtb-forge (formerly rtb-vcs).
• CLI family — rtb-cli, rtb-update, rtb-docs, rtb-mcp, in phpboyscout/rust/cli.

rust-tool-base/
├── Cargo.toml                      # workspace root
├── crates/
│   ├── rtb/                        # umbrella crate (public API)
│   └── rtb-cli-bin/                # the `rtb` scaffolder binary
├── examples/
│   └── minimal/                    # smoke-test tool
├── docs/                           # user-facing documentation
│                                   # (specs live in the project wiki)
├── .gitlab-ci.yml                  # CI + the tagged `dist` release stage
├── deny.toml                       # cargo-deny policy
├── rustfmt.toml
├── rust-toolchain.toml             # pinned stable
├── justfile                        # common tasks
├── LICENSE                         # MIT
└── SECURITY.md

Quick start

A working end-to-end example lives at examples/minimal. Run it with:

$ cargo run -p rtb-example-minimal -- version
$ cargo run -p rtb-example-minimal -- greet
$ cargo run -p rtb-example-minimal -- doctor
$ cargo run -p rtb-example-minimal -- --help

Anatomy

A minimal RTB-based tool has three parts: (1) a custom Command implementation, (2) a linkme registration that inserts it into the framework's command slice, and (3) an Application::builder() call in main.

use async_trait::async_trait;
use linkme::distributed_slice;
use rtb::core::app::App;
use rtb::core::command::{BUILTIN_COMMANDS, Command, CommandSpec};
use rtb::prelude::*;

// 1. Implement the Command trait.
struct Greet;

#[async_trait]
impl Command for Greet {
    fn spec(&self) -> &CommandSpec {
        static SPEC: CommandSpec = CommandSpec {
            name: "greet",
            about: "Print a friendly greeting",
            aliases: &["hi"],
            feature: None,
        };
        &SPEC
    }

    async fn run(&self, app: App) -> miette::Result<()> {
        println!("hello from {}", app.metadata.name);
        Ok(())
    }
}

// 2. Register into the framework's command slice at link time.
#[distributed_slice(BUILTIN_COMMANDS)]
fn register_greet() -> Box<dyn Command> { Box::new(Greet) }

// 3. Wire the Application.
#[tokio::main]
async fn main() -> miette::Result<()> {
    rtb::cli::Application::builder()
        .metadata(
            ToolMetadata::builder()
                .name("mytool")
                .summary("my CLI tool")
                .build(),
        )
        .version(version_info!())
        .build()?
        .run()
        .await
}

version_info!() has to be a macro: it expands env!("CARGO_PKG_VERSION") at your call site, so it reports your tool's version. A function couldn't — its env! would expand inside the framework and report the framework's version instead.

Downstream tools need rtb, tokio, miette, async-trait, and linkme as direct dependencies. linkme must be direct because its #[distributed_slice] attribute expands to ::linkme::… paths.

Development

just ci           # fmt + clippy + tests + cargo-deny
just check        # cargo check all targets, all features
just rtb -- --help   # run the scaffolder CLI

License

MIT — see LICENSE.