Skip to main content

CLI

The Osaurus CLI controls your local LLM server, MCP tools, and models from the terminal.

Quick Start​

# Start the server
osaurus serve

# Open the UI
osaurus ui

# Check status
osaurus status

# Diagnose a broken install
osaurus doctor

# Download a model, then chat with it
osaurus pull mlx-community/Llama-3.2-1B-4bit
osaurus run gemma-4-e2b-it-4bit

Installation​

The CLI ships inside the Osaurus application bundle. The Homebrew cask links it automatically and owns that link.

Manual Setup​

If the osaurus command is not found after installation:

cli="/Applications/Osaurus.app/Contents/Helpers/osaurus"
[ -x "$cli" ] || cli="/Applications/Osaurus.app/Contents/MacOS/osaurus"

# Prefer /usr/local/bin; fall back without sudo.
bin="/usr/local/bin"
if [ ! -d "$bin" ] || [ ! -w "$bin" ]; then
  bin="$HOME/.local/bin"
  mkdir -p "$bin"
fi
ln -sf "$cli" "$bin/osaurus"

Do not write into $(brew --prefix)/bin for a DMG install: Homebrew manages that directory. If the link uses ~/.local/bin, add it to PATH. From a source checkout, scripts/release/install_cli_symlink.sh --prefix <directory> explicitly targets <directory>/bin; without --prefix, it follows the same /usr/local/bin then ~/.local/bin order.

Commands​

osaurus serve​

Start the Osaurus server.

osaurus serve [options]

Options:

OptionDescriptionDefault
--portServer port number1337
--exposeEnable LAN access (bind to all interfaces)false
--yes, -ySkip the interactive security prompt that --expose showsfalse
--superviseKeep the server alive — probe health and relaunch it whenever it goes downfalse
--intervalHealth-probe interval in seconds (with --supervise)15

Examples:

# Default start (localhost:1337)
osaurus serve

# Custom port
osaurus serve --port 8080

# Enable LAN access
osaurus serve --expose

# Keep-alive loop that survives app quits and crashes
osaurus serve --supervise
Environment Variable

Set OSU_PORT to override the default port globally.

Supervise mode​

Plain osaurus serve is a one-shot command: it launches the app, starts the server, and exits. If the app later quits or crashes, nothing brings the server back.

--supervise never exits — it probes /health every --interval seconds and relaunches the server whenever it's down. Pair it with a launchd LaunchAgent for quit/crash/logout/reboot resilience:

<!-- ~/Library/LaunchAgents/ai.osaurus.serve.plist -->
<dict>
  <key>Label</key>            <string>ai.osaurus.serve</string>
  <key>ProgramArguments</key> <array>
      <string>/opt/homebrew/bin/osaurus</string>
      <string>serve</string><string>--supervise</string>
  </array>
  <key>RunAtLoad</key> <true/>
  <key>KeepAlive</key> <true/>
</dict>

osaurus stop​

Stop the running Osaurus server.

osaurus stop

osaurus status​

Check whether the server is running.

osaurus status

Example output:

running (port 1337)

Prints stopped when the server isn't running.

osaurus doctor​

Read-only diagnostics for the installation and server: CLI/app version skew, duplicate app bundles, server startup, and model storage.

osaurus doctor [--port N] [--json] [--redact] [--verify-signatures]
OptionDescription
--portProbe a specific port instead of the configured one
--jsonMachine-readable report
--redactStrip usernames/paths for a shareable report — use this when attaching output to a bug report
--verify-signaturesAlso check code signature and notarization of every discovered app bundle (explicit because it can be slow with many copies installed)

The report ends with a diagnosis and a concrete next step. Exit code is 0 when the install is usable (healthy, or merely not running) and 1 otherwise.

osaurus ui​

Open the Osaurus menu-bar popover.

osaurus ui

Launches the app if not already running and opens its menu-bar popover (not a full app window).

osaurus list​

List all downloaded models.

osaurus list

Example output:

gemma-4-e2b-it-4bit
gemma-4-26b-a4b-it-jang_4m
qwen3.6-35b-a3b-jangtq2

One model ID per line. Use osaurus show <model> for size and metadata.

osaurus show​

Show metadata for a specific model.

osaurus show <model>

Example:

osaurus show gemma-4-e2b-it-4bit

Example output:

Model: gemma-4-e2b-it-4bit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Architecture:   Gemma4ForCausalLM
Parameters:     2B
Quantization:   4-bit
Context Length: 131072
Size:           1.5 GB
Path:           ~/MLXModels/gemma-4-e2b-it-4bit
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Useful for inspecting architecture, parameter count, quantization level, and context window size.

