https://github.com/mateonunez/nucleo
A reusable CLI framework — the nucleus of your next CLI
https://github.com/mateonunez/nucleo
ai cli framework
Last synced: 2 days ago
JSON representation
A reusable CLI framework — the nucleus of your next CLI
- Host: GitHub
- URL: https://github.com/mateonunez/nucleo
- Owner: mateonunez
- License: mit
- Created: 2026-03-28T20:03:42.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T16:00:11.000Z (3 months ago)
- Last Synced: 2026-05-27T12:30:20.493Z (about 2 months ago)
- Topics: ai, cli, framework
- Language: Rust
- Homepage: https://nucleo-cli.vercel.app
- Size: 191 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# nucleo
> The nucleus of your next CLI.
A reusable Rust CLI framework with batteries included: plugin system, template scaffolding, MCP server, output formatting, layered config, and benchmarks. Fork it, change 4 constants, build your domain.
## Quick Start
```sh
git clone
cd nucleo
# Customize identity (src/consts.rs)
# APP_NAME, APP_DIR, APP_PREFIX, APP_BIN
cargo build --release
./target/release/nucleo --help
```
## Features
- **9 native commands** — auth, config, status, ping, echo, completions, plugins, mcp, setup
- **6 output formats** — JSON, table, YAML, CSV, IDs, Slack mrkdwn
- **Plugin system** — language-agnostic (Python, TypeScript, Rust, Go, anything) via subprocess protocol
- **Scaffold plugin** — create projects, layouts, and components from templates
- **MCP server** — Claude Desktop integration out of the box via `nucleo mcp`
- **Layered config** (JSON) — env vars > top-level URLs > active preset URLs, with auto-selection of first preset
- **OAuth2 PKCE** — Authorization Code flow with PKCE for APIs like Spotify, GitHub, Google
- **HTTP client** — retry on 429, automatic token refresh (basic + OAuth2), 401 retry
- **Error system** — typed errors with distinct exit codes (1/2/3/5) and JSON output
- **Benchmarks** — token consumption and execution speed measurement
- **CI/CD** — GitHub Actions for quality (check, test, clippy, fmt) and cross-platform release
- **Claude Code integration** — agents, skills, and CLAUDE.md for AI-assisted development
- **Shell completions** — bash, zsh, fish, powershell, elvish
## 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
```
## How to Fork
**Full guide:** [docs/guides/create-a-new-cli.md](docs/guides/create-a-new-cli.md)
**Quick version:**
1. Edit `src/consts.rs` — change the 4 identity constants
2. Update `Cargo.toml` — package name and `[[bin]]` name
3. Remove example commands (`ping`, `echo`)
4. Add your domain commands following the patterns in `src/commands/`
5. Configure auth in `config.json` (OAuth2 PKCE, API key, or basic)
6. `cargo build --release`
**With Claude Code:**
```sh
npx skills add mateonunez/nucleo
```
Then run `/create-cli` — it discovers your API endpoints, configures auth, and generates everything automatically.
## Commands
| Command | Description |
|---------|-------------|
| `auth login\|logout\|token` | Manage authentication (basic or OAuth2 PKCE) |
| `config show\|env\|set` | View and modify configuration |
| `status` | System, auth, and config overview |
| `ping` | HTTP GET example (test connectivity) |
| `echo` | Authenticated HTTP POST example |
| `plugins` | Install, remove, upgrade, and run plugins |
| `mcp` | Start MCP server for Claude Desktop |
| `setup` | Interactive setup wizard |
| `completions` | Generate shell completions |
## Plugins
Plugins are language-agnostic extensions. Any executable with a `plugin.json` manifest works:
```sh
nucleo plugins install ./plugins/hello # install
nucleo plugins hello greet # run
nucleo plugins list # list installed
nucleo plugins remove hello # uninstall
```
**Shipped plugins:**
| Plugin | Language | Purpose |
|--------|----------|---------|
| `hello` | TypeScript | Example plugin demonstrating the protocol |
| `scaffold` | Node.js | Template scaffolding for new projects |
```sh
nucleo plugins install ./plugins/scaffold
nucleo plugins scaffold list # list templates
nucleo plugins scaffold create my-app hello-api # scaffold a project
```
## MCP Server
Connect nucleo to Claude Desktop. Add this to your config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"nucleo": {
"command": "nucleo",
"args": ["mcp"]
}
}
}
```
Or automate it:
```sh
nucleo setup --claude-desktop
```
**Available tools:**
| Tool | Description |
|------|-------------|
| `nucleo_status` | Check CLI status: version, auth, project context, configured URLs |
| `nucleo_ping` | Ping a service URL to check connectivity and measure latency |
| `nucleo_plugins_list` | List installed plugins with their versions and commands |
## Benchmarks
```sh
./benchmarks/run.sh # full suite
./benchmarks/run.sh --quick # smoke test
./benchmarks/run.sh --formats # compare output formats
./benchmarks/run.sh --json # raw JSON
```
## Stack
- **Rust** (edition 2024, rust-version 1.85)
- **clap** 4.6 (derive macros)
- **tokio** 1.50 (async runtime)
- **reqwest** 0.12 (HTTP client)
- **rmcp** 1.3 (MCP server)
- **serde** / **serde_json** (serialization)
- **sha2** 0.10 / **rand** 0.9 (OAuth2 PKCE)
- **thiserror** 2 / **anyhow** (error handling)
## License
[MIT](LICENSE)