# Operators & Nodes

## validator

Manage validator registration, committee membership, and reporting.
**Note:** State-modifying subcommands accept [transaction processing arguments](https://docs.soma.org/reference/cli/overview/#transaction-processing-arguments).

### make-validator-info

Generate validator key files and metadata.

```
soma validator make-validator-info <HOST_NAME> [COMMISSION_RATE]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `host_name` | `string` | Yes | Hostname for the validator |
| `commission_rate` | `u16` | No | Commission rate in basis points (default from config) |

Generates the following files in the current directory:

| File | Description |
|------|-------------|
| `protocol.key` | Protocol keypair |
| `account.key` | Account keypair |
| `network.key` | Network keypair |
| `worker.key` | Worker keypair |
| `validator.info` | Signed validator metadata (used with `join-committee`) |

```
soma validator make-validator-info validator.example.com 200
```

### join-committee

Request to join the validator committee.

```
soma validator join-committee <VALIDATOR_INFO_PATH>
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `validator-info-path` | `path` | Yes | Path to `validator.info` file |

```
soma validator join-committee ./validator.info
```

### leave-committee

Request to leave the validator committee. Takes effect at end of current epoch.

```
soma validator leave-committee
```

```
soma validator leave-committee
```

### list

List all active and pending validators.

```
soma validator list
```

### display-metadata

Display validator metadata.

```
soma validator display-metadata [VALIDATOR_ADDRESS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `validator-address` | `SomaAddress` | No | Validator address (defaults to active address) |

```
soma validator display-metadata
```

```
soma validator display-metadata 0xVAL...
```

### update-metadata

Update validator metadata. Changes take effect next epoch.

```
soma validator update-metadata <SUBCOMMAND> <VALUE>
```

Available subcommands:

| Subcommand | Value type | Description |
|------------|------------|-------------|
| `network-address` | `address` | Update network address |
| `primary-address` | `address` | Update primary address |
| `p2p-address` | `address` | Update P2P address |
| `network-pub-key` | `path` | Update network public key from file |
| `worker-pub-key` | `path` | Update worker public key from file |
| `protocol-pub-key` | `path` | Update protocol public key from file |

```
soma validator update-metadata network-address /dns/validator.example.com/tcp/8080/http
```

```
soma validator update-metadata protocol-pub-key ./new-protocol.key
```

### set-commission-rate

Set validator commission rate. Takes effect next epoch.

```
soma validator set-commission-rate <COMMISSION_RATE>
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `commission-rate` | `u16` | Yes | Commission rate in basis points (max `10000`) |

```
soma validator set-commission-rate 500
```

### report-validator

Report a misbehaving validator.

```
soma validator report-validator <REPORTEE_ADDRESS> [OPTIONS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `reportee-address` | `SomaAddress` | Yes | Address of the validator to report |
| `--undo-report` | flag | No | Undo a previous report |

```
soma validator report-validator 0xVAL...
```

```
soma validator report-validator 0xVAL... --undo-report
```

### report-model

Report a model (validators only). If 2f+1 validators report a model at an epoch boundary, the model is slashed.

```
soma validator report-model <MODEL_ID> [OPTIONS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `model-id` | `ObjectID` | Yes | Model object ID to report |
| `--undo-report` | flag | No | Undo a previous report |

```
soma validator report-model 0xMODEL...
```

```
soma validator report-model 0xMODEL... --undo-report
```

## start

Start nodes and services.

### localnet

Start a local development network.

```
soma start localnet [OPTIONS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `--network.config` | `path` | No | Path to network config |
| `--force-regenesis` | flag | No | Force regenesis even if state exists |
| `--fullnode-rpc-port` | `u16` | No | RPC port for the fullnode (default `9000`) |
| `--epoch-duration-ms` | `u64` | No | Epoch duration in milliseconds |
| `--data-ingestion-dir` | `path` | No | Directory for data ingestion |
| `--no-full-node` | flag | No | Skip starting a fullnode |
| `--committee-size` | `u64` | No | Number of validators in the committee |
| `--log-level` | `string` | No | Log level (default `info`) |
| `--with-faucet` | `string` | No | Start faucet at `host:port` |
| `--no-faucet` | flag | No | Do not start faucet |
| `--no-scoring` | flag | No | Do not start scoring service |
| `--small-model` | flag | No | Use small model for scoring |

```
soma start localnet
```

```
soma start localnet --force-regenesis --epoch-duration-ms 10000 --with-faucet 127.0.0.1:9123
```

### validator

Start a validator node from a config file.

```
soma start validator --config <PATH>
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `-c`, `--config` | `path` | Yes | Path to validator configuration file |

```
soma start validator --config ./validator-config.yaml
```

### scoring

Start the scoring service.

```
soma start scoring [OPTIONS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `--host` | `string` | No | Host to bind to (default `0.0.0.0`) |
| `--port` | `u16` | No | Port to listen on (default `9124`) |
| `--data-dir` | `path` | No | Data directory for scoring state |
| `--small-model` | flag | No | Use a smaller model for testing |
| `--device` | `string` | No | Compute device: `cpu`, `wgpu`, or `cuda` (default `wgpu`) |

```
soma start scoring
```

```
soma start scoring --device cuda --port 9124
```

## network

Inspect local network configuration.

```
soma network [OPTIONS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `--network.config` | `path` | No | Path to network config file |
| `-d`, `--dump-addresses` | flag | No | Dump validator addresses |

```
soma network
```

```
soma network --dump-addresses
```

## genesis

Bootstrap and initialize a new network.

```
soma genesis [OPTIONS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `--from-config` | `path` | No | Create genesis from an existing config |
| `--write-config` | `path` | No | Write configuration to file without building genesis |
| `--working-dir` | `path` | No | Working directory for genesis output |
| `--force` | flag | No | Overwrite existing genesis state |
| `--epoch-duration-ms` | `u64` | No | Epoch duration in milliseconds |
| `--with-faucet` | flag | No | Include faucet in genesis |
| `--committee-size` | `u64` | No | Number of validators |

```
soma genesis --working-dir ./genesis-output --committee-size 4
```

```
soma genesis --from-config ./genesis-config.yaml --force
```

### ceremony

Coordinate a multi-validator genesis ceremony for network launches.

```
soma genesis ceremony [OPTIONS]
```

Used to coordinate genesis across multiple validator operators. Each participant runs the ceremony command to contribute their validator information, and the coordinator assembles the final genesis state.

## keytool

Low-level keystore operations.

### generate

Generate a new keypair.

```
soma keytool generate <KEY_SCHEME> [DERIVATION_PATH] [WORD_LENGTH]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `key-scheme` | `string` | Yes | Signing scheme (`ed25519`, `secp256k1`, `secp256r1`) |
| `derivation-path` | `string` | No | BIP-44 derivation path |
| `word-length` | `string` | No | Mnemonic word count |

```
soma keytool generate ed25519
```

### import

Import a key from a mnemonic or private key.

```
soma keytool import [--alias <ALIAS>] <INPUT_STRING> <KEY_SCHEME> [DERIVATION_PATH]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `input-string` | `string` | Yes | Mnemonic phrase or private key |
| `key-scheme` | `string` | Yes | Signing scheme |
| `--alias` | `string` | No | Alias for the imported key |
| `derivation-path` | `string` | No | BIP-44 derivation path |

```
soma keytool import "word1 word2 ... word12" ed25519 --alias imported-key
```

### export

Export a private key from the keystore.

```
soma keytool export --key-identity <IDENTITY>
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `--key-identity` | `string` | Yes | Address or alias of the key to export |
**Danger:** This outputs the raw private key. Never share it or store it in plaintext.

### list

List all keys in the keystore.

```
soma keytool list [OPTIONS]
```

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| `--sort-by-alias` | flag | No | Sort output by alias |

```
soma keytool list
```

<details>
<summary>Additional keytool subcommands</summary>

| Subcommand | Description |
|------------|-------------|
| `update-alias` | Update the alias for a key |
| `decode-or-verify-tx` | Decode or verify a transaction |
| `decode-multi-sig` | Decode a multi-sig transaction |
| `load-keypair` | Load a keypair from a file |
| `multi-sig-address` | Derive a multi-sig address |
| `multi-sig-combine-partial-sig` | Combine partial signatures for multi-sig |

</details>

## completions

Generate shell completion scripts.

```
soma completions bash > ~/.local/share/bash-completion/completions/soma
```

```zsh
soma completions zsh > ~/.zfunc/_soma
```

```fish
soma completions fish > ~/.config/fish/completions/soma.fish
```