> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/products/rome-cli.md).

# Rome CLI + MCP

`rome` carries a builder — human or AI agent — across the whole build-on-Rome lifecycle: grounded chain facts, the right pattern, contract calls, the funding on-ramp, deploy/send, cross-VM diagnosis, and a both-lane works-gate. One capability core, two aligned surfaces — a CLI (`rome <command>`) and an [MCP](https://modelcontextprotocol.io) server (`rome mcp`) — so an agent and a human share one mental model.

## Install

Repo-first (npm publish pending):

```bash
# one-shot, no install:
npx github:rome-protocol/rome-cli facts chain hadrian

# durable install — clone + link:
git clone https://github.com/rome-protocol/rome-cli
cd rome-cli && npm install && npm install -g .
```

A plain `npm install -g github:rome-protocol/rome-cli` does **not** work today — npm prepares the package's git dependencies without their own node\_modules ([rome-cli#25](https://github.com/rome-protocol/rome-cli/issues/25)). Use the npx one-shot or clone + link. Pin a tag (`github:rome-protocol/rome-cli#v0.8.0`) when you need reproducible runs.

## Two layers over one core

**Reads — grounding + diagnosis.** No keys; on both the CLI and the MCP server.

| Command                                                  | What it returns                                                                                             |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `rome facts chain·tokens·contracts·gas·balance·programs` | live chain facts from the registry + RPC — no hallucinated ids, addresses, or selectors                     |
| `rome cookbook patterns·cpi-recipe·errors`               | which example fits your goal · the CPI account-rules agents get wrong · decode a Rome failure → cause + fix |
| `rome call <chain> <addr> <sig> [args]`                  | read a contract (`eth_call`) — multi-value args go comma-separated in one argument: `"0xOwner…,0xSpender…"` |
| `rome doctor <chain>`                                    | preflight — chain live? RPC reachable? program configured? wallet funded?                                   |
| `rome tx <chain> <hash>`                                 | diagnose a tx — EVM receipt + the Solana settlement tx(s) + a Via link (Rome has no `debug_trace*`)         |
| `rome preset foundry\|hardhat <chain>`                   | a ready Rome network config for your toolchain + the quirks                                                 |

**Actions — sign on-chain.** CLI-only, key from the environment, **never** on MCP.

| Command                                                                    | What it does                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rome deploy <chain> <artifact>`                                           | deploy a compiled contract, handling Rome's gas quirks                                                                                                                                                                                                                           |
| `rome send <chain> <addr> <sig>`                                           | write to a contract via the correct Rome write path                                                                                                                                                                                                                              |
| `rome fund <chain> --from <src> --amount <usdc>`                           | bridge USDC → Rome gas (CCTP) — the "from home" on-ramp                                                                                                                                                                                                                          |
| `rome bridge <chain> --from <src> --amount <usdc> [--intent gas\|wrapper]` | bridge USDC **in** as gas or wUSDC                                                                                                                                                                                                                                               |
| `rome bridge <chain> --to <dest> --amount <usdc>`                          | bridge wUSDC **out** — burn on Rome; you claim on the destination (Rome sponsors inbound, not the outbound claim)                                                                                                                                                                |
| `rome activate <chain>`                                                    | one-time PDA funding required before the **first bridge out** (inbound is frictionless — needs none)                                                                                                                                                                             |
| `rome verify <chain> [--path …]`                                           | the **path-aware works-gate**, one per way in: `solidity` — the same contract answers on the EVM lane *and* the Solana lane · `solana-program` — an EVM-lane call drives your Solana program via CPI · `from-home` — bridge in → act on Rome → bridge out, the round trip proven |

## Wire it into an AI agent (MCP)

You don't run or host anything — your MCP client launches `rome mcp` (a stdio server) on demand. Register it once:

```json
{ "mcpServers": { "rome": { "command": "npx", "args": ["-y", "github:rome-protocol/rome-cli", "mcp"] } } }
```

(With the clone + link install, `{ "command": "rome", "args": ["mcp"] }` works too — the npx form just needs no prior install.)

The agent then calls tools like `facts_chain`, `cookbook_cpi_recipe`, `doctor`, `tx`, and `preset` — grounded on the live registry + RPC, so it stops guessing addresses and selectors. The MCP surface is **read-only and holds no keys** — safe to wire into any agent; it can never sign or move funds. The signing actions stay on the CLI, with the key supplied through the environment.

## The agent grounding loop

1. `rome cookbook patterns <what I'm building>` → which example repo + architecture
2. `rome facts chain <chain>` → RPC, program id, gas token (no hardcoding)
3. …write code against those exact values…
4. `rome verify <chain> --path <your way in>` → prove it works, whichever path you came by

## Learn more

* Repo + full guides: [`rome-protocol/rome-cli`](https://github.com/rome-protocol/rome-cli)
* [Ecosystem & repos](/getting-started/ecosystem.md) · [Build a dual-lane app](/developer-guides/dual-lane-app.md) · [From home: reach Rome from another chain](/developer-guides/from-home.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rome.builders/products/rome-cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.