Skip to main content

CLI Reference

The Osaurus CLI provides command-line control over your local LLM server, MCP tools, and model management.

Quick Start​

# Start the server
osaurus serve

# Open the UI
osaurus ui

# Check status
osaurus status

# Interactive chat
osaurus run llama-3.2-3b-instruct-4bit

Installation​

The CLI is embedded in the Osaurus application bundle. When installed via Homebrew, it's automatically linked.

Manual Setup​

If the osaurus command is not found after installation:

# Quick symlink
ln -sf "/Applications/Osaurus.app/Contents/MacOS/osaurus" "$(brew --prefix)/bin/osaurus"

# Or add to PATH
echo 'export PATH="/Applications/Osaurus.app/Contents/MacOS:$PATH"' >> ~/.zshrc
source ~/.zshrc

Commands​

osaurus serve​

Start the Osaurus server.

osaurus serve [options]

Options:

OptionDescriptionDefault
--port, -pServer port number1337
--exposeEnable LAN access (bind to all interfaces)false

Examples:

# Default start (localhost:1337)
osaurus serve

# Custom port
osaurus serve --port 8080

# Enable LAN access
osaurus serve --expose
Environment Variable

Set OSU_PORT to override the default port globally.

osaurus stop​

Stop the running Osaurus server.

osaurus stop

osaurus status​

Check server status and display running configuration.

osaurus status

Example output:

Osaurus Server Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status:     Running
Port:       1337
PID:        12345
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

osaurus ui​

Open the Osaurus graphical interface.

osaurus ui

Launches the app if not already running and brings it to the foreground.

osaurus list​

List all downloaded models.

osaurus list

Example output:

Available Models
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
llama-3.2-3b-instruct-4bit    2.1 GB
mistral-7b-instruct-v0.2-4bit  4.2 GB
deepseek-coder-7b-4bit         4.0 GB
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: 10.3 GB

osaurus run​

Interactive chat session with a model.

osaurus run <model>

Example:

osaurus run llama-3.2-3b-instruct-4bit

Starts an interactive REPL where you can chat with the model. Type /exit or press Ctrl+C to quit.

osaurus mcp​

Start MCP stdio transport for connecting MCP clients.

osaurus mcp

This command proxies MCP protocol over stdio to the running Osaurus server. If the server isn't running, it auto-launches.

Use with MCP clients:

{
  "mcpServers": {
    "osaurus": {
      "command": "osaurus",
      "args": ["mcp"]
    }
  }
}

osaurus tools​

Manage plugins and tools.

osaurus tools <subcommand> [options]

tools install​

Install a plugin from the registry or local directory.

# From registry
osaurus tools install osaurus.browser

# From local directory (must contain manifest.json)
osaurus tools install .
osaurus tools install /path/to/plugin

tools uninstall​

Remove an installed plugin.

osaurus tools uninstall osaurus.browser

tools list​

List all installed plugins.

osaurus tools list

Search for plugins in the registry.

osaurus tools search browser
osaurus tools search filesystem

tools create​

Scaffold a new plugin project.

osaurus tools create MyPlugin --language swift
osaurus tools create MyPlugin --language rust

Creates a directory with:

  • Package.swift or Cargo.toml
  • manifest.json
  • Source file template

tools package​

Package a plugin for distribution.

cd MyPlugin
osaurus tools package

Creates a zip file with the built .dylib and manifest.json.

Environment Variables​

Configure Osaurus using environment variables:

VariableDescriptionDefault
OSU_PORTServer port number1337
OSU_MODELS_DIRCustom models directory~/MLXModels

Example:

# Set in your shell profile
export OSU_PORT=8080
export OSU_MODELS_DIR=/Volumes/External/Models

# Or inline
OSU_PORT=8080 osaurus serve

Common Workflows​

Development Setup​

# Start server with custom port
osaurus serve --port 8080

# In another terminal, check available models
curl http://127.0.0.1:8080/v1/models | jq

# Interactive chat for testing
osaurus run llama-3.2-3b-instruct-4bit

MCP Client Integration​

# Ensure server is running
osaurus status

# If not running, start it
osaurus serve

# MCP client connects via:
# osaurus mcp

Plugin Development​

# Create a new plugin
osaurus tools create MyTool --language swift
cd MyTool

# Build and test
swift build -c release
osaurus tools install .

# Check it's installed
osaurus tools list

LAN Access​

# Start with LAN exposure
osaurus serve --expose

# Other machines can connect via your IP
curl http://192.168.1.100:1337/v1/models

Troubleshooting​

Command Not Found​

  1. Verify Osaurus.app is installed:

    ls /Applications/Osaurus.app

  2. Check symlink exists:

    which osaurus
    ls -la $(which osaurus)

  3. Add to PATH manually if needed:

    export PATH="/Applications/Osaurus.app/Contents/MacOS:$PATH"

Server Won't Start​

  1. Check if already running:

    osaurus status

  2. Check port availability:

    lsof -i :1337

  3. Try a different port:

    osaurus serve --port 8080

Permission Denied​

# Make CLI executable
chmod +x /Applications/Osaurus.app/Contents/MacOS/osaurus

# Don't use sudo for normal operations
osaurus serve  # Correct
sudo osaurus serve  # Not recommended

MCP Connection Issues​

  1. Verify server is running:

    osaurus status

  2. Test MCP endpoint:

    curl http://127.0.0.1:1337/mcp/health

  3. Check installed tools:

    osaurus tools list

For CLI help, check our Discord community or file an issue on GitHub.