nucleo

The reusable Rust CLI framework. The nucleus of your next CLI.

RustPlugin systemMCP-ready

View on GitHub Get Started

terminal

$ nucleo setup

Welcome to nucleo setup!

✓ Authenticated as mateo

✓ Environment: production

✓ Claude Desktop MCP configured

✓ Ready.

Batteries included

Everything you need to build production CLIs, out of the box.

🔐

Auth & OAuth2 PKCE

Basic auth and OAuth2 Authorization Code + PKCE. Automatic token refresh, 401 retry.

⚙️

Multi-Environment Config

JSON-based layered config with named presets. Switch between dev, staging, prod.

📊

6 Output Formats

JSON, table, YAML, CSV, IDs, Slack mrkdwn. Every command supports --format.

🔌

Plugin System

Language-agnostic plugins via subprocess protocol. Python, TypeScript, Go — anything.

⌨️

Shell Completions

bash, zsh, fish, powershell, elvish. One command to generate them all.

🤖

Claude Desktop MCP

Built-in MCP server. Connect your CLI to Claude Desktop out of the box.

🏗️

Project Scaffolding

Template engine with placeholder replacement. Scaffold projects from templates.

🚀

CI/CD Ready

GitHub Actions for quality (check, test, clippy, fmt) and cross-platform release.

🌐

HTTP Client

Retry on 429 with backoff, automatic token refresh, 401 retry. Production-grade requests.

⚠️

Typed Error System

Distinct exit codes (1/2/3/5), structured JSON error output. No panics, no unwraps.

⏱️

Benchmarks

Token consumption and execution speed measurement. Compare output formats side by side.

🧠

Claude Code Integration

Agents, skills, and CLAUDE.md for AI-assisted development. Extend your CLI with AI.

Command tree

nucleo --help

nucleo

├── auth login [--username] [--password] [--oauth2] [--no-browser] | logout | token

├── config show | env (list | use <preset>) | set <key> <value>

├── status [--format text|json|yaml|csv]

├── ping [--service <name> | --url <url>] [--format]

├── echo [--data <json>] [--url <url>] [--format]

├── completions <shell> (bash | zsh | fish | powershell | elvish)

├── plugins

│ ├── list [--format]

│ ├── install <source>

│ ├── remove <name>

│ ├── upgrade [<name>]

│ ├── info <name> [--format]

│ ├── scaffold list | create <name> <template> [--dry-run]

│ ├── hello greet [name] | status

│ └── <name> [subcommand] [args...]

├── mcp (starts MCP server on stdio)

└── setup [--username] [--password] [--env] [--claude-desktop] [--claude-desktop-only] [--check]

Fork in 4 steps

Change 4 constants, update Cargo.toml, build. That's it.

Clone

Fork the repository and clone it locally.

git clone <your-fork>

cd nucleo

Rename

Edit the 4 constants in src/consts.rs.

pub const APP_NAME: &str = "mycli";

pub const APP_DIR: &str = "mycli";

pub const APP_PREFIX: &str = "MYCLI";

pub const APP_BIN: &str = "mycli";

Configure

Update Cargo.toml with your CLI name.

[package]

name = "mycli"

[[bin]]

name = "mycli"

Build

Build the release binary and ship.

cargo build --release

./target/release/mycli --help

One prompt. Any CLI.

The /create-cli skill turns an API description into a production-ready, MCP-enabled CLI — fully branded, tested, and documented.

Describe your CLI

Three questions: name, one-line description, and target API — that's all Claude needs.

Auto-discover the API

Claude reads OpenAPI specs, live documentation URLs (ReadMe, Redoc, Swagger UI, Postman), or loads a built-in profile for 15+ well-known APIs.

Auto-configure auth

OAuth2 PKCE, API key, or basic auth — detected from the API spec and configured automatically.

Generate commands

All command files written automatically with proper error handling, output formats, and flags.

Generate everything

MCP tools for Claude Desktop, tests, README — all written to disk.

Verify & ship

cargo check + test + clippy pass. Binary works. Next steps printed.

/create-cli

$ /create-cli

> CLI name?

spotify-cli

> Description?

Control Spotify from the terminal

> Target API?

Spotify Web API

✓ Loaded Spotify profile

✓ Discovered 87 endpoints

✓ Branded 4 constants in src/consts.rs

✓ Configured OAuth2 PKCE flow

✓ Generated 12 commands from OpenAPI spec

✓ Added 12 MCP tools for Claude Desktop

✓ cargo check → ok

✓ cargo test → 12 passed

spotify-cli is ready.

🎵

spotify-cli

Spotify Web API

$ spotify-cli player now-playing

$ spotify-cli playlists list

$ spotify-cli search tracks

$ spotify-cli recently-played

auth: OAuth2 PKCE

⚙️

gh-cli

GitHub REST API

$ gh-cli repos list

$ gh-cli issues create

$ gh-cli pulls merge

$ gh-cli releases list

auth: Bearer token

💳

stripe-cli

Stripe API

$ stripe-cli customers list

$ stripe-cli charges get

$ stripe-cli invoices list

$ stripe-cli balance show

auth: API key

Architecture

src/

├── main.rs # Clap derive tree + async dispatch

├── consts.rs # 4 constants — the only file to change when forking

├── error.rs # CliError enum with exit codes

├── formatter.rs # 6 output formats

├── client.rs # HTTP client with retry + auth

├── config.rs # Layered config (JSON) with HashMap-based service URLs

├── oauth2.rs # OAuth2 Authorization Code + PKCE

├── types/ # Auth, OAuth2 config, project context, pagination

├── commands/ # All CLI commands

└── mcp/ # MCP server for AI assistant integration