RUDI CLI

A universal tool manager for MCP stacks, CLI tools, runtimes, and AI agents.

RUDI provides a unified installation and management system for:

• MCP Stacks - Model Context Protocol servers for Claude, Codex, and Gemini
• CLI Tools - Any npm package or upstream binary (ffmpeg, ripgrep, etc.)
• Runtimes - Node.js, Python, Deno, Bun
• AI Agents - Claude Code, Codex CLI, Gemini CLI

Installation

npm install -g @learnrudi/cli

Requires Node.js 18 or later. The installer creates ~/.rudi/ and adds shims to ~/.rudi/bins/.

Add to your shell profile (.bashrc, .zshrc, or .profile):

export PATH="$HOME/.rudi/bins:$PATH"

Core Concepts

Shim-Based Architecture

Every tool installed through RUDI gets a wrapper script (shim) in ~/.rudi/bins/. This provides:

• Clean PATH integration without modifying system directories
• Version isolation per package
• Ownership tracking for clean uninstalls
• Consistent invocation across different package sources

When you run tsc, the shell finds ~/.rudi/bins/tsc, which delegates to the actual TypeScript installation at ~/.rudi/binaries/npm/typescript/node_modules/.bin/tsc.

Package Sources

RUDI supports three installation sources:

1. Dynamic npm (npm:<package>) - Any npm package with a bin field
2. Curated Registry - Pre-configured stacks and binaries with documentation
3. Upstream Binaries - Direct downloads from official sources

Secret Management

MCP stacks often require API keys and tokens. RUDI stores secrets in ~/.rudi/secrets.json (mode 0600) and injects them as environment variables when running stacks. Secrets are never exposed in process listings or logs.

Usage

Installing Packages

# Install any npm CLI tool
rudi install npm:typescript       # Installs tsc, tsserver
rudi install npm:@stripe/cli      # Installs stripe
rudi install npm:vercel           # Installs vercel

# Install from curated registry
rudi install slack                # MCP stack for Slack
rudi install binary:ffmpeg        # Upstream ffmpeg binary
rudi install binary:supabase      # Supabase CLI

# Install with scripts enabled (when needed)
rudi install npm:puppeteer --allow-scripts

Listing Installed Packages

rudi list                # All installed packages
rudi list stacks         # MCP stacks only
rudi list binaries       # CLI tools only
rudi list runtimes       # Language runtimes
rudi list agents         # AI agent CLIs

Searching the Registry

rudi search pdf          # Search for packages
rudi search --all        # List all available packages
rudi search --stacks     # Filter to MCP stacks
rudi search --binaries   # Filter to CLI tools

Managing Secrets

rudi secrets list                      # Show configured secrets (masked)
rudi secrets set SLACK_BOT_TOKEN       # Set a secret (prompts for value)
rudi secrets set OPENAI_API_KEY "sk-..." # Set with value
rudi secrets remove SLACK_BOT_TOKEN    # Remove a secret

Integrating with AI Agents

rudi integrate claude    # Add stacks to Claude Desktop config
rudi integrate codex     # Add stacks to Codex config
rudi integrate gemini    # Add stacks to Gemini config
rudi integrate all       # Add to all detected agents

This modifies the agent's MCP configuration file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json) to include your installed stacks with proper secret injection.

Inspecting Packages

rudi pkg slack           # Show package details
rudi pkg npm:typescript  # Show shims and paths

rudi shims list          # List all shims
rudi shims check         # Validate shim targets exist

Maintenance

rudi update              # Update all packages
rudi update slack        # Update specific package
rudi remove slack        # Uninstall a package
rudi doctor              # Check system health

Directory Structure

~/.rudi/
├── bins/                 # Shims (add to PATH)
│   ├── tsc              # → binaries/npm/typescript/...
│   ├── ffmpeg           # → binaries/ffmpeg/...
│   └── rudi-mcp         # MCP router for agents
│
├── stacks/               # MCP server installations
│   ├── slack/
│   │   ├── manifest.json
│   │   ├── index.js
│   │   └── node_modules/
│   └── google-workspace/
│
├── binaries/             # CLI tool installations
│   ├── ffmpeg/           # Upstream binary
│   ├── supabase/         # npm-based CLI
│   └── npm/              # Dynamic npm packages
│       ├── typescript/
│       └── vercel/
│
├── runtimes/             # Language runtimes
│   ├── node/
│   └── python/
│
├── agents/               # AI agent CLI installations
│
├── secrets.json          # API keys (mode 0600)
├── shim-registry.json    # Shim ownership tracking
└── rudi.db               # Local metadata database

How MCP Integration Works

When you run rudi integrate claude, RUDI:

1. Reads the Claude Desktop config at ~/Library/Application Support/Claude/claude_desktop_config.json
2. Adds entries for each installed stack pointing to ~/.rudi/bins/rudi-mcp
3. Passes the stack ID as an argument

When Claude invokes the MCP server:

1. rudi-mcp receives the stack ID
2. Loads secrets from ~/.rudi/secrets.json
3. Injects secrets as environment variables
4. Spawns the actual MCP server process
5. Proxies stdio between Claude and the server

This architecture means secrets stay local and are never written to agent config files.

Security Model

npm Package Installation

By default, npm packages install with --ignore-scripts to prevent arbitrary code execution during install. If a package requires lifecycle scripts (e.g., native compilation), use:

rudi install npm:puppeteer --allow-scripts

Secret Storage

Secrets are stored in ~/.rudi/secrets.json with file permissions 0600 (owner read/write only). This matches the security model used by SSH, AWS CLI, and other credential stores.

Shim Isolation

Each package installs to its own directory. Shims are thin wrappers that set up the environment and delegate to the real binary. This prevents packages from interfering with each other.

Available Stacks

Stack	Description	Required Secrets
slack	Channels, messages, reactions	SLACK_BOT_TOKEN
google-workspace	Gmail, Sheets, Docs, Drive	GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
notion-workspace	Pages, databases, search	NOTION_API_KEY
github	Issues, PRs, repos, actions	GITHUB_TOKEN
postgres	SQL queries	DATABASE_URL
stripe	Payments, subscriptions	STRIPE_SECRET_KEY
openai	DALL-E, Whisper, TTS	OPENAI_API_KEY
google-ai	Gemini, Imagen	GOOGLE_AI_API_KEY

Available Binaries

Binary	Description	Source
ffmpeg	Video/audio processing	Upstream
ripgrep	Fast text search	Upstream
supabase	Supabase CLI	npm
vercel	Vercel CLI	npm
uv	Python package manager	Upstream

Troubleshooting

Command not found after install

Ensure ~/.rudi/bins is in your PATH:

echo $PATH | grep -q '.rudi/bins' && echo "OK" || echo "Add ~/.rudi/bins to PATH"

Shim points to missing target

Run rudi shims check to validate all shims. If a target is missing, reinstall the package:

rudi remove npm:typescript
rudi install npm:typescript

MCP stack not appearing in agent

1. Check the stack is installed: rudi list stacks
2. Run integration: rudi integrate claude
3. Restart the AI agent application

Permission denied on secrets

Ensure correct permissions:

chmod 600 ~/.rudi/secrets.json

Links

• Documentation: https://learn-rudi.github.io/cli/
• Repository: https://github.com/learn-rudi/cli
• Registry: https://github.com/learn-rudi/registry
• npm: https://www.npmjs.com/package/@learnrudi/cli
• Issues: https://github.com/learn-rudi/cli/issues

License

MIT