cmu network

cmu network manages the RPC networks saved on the machine and controls which one the active wallet session points at.

Usage

bash

cmu network <subcommand> [options]

Subcommands

Subcommand	Description
`cmu network save <url> --name <n>`	Save a new network or update an existing one. `--symbol` sets its coin symbol.
`cmu network list`	List all saved networks.
`cmu network use <name>`	Switch the active network.
`cmu network delete <name>`	Delete a saved network.
`cmu network info`	Show the active network.
`cmu network ping [name]`	Ping a network to check connectivity and latency.

Running cmu network with no subcommand lists the saved networks, exactly as cmu network list does.

TIP

-v, --verbose is a global flag declared on cmu itself, so it works anywhere on the line — cmu -v network list, cmu network -v list and cmu network list -v are equivalent.

Which Network a Command Uses

There are two independent ways a command picks its network. The saved networks managed on this page, with the active one recorded in the session file in effect (the folder's .cmu-session, else ~/.cmu-session), are one. The networks and defaultNetwork of the project's cmu.config.ts/js are the other.

Command	Network comes from	`-n` names
`cmu wallet balance`, `cmu wallet info`, `cmu wallet transfer`	The session's `activeNetwork`	—
`cmu mine start`, `cmu mine stop`, `cmu mine status`	The session's `activeNetwork`	—
`cmu network info`, `cmu network ping`	The session's `activeNetwork`, or the name passed to `ping`	—
`cmu node connect`	`-n`, else the session's `activeNetwork`, else `local`	A saved network
`cmu deploy`, `cmu console`, `cmu explorer`	`-n`, else `defaultNetwork` in `cmu.config.ts/js`	A network in `cmu.config.ts/js`

cmu network use therefore has no effect on cmu deploy, cmu console or cmu explorer, and defaultNetwork has no effect on cmu wallet or cmu mine. The coin symbol that amounts are labelled with comes from the same place as the network. To deploy to a server and mine on it, point both at it: set defaultNetwork (or pass -n) in the config, and run cmu network use <name>.

The same -n flag means different things. With a saved network called geth that cmu.config.ts does not define, cmu node connect -n geth connects, while cmu deploy -n geth fails:

bash

error: deploy failed
network 'geth' is not defined in cmu.config.js.
hint: add it under `networks`, or pick one that is already defined.

Outside a project, with no cmu.config.ts/js, cmu deploy, cmu console and cmu explorer target http://127.0.0.1:8585 (chain ID 1912) directly. They do not read the saved local entry, so re-saving local with another URL does not move them.

cmu network save

Saves a network to the local network store, or overwrites the RPC endpoint of an existing entry with the same name.

Usage

bash

cmu network save http://10.64.24.101:8585 --name mainnet

Options

Flag	Description
`-n, --name <name>`	Name to save the network under. Required.
`--symbol <symbol>`	Coin symbol that amounts on this network are labelled with: 1-11 letters or digits, stored as typed. No short form. Since 1.7.0. See Coin Symbol.

Behavior

--name is required. Omitting it exits with:

bash

error: network save failed
--name is required.
hint: e.g. `cmu network save http://127.0.0.1:8585 --name local`.

The endpoint is validated before anything is written. Only http: and https: are accepted, because every provider in the CLI is an ethers JsonRpcProvider and cannot speak another scheme:

bash

error: network save failed
invalid RPC endpoint 'ftp://node.example'.
hint: pass a full http:// or https:// URL, e.g. `cmu network save http://127.0.0.1:8585 --name local`.

Endpoint	Result
`http://127.0.0.1:8585`	Accepted.
`https://user:pw@node.example/rpc?k=1`	Accepted, credentials and query included. Printed masked; see Credentials in RPC URLs.
`localhost:8545`	Rejected — no scheme.
`http://`	Rejected — no host.
`http://bad host`	Rejected.
`ftp://node.example`	Rejected — only `http:` and `https:`.

The endpoint is not contacted when saving, so an unreachable node is accepted. The name is not validated either: any string works, including spaces and /.

Saving does not change the active network. Use cmu network use to switch to it afterwards.

Output

bash

Saved network 'mainnet' (http://10.64.24.101:8585)

Since 1.7.0 the line also names the coin symbol: the one passed with --symbol, or the one an update kept. A network without a symbol prints the line above, unchanged.

bash

Saved network 'kampus' (http://127.0.0.1:8585, symbol tCMU)
Saved network 'local' (http://127.0.0.1:8585, symbol CMU kept)

Coin Symbol

Since 1.7.0, each saved network can carry a coin symbol. cmu wallet balance, cmu wallet transfer, cmu mine status, the cmu mine start --watch status line and cmu network info label amounts with the symbol of the session's active network. Before 1.7.0 every amount said ETH.

bash

cmu network save http://127.0.0.1:8585 --name kampus --symbol tCMU

Saved network	Amounts are labelled
Saved with `--symbol`	With that symbol, e.g. `100.0 CMU`.
Saved without one, or saved before 1.7.0	`ETH`, as before.
`local` in a `~/.cmu-networks.json` created by 1.7.0	`CMU` — the file is seeded with it.

The symbol is only a label. Amounts are still read and written with 18 decimals, and wei values are unchanged.

The symbol is stored exactly as typed, so tCMU stays tCMU and cmu is not uppercased.
Saving an existing network again without --symbol keeps its symbol, and the output says kept.
A symbol cannot be removed with --symbol. Edit ~/.cmu-networks.json and delete the symbol key to go back to ETH.

--symbol is checked before anything is written. Anything other than 1-11 ASCII letters or digits is refused, and the file is left untouched:

bash

error: network save failed
invalid symbol 'C-M' - expected 1-11 letters or digits, e.g. CMU.
hint: e.g. `cmu network save http://127.0.0.1:8585 --name bad --symbol CMU`.

Labelling an existing local network CMU

1.7.0 does not migrate existing files. A local entry saved by an older cmu keeps showing ETH until you give it a symbol:

bash

cmu network save http://127.0.0.1:8585 --name local --symbol CMU

bash

Saved network 'local' (http://127.0.0.1:8585, symbol CMU)

Use the URL already saved for local (see cmu network list), since save also overwrites the endpoint.

cmu deploy, cmu console and cmu explorer do not read this file; they take the network, and its symbol, from cmu.config.ts/js. See Coin Symbol in cmu explorer.

cmu network list

Prints every saved network and marks the active one with [*].

Usage

bash

cmu network
cmu network list

Output

bash


Saved networks
==========================================================================
| Active | Name                 | RPC endpoint
--------------------------------------------------------------------------
| [*]    | local                | http://127.0.0.1:8585
|        | mainnet              | http://10.64.24.101:8585
==========================================================================

INFO

If no session file exists, the listing falls back to marking local as active. The list itself is still printed in full.

cmu network use

Switches the active network recorded in the current wallet session.

Usage

bash

cmu network use mainnet

Requirements

An active wallet session must exist. Without one the command exits with:

bash

error: network use failed
no active session.
hint: run `cmu wallet use <name>` first, or `cmu wallet create --save <name>` and then `cmu wallet use <name>`.

The target network must already be saved. An unknown name exits with:

bash

error: network use failed
network 'mainnet' is not saved.
hint: list saved networks with `cmu network list`, or add one with `cmu network save <url> --name <name>`.

Behavior

The command rewrites the activeNetwork field of the session file in effect and leaves the rest of the session untouched: the folder's .cmu-session if it has one, otherwise ~/.cmu-session. Every command that reads the session's network — see Which Network a Command Uses — uses the new selection immediately.

Changing ~/.cmu-session changes the network of every folder without its own .cmu-session. Changing a folder's .cmu-session changes only that folder.

Because the selection lives in the session, a session must be in effect before a network can be picked: run cmu wallet use <name> first, then cmu network use <network>. The name is checked before the session, so an unknown name is reported even where there is no session.

Output

Since 1.7.4 the line names the file it wrote, ~/.cmu-session or ./.cmu-session:

bash

Active network is now mainnet (~/.cmu-session)

INFO

The selection survives a later cmu wallet use. It carries the session's active network over, and only falls back to local if the selected network has since been deleted.

cmu network delete

Removes a network from the saved network store.

Usage

bash

cmu network delete staging

Behavior

local can never be deleted, with or without a session, since every fallback points at it. Since 1.7.2:

bash

error: network delete failed
network 'local' is the built-in fallback and cannot be deleted.
hint: point it at another endpoint with `cmu network save <url> --name local`.

The command also refuses to delete a network that a session it can find has selected. Since 1.7.4 it checks two files: the session file in effect, and ~/.cmu-session, which every folder without its own .cmu-session uses. The message names each file that has the network selected, with one hint per file:

bash

error: network delete failed
network 'staging' is currently active in ./.cmu-session and ~/.cmu-session and cannot be deleted.
hint: switch ./.cmu-session away first with `cmu network use <name>`.
hint: switch ~/.cmu-session away first with `cmu network use <name>` in a folder without its own .cmu-session, such as your home folder.

When only one file has it selected, only that file is named. cmu network use writes the session file in effect, which is why the ~/.cmu-session hint says to run it in a folder without its own .cmu-session; run where ~/.cmu-session is the file in effect, that hint has no folder part. In 1.7.3 and older only the session in the current directory was checked, and the message was network 'staging' is currently active and cannot be deleted.

Switch to a different network with cmu network use before deleting. Deleting a name that was never saved exits with network '<name>' is not saved.

A .cmu-session in another folder is not checked, since cmu keeps no list of folders, and the output says so after a delete. The saved list is shared by every folder on the machine, so deleting a network can remove the network another folder's .cmu-session still points at. Commands in that folder then fail until it picks another one:

Command in the other folder	Message
`cmu network info`, `cmu network ping`	`active network '<name>' is no longer saved.`
`cmu wallet info`, `cmu wallet balance`, `cmu mine`	`network '<name>' is not saved.`

INFO

In 1.7.1 and older, cmu network delete local succeeded in a directory without a session, leaving every fallback to local pointing at nothing. If local is missing from ~/.cmu-networks.json for that reason, restore it with cmu network save http://127.0.0.1:8585 --name local. cmu wallet use warns about a missing local each time it falls back to it; see Active Network.

Output

bash

Deleted network 'staging'
hint: another folder's .cmu-session still on 'staging' is not checked: run `cmu network use <name>` there.

The hint is printed after every delete since 1.7.4.

cmu network info

Displays the active network name and RPC endpoint resolved from the current session.

Usage

bash

cmu network info

Requirements

An active wallet session with a selected network must exist. Each way of not having one is reported separately:

Condition	Message
No session file in effect	`no active session.`
Session has no `activeNetwork`	`no active network in the session.`
Selected network no longer saved	`active network '<name>' is no longer saved.`

Output

bash

--- Active network ---
Network      : local
RPC endpoint : http://127.0.0.1:8585
Symbol       : CMU
----------------------

The Symbol line is new in 1.7.0. It shows the network's coin symbol, or ETH for a network saved without one.

cmu network ping

Measures round-trip latency to a network by requesting its current block number.

Usage

bash

cmu network ping
cmu network ping mainnet

Arguments

Argument	Description
`[name]`	Optional. The saved network to ping. Defaults to the session's active network when omitted.

Behavior

When [name] is supplied, the network is looked up in the saved network store and no session is required. When it is omitted, the command reads activeNetwork from the session file in effect and therefore requires an active session.

The endpoint is first checked the same way as cmu deploy --ping: it must report its chain ID within 3 seconds. Since 1.7.2. Latency is then measured as the elapsed time around a single eth_blockNumber call, so it reflects RPC round-trip time rather than block production speed.

Output

bash

Pinging http://127.0.0.1:8585...
Connected to 'local' (chain ID 1912).
--- Ping result ---
Network      : local
Block number : 1482
Latency      : 12ms
-------------------

The command exits with code 1 if the endpoint is unreachable:

bash

Pinging http://127.0.0.1:9...

error: network ping failed
RPC endpoint http://127.0.0.1:9 is unreachable (timed out after 3000ms).
hint: check the node is running and the endpoint is correct - `cmu network list`.

The message is the same whether the connection is refused at once or the endpoint does not answer at all; only the latter actually waits the 3 seconds. In 1.7.1 and older the command printed ethers' retry notice and its raw error instead.

Deprecated Flags

Before the subcommands existed, cmu network took its actions as flags on the root command. Those flags still work, print a deprecation notice, and run the same handler the subcommand would.

Deprecated flag	Replacement
`-s, --save <url>`	`cmu network save <url> --name <name>`
`-u, --use <name>`	`cmu network use <name>`
`-l, --list`	`cmu network list`
`-D, --delete <name>`	`cmu network delete <name>`

Each prints, before doing the work:

bash

warning: `cmu network --save` is deprecated
hint: use `cmu network save <url> --name <name>` instead.

DEPRECATED SINCE 1.3.6

No removal release is scheduled. Until 1.7.1 the warning ended with and will be removed in 2.0.0; since 1.7.2 it names no release. The flags may still be removed in a later major version, so migrate scripts and CI pipelines to the subcommand form.

Only one action runs per invocation. The flags are evaluated in a fixed order and the command returns after the first match:

--save
--delete
--use
--list

WARNING

-n, --name is not deprecated — it is how cmu network save receives its name, and it is declared on the root command as well as on the subcommand.

A combination that matches none of the four branches falls through to the network listing. In particular cmu network --name prod, which is what a forgotten --save looks like, prints the saved-network table and exits 0 without saving anything. Check the output for a Saved network '<name>' line before assuming a save succeeded, or use the subcommand form, which reports the missing name as an error.

INFO

The delete flag is a capital -D. A lowercase -d is not registered and is rejected as an unknown option.

Network Storage

Saved networks are kept in .cmu-networks.json as an array of entries:

Field	Description
`name`	The identifier used by `use` and `delete`.
`rpcUrl`	The JSON-RPC endpoint of the network.
`symbol`	Optional. The coin symbol amounts are labelled with; `ETH` when absent. Since 1.7.0.

On first read the file is seeded with a single entry, local pointing at http://127.0.0.1:8585. Since 1.7.0 the seeded entry has the symbol CMU. It is only seeded when the file does not exist, so a file created by an older cmu keeps its local without a symbol, and a local removed by hand, or deleted by 1.7.1 or older, is not re-created. cmu network delete local is refused since 1.7.2.

json

[
  {
    "name": "local",
    "rpcUrl": "http://127.0.0.1:8585",
    "symbol": "CMU"
  }
]

A network saved without --symbol is written with name and rpcUrl only, exactly as before 1.7.0.

A symbol edited by hand into something other than 1-11 letters or digits stops the commands that print amounts, and the error names the command that fixes it:

bash

error: wallet balance failed
network 'local' has an invalid symbol "c m" in ~/.cmu-networks.json - expected 1-11 letters or digits, e.g. CMU.
hint: set it again with `cmu network save http://127.0.0.1:8585 --name local --symbol <SYMBOL>`.

Re-saving that network without --symbol keeps the broken value and says so (symbol "c m" kept), so pass a new --symbol.

Since 1.7.2 the file is written with 0600 permissions, readable only by the owning user, like ~/.cmu-wallets.json and .cmu-session. It is replaced atomically, through a temporary file renamed over it, so an interrupted write leaves the previous file intact. A file that 1.7.1 or older wrote with 0644 is tightened to 0600 the next time anything writes it, including a save that only updates a symbol.

Credentials in RPC URLs

The file stores each rpcUrl exactly as typed. Since 1.7.2, every URL cmu prints — in save, list, info, cmu wallet info, the Pinging and RPC endpoint lines of every command, and error messages including -v output — has its password and every query value replaced by ***:

bash

cmu network save 'https://alice:s3cret@rpc.example.com/v1?apikey=abc&x=1' --name infura

bash

Saved network 'infura' (https://alice:***@rpc.example.com/v1?apikey=***&x=***)

A username on its own is masked as well; with a password, the username is kept. A URL with nothing to mask is printed exactly as typed. A hint that is a command to run again shows <url> instead of a masked URL, since running it with *** would save *** as the password:

bash

hint: e.g. `cmu network save <url> --name infura --symbol CMU`.

WARNING

A key in the URL path is not recognised and is printed in full, such as the project ID in https://mainnet.example.io/v3/<key>. Pass keys as a query parameter or userinfo where the provider allows it, or keep such output out of logs.

INFO

.cmu-networks.json is stored in your home directory, not in the project. The saved network list is therefore shared by every CointMU project on the machine. The active network selection lives in the session file in effect: since 1.7.4 that is ~/.cmu-session, shared by every folder without its own .cmu-session, unless the folder has one.

WARNING

Both .cmu-networks.json and .cmu-session are listed in the .gitignore generated by cmu create. Do not commit either file to version control.

cmu network ​

Usage ​

Subcommands ​

Which Network a Command Uses ​

cmu network save ​

Usage ​

Options ​

Behavior ​

Output ​

Coin Symbol ​

cmu network list ​

Usage ​

Output ​

cmu network use ​

Usage ​

Requirements ​

Behavior ​

Output ​

cmu network delete ​

Usage ​

Behavior ​

Output ​

cmu network info ​

Usage ​

Requirements ​

Output ​

cmu network ping ​

Usage ​

Arguments ​

Behavior ​

Output ​

Deprecated Flags ​

Network Storage ​

Credentials in RPC URLs ​

cmu network

Usage

Subcommands

Which Network a Command Uses

cmu network save

Usage

Options

Behavior

Output

Coin Symbol

cmu network list

Usage

Output

cmu network use

Usage

Requirements

Behavior

Output

cmu network delete

Usage

Behavior

Output

cmu network info

Usage

Requirements

Output

cmu network ping

Usage

Arguments

Behavior

Output

Deprecated Flags

Network Storage

Credentials in RPC URLs