CLI (mrl)

A lightweight command-line tool for running and testing ModelRelay agents, managing resources, and running local agentic tool loops.

Installation

Homebrew (macOS/Linux)

brew install modelrelay/tap/mrl

To upgrade:

brew upgrade mrl

Manual Download

Download the latest release from releases.modelrelay.ai/mrl and add to your PATH.

From Source

go install github.com/modelrelay/mrl@latest

Configuration

Environment Variables

export MODELRELAY_API_KEY=mr_sk_...
export MODELRELAY_PROJECT_ID=...    # UUID (optional default)
export MODELRELAY_API_BASE_URL=...  # optional

Config File

Create ~/.config/mrl/config.toml:

current_profile = "default"

[profiles.default]
api_key = "mr_sk_..."
base_url = "https://api.modelrelay.ai/api/v1"
project_id = "<uuid>"
output = "table" # or "json"

Managing Profiles

# Set values for a profile
mrl config set --profile dev --api-key mr_sk_...

# Switch to a profile
mrl config use dev

# Show current config
mrl config show

Running Agents

Run a Deployed Agent

Run an agent deployed to ModelRelay by its slug:

mrl agent run researcher --input "Analyze Q4 sales"

Test with Mocked Tools

Test agents locally with mocked tool responses:

mrl agent test researcher \
  --input "Analyze Q4 sales" \
  --mock-tools ./mocks.json \
  --trace

JSON Input

For complex inputs, use a JSON file:

mrl agent test researcher \
  --input-file ./inputs.json \
  --output ./trace.json \
  --json

Local Tool Loops

Run agentic loops locally with the model calling tools on your machine.

Basic Loop with Bash

Enable the bash tool (deny-by-default) with allowed command prefixes:

mrl agent loop \
  --model claude-sonnet-4-5 \
  --tool bash \
  --bash-allow "git " \
  --input "List recent commits and summarize them"

With Task Tracking

Include tasks.write for progress tracking:

mrl agent loop \
  --model claude-sonnet-4-5 \
  --tool bash \
  --tool tasks.write \
  --state-ttl-sec 86400 \
  --tasks-output ./tasks.json \
  --input "Audit this repo and track your progress"

Filesystem Tools

Enable local filesystem tools (fs.*):

mrl agent loop \
  --model claude-sonnet-4-5 \
  --tool fs \
  --input "Search for TODOs in this repo"

Tool Manifest

Load tools from a TOML or JSON manifest file. CLI flags override manifest values.

Create tools.toml:

tool_root = "."
tools = ["bash", "tasks.write"]
state_ttl_sec = 86400

[bash]
allow = ["git ", "rg "]
timeout = "15s"
max_output_bytes = 64000

[tasks_write]
output = "tasks.json"
print = true

[fs]
ignore_dirs = ["node_modules", ".git"]
search_timeout = "3s"

[[custom]]
name = "custom.echo"
description = "Echo input as JSON"
command = ["cat"]
schema = { type = "object", properties = { message = { type = "string" } }, required = ["message"] }

Run with:

mrl agent loop --model claude-sonnet-4-5 --tools-file ./tools.toml --input "Audit this repo"

Resource Management

Customers

# List customers
mrl customer list

# Get a customer
mrl customer get <customer_id>

# Create a customer
mrl customer create --external-id user_123 --email user@example.com

Tiers

# List tiers
mrl tier list

# Get a tier
mrl tier get <tier_id>

Usage

# View account usage
mrl usage account

Utility Commands

List Models

# List all models
mrl model list

# Filter by provider and capability
mrl model list --provider openai --capability text_generation

# Include deprecated models
mrl model list --include-deprecated --json

Lint JSON Schemas

Validate JSON schemas for provider compatibility:

# Basic lint
mrl schema lint ./schema.json

# Validate for specific provider
mrl schema lint ./schema.json --provider openai

# Validate tool schema
mrl schema lint ./tool-schema.json --provider openai --tool-schema

Version

mrl version

Output Formats

Table output is the default. Use --json for machine-readable output on any command:

mrl customer list --json
mrl model list --json

Global Flags

Next Steps

• First Request - Make your first API call
• Go SDK - Use the Go SDK for programmatic access
• TypeScript SDK - Use the TypeScript SDK