npm package: @robinpath/cli
Description: AI-powered scripting CLI — automate anything from your terminal
Latest version: 4.4.1

# RobinPath CLI

AI-powered scripting CLI — automate anything from your terminal.

## Install

```
npm install -g @robinpath/cli
```

Requires Node.js 18+.

## Use with AI Clients (MCP)

RobinPath includes a built-in [MCP server](https://modelcontextprotocol.io) that works with Claude Code, Cursor, Windsurf, Codex CLI, and any MCP-compatible AI client.

### Quick Setup (recommended)

```sh
robinpath mcp init
```

That's it. Auto-detects your AI clients and configures them. Or target a specific client:

```sh
robinpath mcp init claude     # Claude Code (global)
robinpath mcp init project    # Current project only (.mcp.json)
robinpath mcp init cursor     # Cursor
robinpath mcp init windsurf   # Windsurf
```

Check connection status:

```sh
robinpath mcp status
```

### Manual Setup

If you prefer manual configuration:

**Claude Code** — add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "robinpath": {
      "command": "robinpath",
      "args": ["mcp"]
    }
  }
}
```

**Cursor** — Settings > MCP Servers > Add: command `robinpath`, args `mcp`, transport `stdio`

**Windsurf** — add the same JSON to your MCP config

### What you get

Once connected, your AI client gets **16 tools**:

| Tool | Description |
|------|-------------|
| `robinpath_resolve` | Find relevant modules via AI Brain — checks what's installed vs missing |
| `robinpath_generate` | AI-powered code generation with RAG and validation |
| `robinpath_query` | Search documentation for function signatures and examples |
| `robinpath_execute` | Run a RobinPath script and get output |
| `robinpath_execute_file` | Run a .rp script file |
| `robinpath_check_syntax` | Validate script syntax without executing |
| `robinpath_format` | Prettify RobinPath code |
| `robinpath_get_ast` | Parse script to AST |
| `robinpath_list_modules` | List native + installed modules |
| `robinpath_search_modules` | Search the module registry |
| `robinpath_install_module` | Install a registry module |
| `robinpath_remove_module` | Remove a module |
| `robinpath_info` | CLI version, environment status |
| `robinpath_run_tests` | Run test files with assertions |
| `robinpath_env_set` | Set encrypted environment variable |
| `robinpath_env_list` | List environment variables |

### Context-aware intelligence

The MCP server automatically tells your AI client:
- Which **native modules** are available (file, http, crypto, os, etc.)
- Which **registry modules** are installed
- Which **env vars** are configured
- What's **missing** when you ask for something that needs a module you don't have

Example: if you ask *"send a Slack message and email the results"*, the AI will tell you that `@robinpath/slack` and `@robinpath/email` need to be installed first, and offer to install them.

### MCP server options

```sh
robinpath mcp                          # default
robinpath mcp --read-only              # disable write operations
robinpath mcp --timeout 30000          # 30s execution timeout
robinpath mcp --log-file audit.log     # audit log
robinpath mcp --tools execute,resolve  # whitelist specific tools
```

### Enterprise features

- **Input validation** — module names, env keys, file paths all validated
- **Command injection protection** — safe argument passing (no shell interpolation)
- **Rate limiting** — 30/min for execution tools, 60/min for reads
- **Audit logging** — optional JSON log of all tool calls
- **Read-only mode** — disable all write operations
- **Tool whitelisting** — expose only the tools you need
- **File restrictions** — only `.rp`/`.robin` files can be executed
- **Script size limits** — 100KB max per execution
- **Path traversal protection** — blocks `..` escapes

## Getting Started

```
robinpath
```

First run guides you through:
1. **Login** — authenticate with your RobinPath account
2. **API key** — paste your OpenRouter key (get one at [openrouter.ai/keys](https://openrouter.ai/keys))
3. **Ready** — start chatting with the AI

## Usage

```sh
# Interactive AI assistant
robinpath

# Headless AI prompt (for scripts/piping)
robinpath -p "create a script that fetches weather data"

# Run a script
robinpath hello.rp

# Inline code
robinpath -e 'log "Hello World"'
```

## AI Commands (inside the REPL)

| Command | Description |
|---------|-------------|
| `/model` | Switch AI model (arrow-key selector) |
| `/settings` | View API key, model, shell config |
| `/clear` | Clear conversation |
| `/save` | Save session |
| `/sessions` | List saved sessions |
| `/resume` | Resume a session |
| `/memory` | Persistent memory across sessions |
| `/init` | Create ROBINPATH.md project config |
| `/auto` | Toggle auto-accept for commands |
| `/shell` | Switch shell (bash, powershell, zsh) |
| `/usage` | Token usage and cost |
| `@filename` | Include file contents in prompt |
| `exit` | Quit |

## CLI Commands

```sh
robinpath <file.rp>          # Run a script
robinpath -p "prompt"        # AI headless mode
robinpath -e "code"          # Execute inline code
robinpath fmt <file>         # Format code
robinpath check <file>       # Syntax check
robinpath test [dir]         # Run tests
robinpath add <pkg>          # Install a module
robinpath remove <pkg>       # Remove a module
robinpath search <query>     # Search module registry
robinpath login              # Authenticate
robinpath update             # Self-update to latest
robinpath uninstall          # Clean removal
robinpath mcp                # Start MCP server
```

## Flags

| Flag | Description |
|------|-------------|
| `-p "prompt"` | AI headless mode |
| `--save` | Save generated code to .rp file |
| `--run` | Save and run generated code |
| `-o <file>` | Output filename |
| `--auto` | Auto-accept commands |
| `--dev` | Dev mode (auto + verbose) |
| `-v` | Version |
| `-h` | Help |

## ROBINPATH.md

Create a `ROBINPATH.md` file in your project to customize the AI's behavior — like Claude Code's `CLAUDE.md`. The AI reads it automatically on startup.

```
robinpath
> /init
```

## Configuration

```sh
robinpath ai config set-key ...       # Set API key
robinpath ai config set-model <id>    # Set model
robinpath ai config show              # View config
robinpath ai config remove            # Remove config
```

## Links

- Website: [dev.robinpath.com](https://dev.robinpath.com)
- npm: [@robinpath/cli](https://www.npmjs.com/package/@robinpath/cli)
- GitHub: [wiredwp/robinpath-cli](https://github.com/wiredwp/robinpath-cli)