CLI commands

Complete command reference for the Meerkat CLI (rkat).

rkat is the command-line interface for Meerkat. It lets you run AI agents from your terminal with support for multiple providers, MCP tools, session management, and streaming output.

Common commands

Command	Example	Purpose
run	rkat run "prompt"	Execute an agent with a prompt
resume	rkat resume <ID> "prompt"	Continue a previous session
sessions list	rkat sessions list	List stored sessions
sessions show	rkat sessions show <ID>	View session details
mcp add	rkat mcp add name -- cmd	Add an MCP tool server
mcp list	rkat mcp list	List configured MCP servers
config	rkat config get	Get, set, or patch configuration
rpc	rkat rpc	Start the JSON-RPC stdio server

---

run

Execute an agent with a prompt.

rkat run [OPTIONS] <PROMPT>

PROMPT · string · required

The prompt to execute.

Model selection

--model · string · default: "claude-opus-4-6"

Model to use.

-p, --provider · string

LLM provider: anthropic, openai, or gemini. Auto-detected from the model name if omitted.

Output

--output · string · default: "text"

Output format: text or json.

--stream · boolean · default: "false"

Stream response tokens as they arrive.

Budget and token limits

--max-tokens · integer · default: "4096"

Maximum tokens per turn.

--max-total-tokens · integer

Maximum total tokens for the run. Unlimited by default.

--max-duration · string

Maximum duration (e.g., 5m, 1h30m, 30s). Unlimited by default.

--max-tool-calls · integer

Maximum number of tool calls. Unlimited by default.

Provider parameters (--param)

--param · string

Provider-specific parameter as KEY=VALUE. Can be repeated. See provider parameters for details.

Inter-agent communication flags

--comms-name · string

Agent name for inter-agent communication. Enables comms if set.

--comms-listen-tcp · string

TCP address to listen on (e.g., 0.0.0.0:4200).

--no-comms · boolean

Disable inter-agent communication entirely.

Examples

Basic usage

rkat run "What is the capital of France?"
rkat run --model claude-opus-4-6 "Explain quantum computing"
rkat run --model gpt-5.2 "Write a haiku about Rust"
rkat run --model gemini-3-flash-preview "What are the benefits of async/await?"

---

resume

Resume a previous session with a new prompt.

rkat resume <SESSION_ID> <PROMPT>

SESSION_ID · string · required

Session ID to resume.

PROMPT · string · required

The prompt to continue with.

rkat run "Let's discuss Rust error handling"
# Note the session ID from output
rkat resume 01936f8a-... "What about the ? operator?"

---

sessions

Manage stored sessions.

list

rkat sessions list [--limit N]

$ rkat sessions list
ID                                       MESSAGES     CREATED              UPDATED
--------------------------------------------------------------------------------------------
01936f8a-7b2c-7000-8000-000000000001     8            2025-01-22 14:30     2025-01-22 15:45
01936f8a-7b2c-7000-8000-000000000002     3            2025-01-21 09:15     2025-01-21 09:20

show

rkat sessions show <ID>

Displays all messages in the session with their types (USER, ASSISTANT, SYSTEM, TOOL RESULTS).

delete

rkat sessions delete <SESSION_ID>

---

mcp

Manage MCP (Model Context Protocol) server configuration.

add

rkat mcp add [OPTIONS] <NAME> [-- <COMMAND>...]

Stdio transport

rkat mcp add my-tools -- npx -y @example/mcp-server
rkat mcp add api-tools -e API_KEY=secret123 -- python mcp_server.py
rkat mcp add global-tools --user -- /usr/local/bin/mcp-server

HTTP transport

rkat mcp add remote-tools --url https://mcp.example.com/api
rkat mcp add auth-tools --url https://mcp.example.com/api -H "Authorization:Bearer token123"
rkat mcp add sse-tools -t sse --url https://old.example.com/sse

list

rkat mcp list [--scope user|project] [--json]

get

rkat mcp get [--scope user|project] [--json] <NAME>

remove

rkat mcp remove [--scope user|project] <NAME>

If the server exists in multiple scopes and --scope is not specified, the command will error.

---

rpc

Start the JSON-RPC stdio server for IDE and desktop app integration.

rkat rpc

The server reads/writes newline-delimited JSON-RPC 2.0 on stdin/stdout. Unlike run/resume, it keeps agents alive between turns.

See the RPC reference for the full protocol specification.

---

Examples

MCP tools workflow

1. Set up a filesystem tool

   rkat mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects
   
2. Run with tools available

   rkat run "List all Rust files in the projects directory"
   

Session workflow

1. Start a conversation

   rkat run "I want to learn about Rust iterators"
   
2. Continue the conversation

   rkat resume 01936f8a-... "What about the collect() method?"
   
3. Review and clean up

   rkat sessions show 01936f8a-...
   rkat sessions delete 01936f8a-...
   

Scripting with JSON output

#!/bin/bash
prompts=("What is Rust?" "What is Go?" "What is Python?")

for prompt in "${prompts[@]}"; do
    result=$(rkat run --output json "$prompt")
    text=$(echo "$result" | jq -r '.text')
    tokens=$(echo "$result" | jq -r '.usage.input_tokens + .usage.output_tokens')
    echo "Q: $prompt"
    echo "A: $text"
    echo "Tokens: $tokens"
    echo "---"
done

---

See also

• CLI configuration - environment variables, config files, exit codes
• RPC reference - JSON-RPC stdio server protocol
• Providers - model and provider setup