CLI

The MUD CLI

The MUD CLI is used for building and developing a MUD project.

It comes with

  1. tablegen: code-generation tool that makes it easy to work with Store tables
  2. create: bootstrap a MUD project from one of the template.
  3. dev-contracts: start a local MUD development server, including local Ethereum node and file watchers
  4. deploy: deployer for MUD v2 projects that deploys an app using the World kernel onchain
  5. devnode: a wrapper around Anvil with defaults needed to make MUD work properly in development. We recommend running mud devnode over anvil.
  6. faucet: a interface to the Lattice Testnet faucet. It makes it easy to fund addresses on the testnet

Installation

We don’t recommend installing the CLI globally.

Instead, you should add the CLI as a dev dependency to your project (done automatically if you start from a starter kit using pnpm create mud@canary), and use it with pnpm mud inside your project directory.

Using the CLI

Some commands expect a MUD config in the same folder where the CLI is being executed. This includes tablegen, dev-contracts, and deploy.

create, faucet, and devnode can be executed anywhere.

Commands

tablegen

Generates Store libraries from a mud.config.ts file. See the Store Config and tablegen documentation in the Store section for more details.

# in a folder with a mud.config.ts
pnpm mud tablegen

create

Bootstrap a MUD project from a template. You can specify a template interactively when running the command without arguments, or pass it via --template

The valid templates are:

react: A MUD template with React client side that uses the MUD React hooks

minimal: A minimal template with javascript for the frontend (no framework)

pnpm mud create --template minimal

dev-contracts

Start a local MUD development server.

The tool with start a local Ethereum node in the background, or use a custom node via the provided --rpc argument.

It will run all the necessary codegeneration steps, deploy the MUD contracts to the local node. It will also watch for file changes to the mud.config.ts file and all Solidity source files, and re-run the codegen or deploy steps if necessary. The latest deployment is saved to the worlds.json file, where the client can find it to always connect to the latest local deployment.

The tsgenOutput argument is used to specify the output path for code generated for recs.

When using the MUD templates, the project is laid down as a monorepo with contracts in the packages/contracts folder, and the client in the packages/client. dev-contracts need to be executed in the folder with the MUD config -- packages/contracts -- and point to where the client codegeneration should be saved. In this casem the packages/client/src/mud.

To run the dev server with internal development node:

# in a folder with the mud.config.ts
pnpm mud dev-contracts --tsgenOutput ../client/src/mud

To run the dev server with a custom development node:

# Terminal 1:
anvil --port 8545
 
# Terminal 2:
pnpm mud dev-contracts --tsgenOutput ../client/src/mud --rpc localhost:8545

deploy

Deploy a MUD project with the World framework.

This tool will use the mud.config.ts to detect all systems, tables, modules, and namespaces in the World and will deploy them to the chain specified in your Foundry profile.

When using the deployer, you must set the private key of the deployer using the PRIVATE_KEY environment variable. You can make this easier by using dotenv (opens in a new tab) before running pnpm mud deploy in your deployment script.

To set the profile used by the deployer, either set your FOUNDRY_PROFILE environment variable, or pass --profile <profileName> to the deployer (eg: mud deploy --profile optimism-mainnet).

The RPC used by the deployer will be http://localhost:8545 if no profile is set, otherwise it will be read from the eth_rpc_url configuration field of the Foundry profile.

Example profile:

# foundry.toml
[profile.lattice-testnet]
eth_rpc_url = "https://follower.testnet-chain.linfra.xyz"
[profile.optimism-mainnet]
eth_rpc_url = "https://infura[...]"
# to deploy locally
pnpm mud deploy
# to deploy to the lattice testnet
pnpm mud deploy --profile lattice-testnet
# to deploy to optimism mainnet
pnpm mud deploy --profile optimism-mainnet

devnode

Runs Anvil with a block time of 1s, and no base fee (to make it possible for unfunded account to send transactions).

This command also wipes the Anvil cache. Anvil cache blow-up problems won’t happen to you anymore 🙂

pnpm mud devnode

faucet

Connects to a MUD faucet service to fund an address.

pnpm mud faucet --faucetUrl <faucetService> --address <address>

The default faucet service is the one running on the Lattice testnet.

To fund an address on the testnet, run pnpm mud faucet --address <address>

MODEECS and MUD