Reference

CLI reference

Every command, option, and default for the replicate-agent command-line interface — plus the standalone MCP server executable and the environment variables both of them read.

The CLI is the operational surface of the framework: it serves agents over MCP, runs agents and workflows ad hoc, launches distributed workers, and inspects the local audit log. The package installs two executables. replicate-agent is the full Click-based CLI documented on this page; replicate-mcp-server is a minimal alias that starts the stdio MCP server directly, which is convenient as a one-line command in Claude Desktop or Cursor configuration. Run replicate-agent --version to print the installed version.

replicate-agent serve

Launches the MCP server with one of three transports: stdio (the default, for Claude Desktop and Cursor), sse (HTTP Server-Sent Events for cloud-hosted MCP), or streamable-http (bidirectional HTTP, preferred for MCP 1.x clients). If REPLICATE_API_TOKEN is missing, the server still starts but warns that tool calls will fail. See Serve agents over MCP for client wiring.

replicate-agent serve --transport sse --workflows-file workflows.yaml

✓ Loaded 2 workflow(s) from workflows.yaml
Starting MCP SSE server on http://0.0.0.0:8080

replicate-agent doctor

Runs seven diagnostic checks and prints a pass/fail report: API token presence and format, Python version (3.10+), importability of the nine core dependencies, Replicate API connectivity (a 5-second GET /v1/models probe), writability of ~/.replicate, audit log status, and persisted router state. The API check is skipped (not failed) when no token is set, and a missing audit log or router state counts as a pass — both are normal on first run. doctor always exits 0; it is a diagnostic reporter, not a gatekeeper, so read the output rather than relying on the exit code.

replicate-agent doctor

  ✓ API Token  r8_x...xxxx  (format valid)
  ✓ Python      3.11.9
  ✓ Packages    all core dependencies importable
  ✓ API         Replicate API reachable
  ✓ Config dir  /home/you/.replicate (writable)
  — Audit log   not yet created (normal for first run)
  — Router state  no persisted state (cold start)

  Doctor Report: All 7 checks passed — System is ready to run.

replicate-agent init

Creates a default MCP configuration at ~/.replicate/mcp.yaml (transport stdio, log level INFO, max_concurrency: 8) if it does not already exist, then reports whether an API token is detected. Re-running it never overwrites an existing file.

replicate-agent init
# ✓ Created /home/you/.replicate/mcp.yaml
# ✓ API token detected: r8_x...xxxx

replicate-agent status

Prints the installed version, the masked API token (or a warning if unset), and the number of agents in the server registry. Useful as a quick liveness check after exporting the token.

replicate-agent status

replicate-agent agents

Manage and invoke individual agents. agents list takes no options and prints a table of registered agents with their model path, streaming support, tags, and estimated cost. agents run invokes one agent and streams output; its positional AGENT_ID can be a short name or a full Replicate model path.

replicate-agent agents run llama3_chat --input '{"prompt": "Hello!"}'
replicate-agent agents run my_agent --model meta/llama-3-70b --json
replicate-agent agents run llama3_chat --dry-run --input '{"prompt": "test"}'

replicate-agent workflows

Manage multi-step workflows registered through the SDK. workflows list shows each registered workflow's name, step count, agent chain, and description. workflows run NAME executes a registered workflow step by step, feeding each step's output into the next (with input_map remapping applied), and exits 1 if the workflow is not registered or the token is missing. Workflows come from register_workflow() in your code or a --workflows-file passed to serve.

replicate-agent workflows run research --input '{"query": "MCP protocol"}'
replicate-agent workflows run research --checkpoint-dir ./ckpt --resume-from 2

replicate-agent workers

Manage distributed worker nodes. workers start launches an HTTP worker that exposes POST /execute, GET /health, and GET /metrics; it refuses to start without REPLICATE_API_TOKEN. workers ping URL health-checks a remote worker (for example http://host:7999) and prints its active-task and total-processed counters, exiting 1 if unreachable. Coordinators connect with RemoteWorkerNode plus HttpWorkerTransport — see Scale out with worker nodes.

# On the worker machine
export REPLICATE_API_TOKEN=r8_...
replicate-agent workers start --port 7999 --node-id gpu-node-1

# From the coordinator
replicate-agent workers ping http://gpu-node-1:7999

replicate-agent audit

Inspect the local invocation audit log and cost dashboard. Records accumulate automatically once agents are invoked; every subcommand prints a friendly notice when the log does not exist yet.

replicate-agent audit costs --period today

Cost Dashboard — Today
Model                            Calls   Success   Cost (USD)
meta/meta-llama-3-8b-instruct       42     97.6%      $0.0840
mistral/mixtral-8x7b-instruct        7    100.0%      $0.0210
TOTAL                               49     97.9%      $0.1050

Environment variables

The CLI itself only needs the Replicate token; the other variables configure optional subsystems that the CLI starts for you.

Next steps

• Serve agents over MCP — wire serve into Claude Desktop, Cursor, or a cloud host.
• Python API reference — the classes and defaults behind every command on this page.
• Troubleshooting — what to do when doctor is red or calls start failing.