Skip to content

Commit 6306e2c

Browse files
marc0olomarc0olo
committed
docs: add comprehensive CLI reference to README
1 parent c93143f commit 6306e2c

File tree

1 file changed

+134
-3
lines changed

1 file changed

+134
-3
lines changed

‎README.md‎

Lines changed: 134 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,141 @@
11
# icp-cli-network-launcher
22

3-
This is a simple CLI interface for `pocket-ic`, tailored to the needs of `icp-cli`. It exposes just enough features via CLI flags to support diverse use-cases, but not so much complexity that future features will require any breaking changes.
3+
Launches a local ICP test network powered by [PocketIC](https://github.com/dfinity/pocketic). Designed as the network backend for [`icp-cli`](https://github.com/dfinity/icp-cli), but can also be used standalone.
44

5-
The CLI interface should be stable across releases of `pocket-ic`, and the primary way `pocket-ic` is installed for use with `icp-cli` is by installing `icp-cli-network-launcher`. The downloadable package contains both the launcher and the `pocket-ic` binary it supports.
5+
```sh
6+
# Start a local network with default settings (application + NNS subnets)
7+
icp-cli-network-launcher --gateway-port=4943
8+
9+
# Start with Bitcoin integration (implicitly enables Internet Identity)
10+
icp-cli-network-launcher --gateway-port=4943 --bitcoind-addr=127.0.0.1:18444
11+
```
12+
13+
The CLI interface is stable across PocketIC releases. The downloadable package contains both the launcher and the PocketIC binary it supports. One launcher version is tied to one PocketIC version — if the PocketIC version is a published release, the launcher version matches (e.g. `10.0.0`); if it's a git hash, it's added as a tag (e.g. `10.0.0+97ad9167`). The launcher expects the `pocket-ic` binary in the same directory.
14+
15+
## CLI Reference
16+
17+
### Flags
18+
19+
| Flag | Type | Description |
20+
|------|------|-------------|
21+
| `--gateway-port` | integer | Port for the HTTP gateway (ICP API). Random if not set. |
22+
| `--config-port` | integer | Port for the PocketIC admin interface. Random if not set. |
23+
| `--bind` | IP address | Network interface to bind the PocketIC server on. |
24+
| `--state-dir` | path | Directory to persist PocketIC state across restarts. Ephemeral if not set. |
25+
| `--artificial-delay-ms` | integer | Artificial delay for update call execution (ms). |
26+
| `--subnet` | enum | Subnet to add. Can be specified multiple times. See [Subnet Configuration](#subnet-configuration). |
27+
| `--bitcoind-addr` | host:port | Bitcoin P2P node address. Can be specified multiple times. See [Bitcoin/Dogecoin](#bitcoin-and-dogecoin-integration). |
28+
| `--dogecoind-addr` | host:port | Dogecoin P2P node address. Can be specified multiple times. See [Bitcoin/Dogecoin](#bitcoin-and-dogecoin-integration). |
29+
| `--ii` | flag | Enable Internet Identity. See [Internet Identity](#internet-identity). |
30+
| `--nns` | flag | Enable NNS and SNS. See [NNS](#nns). |
31+
| `--interface-version` | semver | Expected CLI interface version. Also read from `ICP_CLI_NETWORK_LAUNCHER_INTERFACE_VERSION` env var. Used by automated setups. |
32+
| `--status-dir` | path | Directory to write the [status file](#status-file) to. Used by automated setups. |
33+
| `--verbose` | flag | Enable verbose logging from PocketIC. |
34+
35+
### Subnet Configuration
36+
37+
The `--subnet` flag controls which subnets the local network includes. Available types: `application`, `system`, `verified-application`, `bitcoin`, `fiduciary`, `nns`, `sns`.
38+
39+
**Default behavior:**
40+
- With no `--subnet` flags: one **application** subnet is created.
41+
- With any `--subnet` flag: the default application subnet is **not** created. Only explicitly specified subnets are added.
42+
- An **NNS** subnet is **always** created regardless of flags (it is required for system operations).
43+
44+
**Examples:**
45+
46+
```sh
47+
# Default: application + NNS
48+
icp-cli-network-launcher
49+
50+
# Two application subnets + NNS (for cross-subnet testing)
51+
icp-cli-network-launcher --subnet=application --subnet=application
52+
53+
# System + application + NNS
54+
icp-cli-network-launcher --subnet=system --subnet=application
55+
56+
# Only system + NNS (no application subnet!)
57+
icp-cli-network-launcher --subnet=system
58+
```
59+
60+
### Internet Identity
61+
62+
The `--ii` flag creates an II subnet and installs the Internet Identity canister.
63+
64+
The II subnet and canister are also **implicitly enabled** when any of the following are used:
65+
- `--nns`
66+
- `--bitcoind-addr`
67+
- `--dogecoind-addr`
68+
69+
This is because the II subnet provides threshold signature keys (tECDSA/tSchnorr) that are required for Bitcoin and Dogecoin signing operations, and by NNS/SNS governance. Using `--ii` explicitly alongside these flags is valid but redundant.
70+
71+
### NNS
72+
73+
The `--nns` flag installs the NNS (Network Nervous System) and SNS (Service Nervous System). It has the following effects:
74+
75+
- Creates an **SNS** subnet
76+
- Creates an **II** subnet (implies `--ii`)
77+
- Enables NNS governance, NNS UI, SNS, and canister migration features
78+
79+
### Bitcoin and Dogecoin Integration
80+
81+
The `--bitcoind-addr` and `--dogecoind-addr` flags connect the network to external Bitcoin or Dogecoin nodes for chain integration testing.
82+
83+
**Implicit effects:**
84+
- A **bitcoin** subnet is automatically created (shared by both Bitcoin and Dogecoin)
85+
- An **II** subnet is automatically created (provides threshold signing keys)
86+
- The respective chain feature (bitcoin or dogecoin) is enabled
87+
88+
**Address format:** `host:port` — this is the P2P address of the node, not the RPC address.
89+
90+
**Examples:**
91+
92+
```sh
93+
# Connect to a local Bitcoin node
94+
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444
95+
96+
# Connect to both Bitcoin and Dogecoin nodes
97+
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444 --dogecoind-addr=127.0.0.1:22556
98+
99+
# Multiple Bitcoin nodes
100+
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444 --bitcoind-addr=192.168.1.5:18444
101+
```
102+
103+
### Interaction Summary
104+
105+
The following table summarizes the subnets created for common configurations. An NNS subnet is always present.
106+
107+
| Configuration | Subnets created |
108+
|--------------|----------------|
109+
| *(no flags)* | application, NNS |
110+
| `--ii` | application, NNS, II |
111+
| `--nns` | application, NNS, II, SNS |
112+
| `--bitcoind-addr=...` | application, NNS, bitcoin, II |
113+
| `--dogecoind-addr=...` | application, NNS, bitcoin, II |
114+
| `--subnet=system` | system, NNS |
115+
| `--subnet=system --bitcoind-addr=...` | system, NNS, bitcoin, II |
116+
| `--nns --subnet=system` | system, NNS, II, SNS |
117+
118+
**Key points:**
119+
- Specifying any `--subnet` flag replaces the default application subnet. Add `--subnet=application` explicitly if you still need it.
120+
- `--bitcoind-addr` and `--dogecoind-addr` always add a bitcoin subnet and an II subnet, regardless of `--subnet` flags.
121+
- `--nns` always adds an SNS subnet and an II subnet, regardless of `--subnet` flags.
122+
123+
### Status File
124+
125+
When `--status-dir` is provided, the launcher writes a JSON status file (`status.json`) to the specified directory once the network is ready. This is used by `icp-cli` and other automated setups to discover the running network.
126+
127+
| Field | Type | Description |
128+
|-------|------|-------------|
129+
| `v` | string | Status file format version. Currently `"1"`. |
130+
| `gateway_port` | number | Port where the HTTP gateway (ICP API) is listening. |
131+
| `root_key` | string | Hex-encoded root key of the network. |
132+
| `config_port` | number | Port of the PocketIC admin interface. |
133+
| `instance_id` | number | PocketIC instance ID. |
134+
| `default_effective_canister_id` | string | Default effective canister ID for provisional canister creation calls. |
135+
136+
### Shutdown
6137

7-
One version of the launcher is tied to one version of `pocket-ic`. If the `pocket-ic` version is a published version, then the launcher version will match, e.g. `10.0.0`. If the `pocket-ic` version is a git hash of the dfinity/ic repo, it is added as a tag after the most recent published version, e.g. `10.0.0+97ad9167`. The launcher expects to be in the same folder as its corresponding version of `pocket-ic`.
138+
The launcher handles `SIGINT` (Ctrl+C) and `SIGTERM` for graceful shutdown. It stops the PocketIC server and waits for it to exit before terminating.
8139

9140
## Development
10141

0 commit comments

Comments
 (0)