Skip to content

Commit 466831d

Browse files
4HM3DMD4HM3DMD
authored
Added command reference
docs: add a full command reference
2 parents 72c9ab5 + fd4f7cd commit 466831d

2 files changed

Lines changed: 108 additions & 0 deletions

File tree

‎SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
* [BPoS Setup](docs/bpos-setup.md)
1212
* [node.sh](docs/what-is-node.sh.md)
1313
* [Quick Setup](docs/quick-setup.md)
14+
* [Command Reference](docs/commands.md)
1415
* [Step-by-Step Setup](docs/archives/step-by-step-setup.md)
1516
* [Checking Environments](docs/archives/step-by-step-setup/checking-environments.md)
1617
* [Installing node.sh](docs/archives/step-by-step-setup/installing-node.sh.md)

‎docs/commands.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Command Reference
2+
3+
`node.sh` is the single entry point for every operation on the node. Commands come in two forms:
4+
5+
```bash
6+
node.sh <command> # acts on the whole node (the active profile)
7+
node.sh <chain> <command> # acts on one chain
8+
```
9+
10+
Run `node.sh` with no arguments (or `node.sh help`) for the grouped, in-terminal version of this reference.
11+
12+
## Daily operations
13+
14+
The day-to-day commands are built to be easy to read. A single `summary` view shows each chain with its state, height, peers, and sync in one table. `health` returns a proper success or failure exit code, so it drops straight into alerts and monitoring. Logs are easier to follow, and status data can be emitted as JSON for dashboards.
15+
16+
| Command | What it does |
17+
|---|---|
18+
| `node.sh start` | Start every chain in the active profile (background). |
19+
| `node.sh stop` | Stop every chain in the profile (bounded wait, then a clean SIGKILL if needed). |
20+
| `node.sh summary` | One row per chain: state, height, peers, and sync. The at-a-glance fleet view. |
21+
| `node.sh status` | The full labeled status block for each chain in the profile. Add `--verbose` for every chain and field. |
22+
| `node.sh health` | One-line verdict. Exit code is `0` when everything is healthy, non-zero otherwise, so it is cron- and alert-friendly. |
23+
| `node.sh logs [chain] [-f]` | Tail the most recent log (defaults to the main chain). `-f` follows it live. |
24+
| `node.sh restart` | Restart the profile's chains one at a time. ELA is skipped unless you pass `--force` (restarting it would interrupt council consensus). |
25+
| `node.sh version` | Tool version plus each chain's binary version. |
26+
27+
### Machine output for dashboards
28+
29+
| Command | What it does |
30+
|---|---|
31+
| `node.sh summary --json` | The fleet table as JSON, one object per chain. |
32+
| `node.sh <chain> status --json` | A single chain's status as JSON. |
33+
| `node.sh ... --no-color` | Disable ANSI color (also honored via the `NO_COLOR` environment variable and on non-TTY output). |
34+
35+
## First-time setup
36+
37+
Install the dependencies first, then initialize. Opening ports, swap, and autostart are separate, explicit steps so nothing surprising happens on a fresh box.
38+
39+
```bash
40+
sudo apt-get install -y jq lsof apache2-utils curl openssl
41+
```
42+
43+
| Command | What it does |
44+
|---|---|
45+
| `node.sh init` | Initialize the node: download the chain binaries and create the keystores. Resumable - an interrupted run adopts an intact keystore instead of starting over. |
46+
| `node.sh setup` | The same initialization as `init`, followed by a guided "next steps" summary. |
47+
| `node.sh profile [set <name>]` | Show or set what this node runs: `mainchain` (main chain only) or `full` (the full cross-chain stack). |
48+
| `node.sh swap` | Optional. Add 16 GB of swap headroom for the initial sync (recovers an inactive swapfile if one exists). |
49+
| `node.sh firewall` | Open only the peer and consensus ports. Detects your SSH port and asks before enabling `ufw`, so it never locks you out. RPC stays on loopback. |
50+
| `node.sh set_cron` | Enable autostart on reboot and scheduled log compression. |
51+
| `node.sh harden` | Close public access to the RPC, WebSocket, oracle, and arbiter RPC ports, and report any chain that still needs a restart to rebind. Restarts nothing. |
52+
| `node.sh reward [set 0x<addr>]` | Show or set a cold mining reward address for the EVM side chains in one step. |
53+
| `node.sh monitor <url>` | Enroll the node with a read-only monitor over an outbound push. No RPC password and no open port. Run `node.sh monitor` to check it, `node.sh monitor off` to stop. |
54+
55+
## Managing the node
56+
57+
| Command | What it does |
58+
|---|---|
59+
| `node.sh update` | Update the chain binaries in the active profile. |
60+
| `node.sh migrate [--dry-run \| --apply]` | Move an existing node onto this tool. `--dry-run` is read-only and changes nothing; the default run preserves the keystore, chain data, and config and writes rollback snapshots; `--apply` rebinds stale side chains to `127.0.0.1` one at a time and never restarts ELA. |
61+
| `node.sh uninstall` | Stop everything, back up the keystore, and remove the installation after a typed confirmation. |
62+
| `node.sh update_script` | Update `node.sh` itself: download from master, verify the published checksum, syntax-check it, and re-apply hardening. Reports "already up to date" when nothing changed. |
63+
| `node.sh set_path` | Add `node.sh` to the shell `PATH`. |
64+
65+
## Per-chain commands
66+
67+
Target a single chain with `node.sh <chain> <command>`:
68+
69+
```bash
70+
node.sh esc status # status of the ESC side chain only
71+
node.sh ela logs -f # follow the main chain log
72+
node.sh eid restart # restart EID
73+
```
74+
75+
Every chain accepts:
76+
77+
```
78+
start stop restart status [--json] health logs [-f]
79+
client rpc init update version
80+
```
81+
82+
Run `node.sh <chain>` with no command to print that chain's full command list.
83+
84+
**Chains:** `ela` (main chain), the EVM side chains `esc`, `eid`, `pg`, their cross-chain oracles (`esc-oracle`, `eid-oracle`, `pg-oracle`), and the `arbiter`. Which chains are active depends on the profile (`mainchain` or `full`).
85+
86+
### Main-chain governance (ELA)
87+
88+
The main chain adds the BPoS and CRC governance commands, for example `node.sh ela register-bpos`, `vote-bpos`, `stake-bpos`, `register-crc`. See the [BPoS Setup](bpos-setup.md) and [CRC Setup](crc-setup.md) guides for the full workflows.
89+
90+
## Aliases and flags
91+
92+
| | |
93+
|---|---|
94+
| Verb aliases | `up` = `start`, `down` = `stop`, `ps` = `summary`, `rpc` = `jsonrpc`. Kebab-case is accepted (`register-bpos` = `register_bpos`). |
95+
| `--profile <mainchain\|full>` | Override the active profile for a single command. |
96+
| `--no-color` / `NO_COLOR` | Plain output with no ANSI color. |
97+
| `--verbose` / `-v` (on `status`) | Show every chain and every field. |
98+
| `--force` (on `restart`) | Include ELA in a restart (otherwise skipped to protect consensus). |
99+
100+
## Maintenance
101+
102+
| Command | What it does |
103+
|---|---|
104+
| `node.sh update_script` | Self-update the script (checksum-verified, see above). |
105+
| `node.sh set_path` | Install `node.sh` onto the shell `PATH`. |
106+
107+
For the security defaults and the full port table, see [Security](../SECURITY.md). For installing from scratch, see [Quick Setup](quick-setup.md).

0 commit comments

Comments
 (0)