CLI Installation

The OneMCP CLI (onemcp) is a lightweight cross-platform tool designed to simplify how users interact with the OneMCP runtime. It provides a unified interface for:

Chatting with the server
Triggering assignments
Running regression tests
Managing configuration
Controlling local or remote OneMCP instances

The CLI is distributed as a standalone binary, with first-class support for:

macOS (Intel & Apple Silicon)
Linux (AMD64)
Windows (AMD64 & ARM64)

It can be used in terminals, shells, as part of automation scripts, or CI pipelines.

1. Installing the CLI

1.1 macOS & Linux (Homebrew)

The CLI is available via Homebrew, the simplest way to install on macOS and Linux.

Install


brew tap gentoro-onemcp/onemcp
brew install onemcp

Upgrade


brew upgrade onemcp

Verify


onemcp --help

1.2 Windows (PowerShell via `scoop`)

Windows users can install using Scoop, a popular PowerShell package manager.

Install Scoop (if needed)


Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
iwr -useb get.scoop.sh | iex

Install the CLI


scoop bucket add gentoro-onemcp https://github.com/Gentoro-OneMCP/onemcp-scoop
scoop install onemcp

Upgrade


scoop update onemcp

Verify


onemcp --help

1.3 Manual Installation

For air-gapped systems, custom environments, or if you prefer manual installation.

Download Binaries

Visit GitHub Releases and download the appropriate binary:

Available platforms:

macOS (Apple Silicon): onemcp-darwin-arm64.tar.gz
macOS (Intel): onemcp-darwin-amd64.tar.gz
Linux (AMD64): onemcp-linux-amd64.tar.gz
Windows (AMD64): onemcp-windows-amd64.zip
Windows (ARM64): onemcp-windows-arm64.zip

Install on Linux/macOS


# Download (replace with your platform and latest version)
curl -LO https://github.com/Gentoro-OneMCP/onemcp/releases/download/cli-v0.0.3/onemcp-darwin-arm64.tar.gz
 
# Extract
tar -xzf onemcp-darwin-arm64.tar.gz
 
# Install to system path
sudo mv onemcp /usr/local/bin/
 
# Verify
onemcp --help

Install on Windows

Download the appropriate .zip file for your architecture
Extract onemcp.exe
Move to a directory in your PATH (e.g., C:\Program Files\onemcp\)
Or add the directory to your PATH environment variable


# Verify
onemcp --help

2. Basic Usage

The onemcp tool uses the following structure:


onemcp [command] [options]

Common Commands


# Start interactive chat
onemcp chat
 
# Check server status
onemcp status
 
# View logs
onemcp logs
 
# Stop server
onemcp stop
 
# Check system requirements
onemcp doctor

Getting Help


# Show all commands
onemcp --help
 
# Show help for specific command
onemcp chat --help

3. Requirements

System requirements:

Docker Desktop - Required to run the OneMCP server
Operating System:
- macOS 10.15 or later
- Windows 10 or later
- Linux with Docker support

Docker installation:

4. Verify Installation

After installation, verify everything works:


# Check CLI is installed
onemcp --help
 
# Check Docker is running
docker ps
 
# Run system check
onemcp doctor

Expected output from onemcp doctor:


✓ Docker is installed
✓ Docker daemon is running
✓ Network connectivity OK
✓ Configuration file valid
✓ All requirements met

5. Next Steps

Quick Start: Run onemcp chat to start your first session
CLI Guide: See the CLI Guide for detailed usage
Shell Completion: Set up Shell Completion for faster typing
Configuration: Learn about Configuration

6. Troubleshooting

Installation Issues

Homebrew tap not found:


brew tap gentoro-onemcp/onemcp
brew update
brew install onemcp

Scoop bucket not found:


scoop bucket add gentoro-onemcp https://github.com/Gentoro-OneMCP/onemcp-scoop
scoop update
scoop install onemcp

Permission denied (Linux/macOS):


# Install to user directory instead
mv onemcp ~/.local/bin/
 
# Ensure ~/.local/bin is in PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Docker Issues

Docker not running:


# macOS/Windows: Start Docker Desktop application
# Linux: Start Docker daemon
sudo systemctl start docker

Docker permission denied (Linux):


# Add user to docker group
sudo usermod -aG docker $USER
 
# Log out and back in for changes to take effect

For more help, see the CLI Guide Troubleshooting section.

7. Updating

Homebrew


brew upgrade onemcp

Scoop


scoop update onemcp

Manual Installation

Download the latest release
Replace the existing binary
Verify the new version

8. Uninstallation

Homebrew


brew uninstall onemcp
brew untap gentoro-onemcp/onemcp

Scoop


scoop uninstall onemcp

Manual Installation


# Linux/macOS
sudo rm /usr/local/bin/onemcp
 
# Windows
# Delete onemcp.exe from installation directory

Clean up configuration (optional):


rm -rf ~/.onemcp

Note: This deletes all configuration. Handbooks are in ~/onemcp-handbooks and must be deleted separately if desired.