Merlin CLI

Merlin is a powerful AI-powered command-line assistant for developers, created by Village Labs.

Installation

# Install globally from npm
npm install -g @villagelabs/merlin

After installation, verify that the command is available:

merlin --help

Quick Start

# Start Merlin in your current directory
merlin

Merlin will guide you through a one-time setup process to configure your API key and set your network.

Features

• AI-Powered Assistance: Get help with coding tasks, debugging, and more
• Context-Aware: Understands your codebase and working directory
• Command Integration: Execute shell commands directly from the interface
• Conversation History: Save and review your interactions

Commands

Once inside the Merlin interface, you can use these commands:

/help       - Display help message
/quit       - Exit the application
/cd <path>  - Change working directory
/clear      - Clear the screen
/history    - Show conversation history
/save <file>- Save conversation history to file
/root       - Show current working directory
/restart    - Restart the conversation

Bash Mode

Type ! at the beginning of a line to enter bash mode and execute shell commands directly.

Canceling queries

If you see Merlin start down the wrong path, or you change your mind just press Escape to cancel the current generation, and let Merlin know how they should proceed instead.

Configuration

Command Line Options

# Use a specific model
merlin --model claude-sonnet-4-20250514

# Specify a working directory, otherwise uses the launchred directory
merlin --root /path/to/project

# Enable verbose logging
merlin --verbose

# Use a specific API key and network
merlin --api-key YOUR_API_KEY --network YOUR_NETWORK_ID

# Skip the configuration screen
merlin --skip-config --api-key YOUR_API_KEY --network YOUR_NETWORK_ID

# Run in single-shot mode (process one query and exit)
merlin --single-shot "What does this code do?"

Managing Configuration

# View current configuration
merlin config --show

# Reset configuration
merlin config --reset

# Run the configuration wizard
merlin config

Local configuration can also be edited at

~/.village-merlin

Safety System

Merlin includes a built-in safety system that protects your system by requiring confirmation before executing potentially sensitive operations.

How It Works

When Merlin attempts to perform a sensitive operation (like editing files or running certain commands), you'll see a safety prompt asking for permission. You have four options:

• [o]nce: Allow this specific operation one time only
• [a]lways: Always allow similar operations in the future
• [n]ever: Never allow this type of operation (you'll be asked again if needed)
• [c]ancel: Cancel the current operation

Your preferences are saved between sessions, so Merlin will remember which operations you've approved.

Understanding Tool Keys

The safety system identifies similar operations using "tool keys" that follow these patterns:

• For bash commands: bash(command) - Examples: bash(git), bash(npm install)
• For file operations: toolname(path) - Examples: edit_file(src/*), view(/etc/nginx/)

System directories and sensitive commands receive more specific keys to ensure proper protection.

Support

For support, please contact Village Labs or visit our website.

License

View license in LICENSE.md