{"id":51642991,"url":"https://github.com/mateonunez/nucleo","last_synced_at":"2026-07-13T20:03:23.086Z","repository":{"id":347661367,"uuid":"1194782016","full_name":"mateonunez/nucleo","owner":"mateonunez","description":"A reusable CLI framework — the nucleus of your next CLI","archived":false,"fork":false,"pushed_at":"2026-04-08T16:00:11.000Z","size":196,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T12:30:20.493Z","etag":null,"topics":["ai","cli","framework"],"latest_commit_sha":null,"homepage":"https://nucleo-cli.vercel.app","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mateonunez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T20:03:42.000Z","updated_at":"2026-04-12T03:55:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mateonunez/nucleo","commit_stats":null,"previous_names":["mateonunez/nucleo"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mateonunez/nucleo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Fnucleo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Fnucleo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Fnucleo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Fnucleo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mateonunez","download_url":"https://codeload.github.com/mateonunez/nucleo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mateonunez%2Fnucleo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35434590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","framework"],"created_at":"2026-07-13T20:03:22.185Z","updated_at":"2026-07-13T20:03:23.081Z","avatar_url":"https://github.com/mateonunez.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nucleo\n\n\u003e The nucleus of your next CLI.\n\nA 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.\n\n## Quick Start\n\n```sh\ngit clone \u003cyour-fork\u003e\ncd nucleo\n\n# Customize identity (src/consts.rs)\n# APP_NAME, APP_DIR, APP_PREFIX, APP_BIN\n\ncargo build --release\n./target/release/nucleo --help\n```\n\n## Features\n\n- **9 native commands** — auth, config, status, ping, echo, completions, plugins, mcp, setup\n- **6 output formats** — JSON, table, YAML, CSV, IDs, Slack mrkdwn\n- **Plugin system** — language-agnostic (Python, TypeScript, Rust, Go, anything) via subprocess protocol\n- **Scaffold plugin** — create projects, layouts, and components from templates\n- **MCP server** — Claude Desktop integration out of the box via `nucleo mcp`\n- **Layered config** (JSON) — env vars \u003e top-level URLs \u003e active preset URLs, with auto-selection of first preset\n- **OAuth2 PKCE** — Authorization Code flow with PKCE for APIs like Spotify, GitHub, Google\n- **HTTP client** — retry on 429, automatic token refresh (basic + OAuth2), 401 retry\n- **Error system** — typed errors with distinct exit codes (1/2/3/5) and JSON output\n- **Benchmarks** — token consumption and execution speed measurement\n- **CI/CD** — GitHub Actions for quality (check, test, clippy, fmt) and cross-platform release\n- **Claude Code integration** — agents, skills, and CLAUDE.md for AI-assisted development\n- **Shell completions** — bash, zsh, fish, powershell, elvish\n\n## Architecture\n\n```\nsrc/\n├── main.rs          # Clap derive tree + async dispatch\n├── consts.rs        # 4 constants — the only file to change when forking\n├── error.rs         # CliError enum with exit codes\n├── formatter.rs     # 6 output formats\n├── client.rs        # HTTP client with retry + auth\n├── config.rs        # Layered config (JSON) with HashMap-based service URLs\n├── oauth2.rs        # OAuth2 Authorization Code + PKCE\n├── types/           # Auth, OAuth2 config, project context, pagination\n├── commands/        # All CLI commands\n└── mcp/             # MCP server for AI assistant integration\n```\n\n## How to Fork\n\n**Full guide:** [docs/guides/create-a-new-cli.md](docs/guides/create-a-new-cli.md)\n\n**Quick version:**\n\n1. Edit `src/consts.rs` — change the 4 identity constants\n2. Update `Cargo.toml` — package name and `[[bin]]` name\n3. Remove example commands (`ping`, `echo`)\n4. Add your domain commands following the patterns in `src/commands/`\n5. Configure auth in `config.json` (OAuth2 PKCE, API key, or basic)\n6. `cargo build --release`\n\n**With Claude Code:**\n\n```sh\nnpx skills add mateonunez/nucleo\n```\n\nThen run `/create-cli` — it discovers your API endpoints, configures auth, and generates everything automatically.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `auth login\\|logout\\|token` | Manage authentication (basic or OAuth2 PKCE) |\n| `config show\\|env\\|set` | View and modify configuration |\n| `status` | System, auth, and config overview |\n| `ping` | HTTP GET example (test connectivity) |\n| `echo` | Authenticated HTTP POST example |\n| `plugins` | Install, remove, upgrade, and run plugins |\n| `mcp` | Start MCP server for Claude Desktop |\n| `setup` | Interactive setup wizard |\n| `completions` | Generate shell completions |\n\n## Plugins\n\nPlugins are language-agnostic extensions. Any executable with a `plugin.json` manifest works:\n\n```sh\nnucleo plugins install ./plugins/hello       # install\nnucleo plugins hello greet                   # run\nnucleo plugins list                          # list installed\nnucleo plugins remove hello                  # uninstall\n```\n\n**Shipped plugins:**\n\n| Plugin | Language | Purpose |\n|--------|----------|---------|\n| `hello` | TypeScript | Example plugin demonstrating the protocol |\n| `scaffold` | Node.js | Template scaffolding for new projects |\n\n```sh\nnucleo plugins install ./plugins/scaffold\nnucleo plugins scaffold list                            # list templates\nnucleo plugins scaffold create my-app hello-api         # scaffold a project\n```\n\n## MCP Server\n\nConnect nucleo to Claude Desktop. Add this to your config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"nucleo\": {\n      \"command\": \"nucleo\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nOr automate it:\n\n```sh\nnucleo setup --claude-desktop\n```\n\n**Available tools:**\n\n| Tool | Description |\n|------|-------------|\n| `nucleo_status` | Check CLI status: version, auth, project context, configured URLs |\n| `nucleo_ping` | Ping a service URL to check connectivity and measure latency |\n| `nucleo_plugins_list` | List installed plugins with their versions and commands |\n\n## Benchmarks\n\n```sh\n./benchmarks/run.sh              # full suite\n./benchmarks/run.sh --quick      # smoke test\n./benchmarks/run.sh --formats    # compare output formats\n./benchmarks/run.sh --json       # raw JSON\n```\n\n## Stack\n\n- **Rust** (edition 2024, rust-version 1.85)\n- **clap** 4.6 (derive macros)\n- **tokio** 1.50 (async runtime)\n- **reqwest** 0.12 (HTTP client)\n- **rmcp** 1.3 (MCP server)\n- **serde** / **serde_json** (serialization)\n- **sha2** 0.10 / **rand** 0.9 (OAuth2 PKCE)\n- **thiserror** 2 / **anyhow** (error handling)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateonunez%2Fnucleo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmateonunez%2Fnucleo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmateonunez%2Fnucleo/lists"}