osaurus pull​

Download an MLX model from Hugging Face without opening the app.

osaurus pull <model_id>

# Example
osaurus pull mlx-community/Llama-3.2-1B-4bit

Downloads the same file set the in-app downloader uses (config, tokenizer, *.safetensors, …) into your configured models directory (falling back to ~/.osaurus/models/<org>/<name>). Files that are already fully downloaded are skipped, so an interrupted pull resumes where it left off.

osaurus run​

Interactive chat session with a model.

osaurus run <model>

Example:

osaurus run gemma-4-e2b-it-4bit

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

osaurus bench​

Benchmark the running server: time-to-first-token, prefill tok/s, and decode tok/s per prompt size, reported as JSON tagged with hardware info.

osaurus bench [--model <id>] [--prompt-tokens 1024,8192] [--max-tokens 128] [--runs 3] [--json <path>] [--port N]

# Find and persist the best prefill step size for a model
osaurus bench --tune-prefill [--model <id>] [--candidates 512,1024,2048,4096]

Requires a running server (osaurus serve). --tune-prefill measures TTFT at each candidate prefill step size and persists the per-model winner — the optimum is model-architecture-dependent, and the server applies it immediately.

osaurus mcp​

Start MCP stdio transport for connecting MCP clients.

osaurus mcp [--access-key KEY]

Proxies the MCP protocol over stdio to the running Osaurus server, auto-launching it if needed. Local-only servers can rely on loopback trust; if Server → Network exposure is enabled, pass an access key with --access-key or the OSAURUS_MCP_ACCESS_KEY environment variable (also accepted: OSAURUS_ACCESS_KEY, OSAURUS_API_KEY, or a Bearer … value in OSAURUS_MCP_AUTHORIZATION).

Use with MCP clients:

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

osaurus version​

Display the Osaurus version (also --version / -v).

osaurus version

osaurus tools​

Manage plugins and tools.

osaurus tools <subcommand> [options]

tools install​

Install a plugin from the registry, a URL, or a local directory.

# From registry
osaurus tools install osaurus.files

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

tools uninstall​

Remove an installed plugin.

osaurus tools uninstall osaurus.files

tools list​

List all installed plugins.

osaurus tools list

Search for plugins in the registry.

osaurus tools search calendar
osaurus tools search git

tools outdated / upgrade / rollback​

Keep installed plugins current — and step back when an update misbehaves.

# Check for newer registry versions
osaurus tools outdated

# Upgrade installed tools
osaurus tools upgrade

# Roll a tool back to its previous version
osaurus tools rollback osaurus.git

tools verify​

Verify the dylib integrity of installed tools — useful after a suspicious sync or restore.

osaurus tools verify

tools reload​

Ask the running app to rescan installed tools without restarting.

osaurus tools reload

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
  • osaurus-plugin.json (the plugin manifest)
  • Source file template

tools dev​

Run a plugin in development mode with hot reload.

osaurus tools dev com.acme.my-plugin

Watches the plugin directory and reloads the plugin when files change — useful for rapid iteration.

tools package​

Package a plugin for distribution.

cd MyPlugin
osaurus tools package <plugin_id> <version> [dylib_path]

# Example
osaurus tools package com.example.mytool 1.0.0

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

osaurus manifest​

Work with plugin manifests during development.

# Extract the manifest JSON embedded in a built plugin dylib
osaurus manifest extract ./MyPlugin.dylib

# Validate a manifest's structure before packaging
osaurus manifest validate ./osaurus-plugin.json

osaurus bundle​

Load and run an MCP Bundle (.mcpb file) — a packaged MCP server that Osaurus can host directly.

osaurus bundle load ./my-server.mcpb --name "Display Name"

osaurus coord​

Foundation for local multi-instance coordination — directories, JSON feature flags, and file-scoped locks.

osaurus coord init                       # Create coordinator directories and seed state
osaurus coord status [--json]            # Root, initialization, locks, pause/stop state
osaurus coord feature-flags list|get|set # Read or update JSON-backed feature flags
osaurus coord lock list|acquire|release|reap

All subcommands accept --root PATH to work against a non-default coordinator root. Later orchestration subcommands (preflight, heartbeat, lane, promote, …) are registered but not yet supported — they exit with an error in the current foundation slice.

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 gemma-4-e2b-it-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 .

# Or use dev mode for hot reload
osaurus tools dev com.example.mytool

# 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

Related: