Rust Workspace Template

A batteries-included Rust workspace template with CLI, TUI, MCP server, and HTTP API crates sharing a common core library.

Quick Start

Install the latest stable Rust toolchain (rustup default stable), then:

cargo build
cargo test

Run individual binaries:

cargo run -p kyz-cli -- run
cargo run -p kyz-tui
cargo run -p kyz-api -- --port 3000
cargo run -p kyz-mcp

Scaffold a new project:

scripts/new-cli.sh my-app

pwsh scripts/new-cli.ps1 my-app

This creates a new workspace with all crates renamed (e.g., my-app-core, my-app-cli, etc.).

Workspace Structure

crates/
  kyz-core/    # Shared library: config, paths, error types
  kyz-cli/     # Command-line interface
  kyz-tui/     # Terminal user interface (ratatui)
  kyz-mcp/     # Model Context Protocol server
  kyz-api/     # HTTP API server (axum)
examples/
  config.toml   # Example configuration
scripts/
  new-cli.sh    # Unix scaffolding script
  new-cli.ps1   # PowerShell scaffolding script

Crates

kyz-core

Shared library providing:

• AppConfig - Configuration loading via config crate
• AppPaths - XDG-compliant path resolution
• Error types and common utilities

kyz-cli

Command-line interface with:

• Subcommands: run, init, config, completions
• Global flags: -q, -v, --debug, --trace, --json, --yaml, --no-color, --dry-run, --yes
• Shell completion generation

cargo run -p kyz-cli -- --help
cargo run -p kyz-cli -- completions bash > target/kyz-cli.bash

kyz-tui

Terminal UI built with ratatui featuring:

• Three-pane layout (navigation, list, details)
• Vim-style navigation (j/k/h/l)
• Modal help system

cargo run -p kyz-tui

kyz-mcp

MCP (Model Context Protocol) server exposing tools:

• get_profile - Current configuration profile
• echo - Echo messages
• get_runtime_config - Runtime configuration

cargo run -p kyz-mcp

kyz-api

HTTP API server (axum) with endpoints:

• GET / - Service info
• GET /health - Health check
• GET /config - Current configuration

cargo run -p kyz-api -- --port 3000
curl http://localhost:3000/health

Optional API auth:

• Set KYZ_API_TOKEN to require Authorization: Bearer <token> on all endpoints except /health.

kyz exec

Wrap any command with secrets injected as environment variables:

# Using a config alias
kyz exec --alias deploy -- make deploy

# Explicit secret references
kyz exec --secret github/deploy-key --secret aws/prod -- ./deploy.sh

# Explicit env-var mapping
kyz exec --env GITHUB_TOKEN=github/deploy-key:token -- gh pr create

# Tag-based: inject all secrets tagged "dev"
kyz exec --tag dev -- cargo test

# Interactive fzf picker (multi-select with TAB)
kyz exec --pick -- ./my-app

Aliases in config.toml

[aliases.deploy]
secrets = ["github/deploy-key", "aws/prod-creds"]
tags = ["deploy"]
env_map = { GITHUB_TOKEN = "github/deploy-key:token" }

[aliases.dev]
tags = ["dev"]

Secret tags

kyz set deploy-key --service github -f token=ghp_xxx --tag deploy --tag ci

Configuration

Default config path: $XDG_CONFIG_HOME/kyz/config.toml (fallback: ~/.config/kyz/config.toml).

Override with --config <path> or environment variables using the KYZ__ prefix:

KYZ__LOGGING__LEVEL=debug cargo run -p kyz-cli -- run

See examples/config.toml for all options.

Development

cargo fmt                                    # Format code
cargo clippy --all-targets --all-features   # Lint
cargo test                                   # Run tests
cargo build --release                        # Release build

Scaffolding

The scripts/new-cli.sh (Unix) and scripts/new-cli.ps1 (PowerShell) scripts create a new project from this template:

scripts/new-cli.sh my-app --path ~/projects/my-app

This will:

1. Copy the template to the destination
2. Rename all crates from rust-* to my-app-*
3. Update all references in Cargo.toml, source files, and documentation
4. Rename crate directories accordingly

Requirements: python3 for the shell script, PowerShell 7 for the Windows script.