Operator CLI

The NOOSChain operator CLI is the command-line surface for running and inspecting a node. It wraps local operator/admin HTTP APIs plus a small number of local helper operations such as snapshot export/import and sidecar tooling.

The CLI does not bypass consensus. Commands either:

• read node or chain state;
• build, sign, and submit normal consensus transactions;
• perform local node maintenance;
• run local file/database operations such as snapshot export, verify, and import.

Use Swagger / OpenAPI for route discovery and request shape inspection. Use the CLI for actual operator workflows.

Run The CLI

From the repository root:

npm run noos -- node health
npm run noos -- node overview --json

Inline help:

npm run noos -- --help
npm run noos -- snapshots export --help
npm run noos -- governance operator-membership --help

Commands with operational consequences may also support --explain for a longer safety-oriented description.

The package declares a future compiled binary entry:

{ "bin": { "noos": "dist/cli/cli.js" } }

Configuration

The CLI loads .env from the current working directory before dispatching a command. Run npm run noos -- ... from the node folder whose .env you want to use. It does not search parent directories in this milestone.

Precedence:

1. command flags;
2. shell environment;
3. current-folder .env;
4. built-in defaults.

Important environment variables:

Variable	Purpose
NOOS_CLI_BASE_URL	Node API base URL. Defaults to http://127.0.0.1:3000.
NOOS_OPERATOR_TOKEN	Operator bearer token for protected node APIs.
DATABASE_URL	Local PostgreSQL URL for DB-backed snapshot and restore commands.
NOOS_CLI_TLS_CA_PATH	Custom CA for HTTPS.
NOOS_CLI_TLS_CERT_PATH	Client certificate for mTLS.
NOOS_CLI_TLS_KEY_PATH	Client key for mTLS.
NOOS_CLI_TLS_REJECT_UNAUTHORIZED	TLS verification switch. Defaults to true.

Global flags:

Flag	Use
--base-url <url>	Override node API URL.
--operator-token <token>	Override operator bearer token.
--json	Emit machine-readable output.
--pretty	Pretty-print JSON where supported.
--ca <file>	Use a custom TLS CA.
--cert <file>	Use a client mTLS certificate.
--key <file>	Use a client mTLS key.
--insecure	Disable TLS certificate verification for troubleshooting.
--timeout-ms <ms>	Override HTTP timeout.
--dry-run	Preview supported operations without applying them.
--yes	Confirm a command that mutates state or performs a dangerous local operation.
--explain	Show expanded operational guidance where supported.
--help	Show command help.

Safety Model

The CLI is designed to fail closed:

• dangerous commands require --yes;
• reviewable actions should support --dry-run;
• transaction builders create normal signed transactions rather than direct database writes;
• snapshot import requires explicit restore flags and local database access;
• peer, incident, governance, and runtime membership actions are gated by operator APIs and confirmation flags;
• sensitive values are redacted from normal output.

The CLI redacts tokens, private keys, secrets, DEKs, auth challenges, plaintext, and encrypted payload bytes. Private keys are accepted only by path, for example --signer-private-key-path admin.key; the CLI never prints private-key contents.

Payload files for transaction ADD_ENCRYPTED_RECORD may contain encrypted payload bytes and should be treated as sensitive local operator files.

Configuration File Helper

The config command group creates, inspects, validates, and edits dotenv files. It is a local helper: it does not contact a running node, invoke Docker, restart a process, or deploy a configuration.

List the available profiles:

npm run noos -- config profiles

The built-in profiles are:

Profile	Intended use
development-single-node	Local single-node development without mandatory TLS.
development-validator	Local validator using the external HashiCorp Go Raft sidecar.
development-observer	Local non-voting observer paired with the HashiCorp Go validator.
production-single-node	Closed single-node production deployment with TLS and mTLS.
production-validator	Production validator using the external HashiCorp Go Raft engine.
production-observer	Production non-voting observer using the external HashiCorp Go Raft engine.

If --profile is omitted, configuration commands use development-single-node. If --file or --output is omitted, they operate on .env in the current directory.

Create A Configuration

Generate a commented file from a profile:

npm run noos -- config init --profile development-single-node --output .env
npm run noos -- config init --profile production-validator --output validator.env

config init refuses to replace an existing file. Use --force only after reviewing the target path:

npm run noos -- config init --profile development-single-node --output .env --force

When an existing file is replaced, the helper preserves its previous contents as <file>.bak.

Production templates intentionally omit deployment-specific credentials, private keys, certificates, node IDs, addresses, and storage paths. They will remain invalid until those required values are supplied.

The development validator and observer templates are a matched local pair:

Setting	Validator	Observer
Node ID	validator-a	observer-a
Node API	http://127.0.0.1:9001	http://127.0.0.1:9002
Sidecar HTTP API	http://127.0.0.1:9101	http://127.0.0.1:9102
Raft TCP address	127.0.0.1:10001	127.0.0.1:10002
Database	nooschain_validator_a	nooschain_observer_a
Runtime role	voter	non-voting observer

Generate and validate both files with:

npm run noos -- config init --profile development-validator --output validator.env
npm run noos -- config init --profile development-observer --output observer.env
npm run noos -- config validate --profile development-validator --file validator.env
npm run noos -- config validate --profile development-observer --file observer.env

Both use RAFT_CLUSTER_ID=nooschain-dev-raft, RAFT_ENGINE=hashicorp-go, the external-process transport, and separate sidecar data directories. Build the sidecar first with npm run build:raft-go, and create the two PostgreSQL databases before starting the nodes.

The validator has HASHICORP_GO_RAFT_BOOTSTRAP=true and deliberately starts with an empty sidecar peer list. This bootstraps only validator-a as a voter; putting the observer in that bootstrap list would incorrectly make it a voter. Start the validator first, start the observer, then use the approved runtime membership workflow to add observer-a at 127.0.0.1:10002 as a non-voter. If an ID, port, or address changes, update the corresponding sidecar and membership settings in both files.

Raft Membership, Identity, And Peers

These settings describe three different concerns:

Setting	Meaning
RAFT_VOTER_NODE_IDS	Desired voting membership. Voters participate in leader election, may become leader, and count toward quorum. A majority of voters must be available to commit entries.
RAFT_OBSERVER_NODE_IDS	Desired non-voting replicated membership. Observers receive committed entries but cannot vote, become leader, or help form quorum.
RAFT_PEERS	Noosraft connection list. baseUrl is the remote node's NOOSChain Raft HTTP endpoint. It is routing information and does not grant membership.
HASHICORP_GO_RAFT_PEERS	Connections to remote HashiCorp sidecars. The individual fields are explained below. When present, this list replaces RAFT_PEERS for the HashiCorp engine.

For HashiCorp Go Raft, the voter and observer lists express NOOSChain's desired membership. They do not automatically rewrite the sidecar's live membership. Use the operator membership plan to reconcile the desired lists with the live HashiCorp configuration. In particular, listing a node under RAFT_OBSERVER_NODE_IDS does not itself add that sidecar as a non-voter.

RAFT_NODE_ID is the engine-neutral node identity. Noosraft uses it directly. HashiCorp Go Raft resolves its effective identity in this order:

1. HASHICORP_GO_RAFT_NODE_ID
2. RAFT_NODE_ID
3. NODE_ID

HASHICORP_GO_RAFT_NODE_ID therefore exists as an engine-specific override, mainly for sidecar-oriented deployments and compatibility. The built-in profiles set both values explicitly and keep them equal. The configuration helper reports an error if both are present but differ, because one physical node should not acquire two Raft identities accidentally. Cluster IDs follow the same override rule: HASHICORP_GO_RAFT_CLUSTER_ID takes precedence over RAFT_CLUSTER_ID.

Example generic Noosraft peer:

{"nodeId":"node-b","baseUrl":"http://127.0.0.1:9002"}

Example HashiCorp sidecar peer:

{"nodeId":"node-b","httpUrl":"http://127.0.0.1:9102","raftAddress":"127.0.0.1:10002"}

Read that entry as "how this node describes the services belonging to node-b":

Peer field	What value to enter	Who uses it
nodeId	The remote node's effective Raft identity, for example observer-a. It must match the ID reported by that remote sidecar.	Raft uses it to associate addresses and membership with one stable node.
httpUrl	The remote HashiCorp sidecar HTTP API, for example http://127.0.0.1:9102. This is not the NOOSChain application API.	That API supports status, proposals, log catch-up, shutdown, and membership operations. In the current static peer list this value is retained as endpoint metadata; Raft replication itself does not use it.
raftAddress	The remote HashiCorp sidecar TCP replication listener, for example 127.0.0.1:10002. This is a host and port, not an HTTP URL. It must be reachable from the other sidecars.	HashiCorp Raft uses it for elections and replicated-log traffic. Adding a voter or non-voter requires this address.
callbackBaseUrl	Optional metadata describing the remote NOOSChain application API. Most deployments should omit it from peer entries.	The active callback target is configured on each machine with HASHICORP_GO_RAFT_CALLBACK_BASE, so it is not needed for normal peer connectivity.

For the built-in observer profile, its peer entry describes the validator:

nodeId          validator-a             identity of the remote validator
httpUrl         http://127.0.0.1:9101   validator sidecar management API
raftAddress     127.0.0.1:10001         validator sidecar replication socket

The 9101 and 10001 values therefore do not appear in the observer's own bind settings: they belong to the remote validator. The complete local pair is:

Profile being edited	Its own sidecar HTTP	Its own Raft TCP	Remote peer entry
development-validator	9101	10001	[] while bootstrapping the validator alone
development-observer	9102	10002	Points to validator HTTP 9101 and Raft TCP 10001

The two local addresses that belong to the current node are configured outside the peer list:

• HASHICORP_GO_RAFT_HTTP_BIND tells the current sidecar where to expose its own management API.
• HASHICORP_GO_RAFT_BIND tells the current sidecar where to listen for Raft TCP replication.
• HASHICORP_GO_RAFT_CALLBACK_BASE tells the current sidecar where its local NOOSChain application is listening for committed-entry callbacks.

Use The CLI With Docker

The Docker image installs the compiled CLI as noos. Run it inside a node when the command needs that node's database, mounted files, or loopback-only sidecars:

docker compose -f docker/compose.local.yaml exec validator noos node health --json
docker compose -f docker/compose.local.yaml exec validator noos raft-go health --json
docker compose -f docker/compose.local.yaml exec validator noos state-root preflight --json
docker compose -f docker/compose.local.yaml exec validator noos contracts runtime preflight --json

For API-only or configuration-file work, use the on-demand CLI service:

docker compose -f docker/compose.local.yaml run --rm cli node health --json
docker compose -f docker/compose.local.yaml run --rm cli config validate --profile production-validator --file /config/validator.env

Files under docker/config are mounted at /config. See Docker Deployment for the complete image, Compose, persistence, firewall, migration, and production release workflow.

Inspect And Validate

Show effective values and the current validation result:

npm run noos -- config show --file .env
npm run noos -- config show --file validator.env --profile production-validator --json

Tokens, database URLs, private keys, TLS private-key paths, passwords, and other sensitive-looking values are redacted by default. Use --show-secrets only in a trusted local terminal:

npm run noos -- config show --file .env --show-secrets

Run fail-closed validation separately when using the helper in scripts:

npm run noos -- config validate --file .env --profile development-single-node
npm run noos -- config validate --file validator.env --profile production-validator --json

config validate exits with an error if validation fails. Validation includes:

• required profile values;
• integer ranges, URLs, JSON fields, booleans, and enumerated values;
• production NODE_ENV and TLS verification requirements;
• TLS certificate/key and mTLS CA relationships;
• Raft node and cluster identity requirements;
• matching NODE_ID and RAFT_NODE_ID;
• duplicate voters and voter/observer overlap;
• election timeout greater than heartbeat interval;
• validator and observer role/profile consistency;
• local validator membership in RAFT_VOTER_NODE_IDS;
• local observer membership in RAFT_OBSERVER_NODE_IDS and the presence of at least one voter;
• required HTTP bind URL, unique peer IDs, valid peer URLs, and peer coverage for every configured remote Raft member.

Validation checks configuration structure and safety relationships. It does not check whether files exist, ports are available, PostgreSQL is reachable, a sidecar binary starts, or the node passes production preflight.

Set Or Remove Values

Set a value while preserving comments and unrelated variables:

npm run noos -- config set PORT 3100 --file .env
npm run noos -- config set NOOS_LOG_LEVEL debug --file .env

For secrets, prefer standard input so the value is not stored in shell history:

$operatorToken | npm run noos -- config set NOOS_OPERATOR_TOKEN --file .env --value-stdin

Remove every definition of one key:

npm run noos -- config unset NOOS_SWAGGER_ENABLED --file .env

set and unset write the requested edit even when other fields remain invalid; their result includes the updated validation report. Run config validate as the final gate before using the file.

The helper accepts unknown environment keys so deployment-specific settings can coexist with the managed catalog. It preserves unknown entries and comments rather than normalizing or deleting them.

Every edit is written through a temporary sibling file and preserves the prior file as <file>.bak.

Compare With A Profile

Compare the selected file with profile defaults:

npm run noos -- config diff --file .env --profile development-single-node
npm run noos -- config diff --file validator.env --profile production-validator --json

The diff reports added, removed, and changed values, whether a field is sensitive, and whether the setting requires a restart. Secret values are redacted in both sides of the diff.

Interactive Editing

Run the terminal editor:

npm run noos -- config edit --file .env --profile development-single-node

For each managed field, press Enter to keep the current value or enter - to remove a non-secret value. Secret fields are reported only as set or not set and are not exposed or changed by the interactive prompts. Use config set --value-stdin to change them safely.

config edit requires an interactive terminal. It preserves comments and unknown fields and asks for confirmation before saving.

Apply The File Manually

Configuration values are loaded when the node starts. After installing the edited file, restart the local development process or recreate the intended Compose service.

Local development:

npm run noos -- config validate --file .env --profile development-single-node
npm run dev

Docker Compose using the edited file as an env_file:

docker compose config
docker compose up -d --force-recreate nooschain

For production, follow the restart with the appropriate readiness gate:

npm run noos -- production preflight --profile validator

The helper does not replace production change control, secret management, backup procedures, rolling validator restarts, or quorum checks.

Doctor

Run doctor first when setting up an operator shell or debugging access:

npm run noos -- doctor
npm run noos -- doctor --json

It checks:

• Node.js runtime version;
• whether .env was loaded from the current working directory;
• effective node API base URL;
• whether an operator token is configured;
• whether DATABASE_URL is configured for local snapshot operations;
• TLS and mTLS file-path configuration;
• authenticated access to /node/observability/overview when a token is set;
• Go toolchain availability for HashiCorp Raft sidecar builds.

The command reports where each effective value came from: flag, shell environment, .env, default, or unset. It does not print operator tokens or database URLs.

Quick Health Checks

Use these commands for a first look at a node:

npm run noos -- node overview
npm run noos -- node health --json
npm run noos -- node metrics
npm run noos -- node sync
npm run noos -- chain head
npm run noos -- chain verify

node sync reads /node/observability/sync. It is useful while a node is catching up or backfilling payloads because it reports phase, peer/result, block and payload counters, backfill reason counts, failover count, last error, and trusted-peer sync state.

For production monitoring design, see Monitoring And Alerting and Observability API.

Production Commands

Use production commands before admitting a node to production traffic and during scheduled operator checks:

npm run noos -- production report --json
npm run noos -- production monitor-report --json
npm run noos -- production profile --profile validator
npm run noos -- production preflight
npm run noos -- production backup-drill --output ./backup-drill

production report is a read-only launch checklist. It checks CLI HTTPS/auth posture, local DATABASE_URL, production profile match, node/CLI compatibility, migration compatibility, node production mode, node TLS/mTLS, health, incidents, database readability, consensus mode, HashiCorp Raft sidecar health, Raft TCP TLS, governance/runtime membership alignment, state-root readiness, snapshot backup readiness, payload availability, and sync/backfill status.

production preflight is a fail-closed admission gate. It is read-only; it does not repair the node or mutate membership. It exits with an error when required checks fail. See Production Readiness.

production monitor-report derives current critical, warning, and info alerts from observability. It is intended for monitoring glue and scheduled operator checks. See Monitoring And Alerting.

production profile returns the role/compatibility subset. Pass --profile validator, --profile observer, or --profile single-node, or set NOOS_PRODUCTION_PROFILE in the node .env.

production backup-drill is local and DB-backed. It exports a packaged archive snapshot, verifies it, imports it into generated isolated schemas, verifies the restored chain/checkpoint bootstrap path, and writes backup-drill-report.json. Use it to prove a backup artifact can restore. For actual node replacement or rejoin decisions, use Backup, Restore, And Recovery.

Transactions

Transaction commands build, sign, and submit consensus transactions:

npm run noos -- tx types
npm run noos -- tx schema --type REGISTER_USER
npm run noos -- tx build --type REGISTER_ORGANIZATION --payload-file org.json --signer-public-key="<public-key>" --signer-private-key-path admin.key --output tx.json
npm run noos -- tx submit --file tx.json --yes
npm run noos -- tx build-and-submit --type REGISTER_USER --payload-file user.json --signer-public-key="<public-key>" --signer-private-key-path admin.key --yes

tx build supports the current protocol transaction types from the central payload schema registry. It validates the payload file, resolves the signer and next nonce using local DATABASE_URL, and signs the canonical transaction.

tx submit posts the signed transaction to /transactions; it never inserts rows directly. Submission requires --yes.

PEM public keys begin with dashes, so use --signer-public-key=<key> rather than separating the flag and value.

Recipes

Recipes are safer wrappers around common transaction workflows. They explain the operation, validate payloads, support --dry-run, and submit only when --yes is provided.

npm run noos -- recipe list
npm run noos -- recipe init:template organization --output org.json
npm run noos -- recipe init:create-organization --payload-file org.json --signer-public-key="<admin-public-key>" --signer-private-key-path admin.key --dry-run
npm run noos -- recipe init:create-user --payload-file user.json --signer-public-key="<admin-public-key>" --signer-private-key-path admin.key --yes
npm run noos -- recipe init:create-bucket --payload-file bucket.json --signer-public-key="<writer-public-key>" --signer-private-key-path writer.key --output bucket-tx.json
npm run noos -- recipe init:update-bucket-policy --payload-file policy.json --signer-public-key="<bucket-admin-public-key>" --signer-private-key-path bucket-admin.key --yes
npm run noos -- recipe init:assign-bucket-principal --payload-file rule.json --signer-public-key="<bucket-admin-public-key>" --signer-private-key-path bucket-admin.key --yes

See Recipes. For bucket concepts and permissions, see Data Buckets and Permission Model.

Organizations And Users

Read organization and user state:

npm run noos -- organizations list
npm run noos -- organizations show org-noos
npm run noos -- organizations users org-noos
npm run noos -- users list --organization-id org-noos
npm run noos -- users show user-admin

These commands are read-only. Organization and user registration is performed with signed consensus transactions through noos tx.

Node Storage And Payloads

Use these commands when diagnosing local storage, payload availability, or encrypted payload retention:

npm run noos -- node storage
npm run noos -- node payloads
npm run noos -- node reconcile-payload-availability --dry-run
npm run noos -- node reconcile-payload-availability --prune-disallowed --yes
npm run noos -- node payload-store-stats
npm run noos -- node payload-store-stats --realtime
npm run noos -- node payload-store-gc --dry-run --older-than-days 30
npm run noos -- node payload-store-gc --bucket-id bucket-a --yes
npm run noos -- node payload-store-repair-counters --yes

node reconcile-payload-availability compares this node's local ciphertext availability with bucket replication policies, bucket permissions, and local node identity. Dry-run reports ciphertext that is locally present but no longer allowed, plus ciphertext that is allowed but still missing. With --prune-disallowed --yes, it clears only local availability-layer fields for disallowed rows. It does not create transactions, change blocks, or update state roots.

node payload-store-stats reads cached local encrypted payload table size and age without returning ciphertext bytes. Use --realtime only for exact counter drift troubleshooting because it scans local payload rows.

node payload-store-gc is a local availability-retention command. Dry-run is the default and non-dry-run requires --yes. It deletes only local ciphertext bytes selected by the filters and does not change consensus state.

node payload-store-repair-counters --yes rebuilds cached payload availability counters from realtime database contents when an operator suspects counter drift after manual database maintenance.

Consensus, Governance, And Peers

Read and reconcile validator, peer, and runtime membership state:

npm run noos -- governance validators
npm run noos -- governance validators active
npm run noos -- validators list
npm run noos -- validators active
npm run noos -- validators show node-validator-1
npm run noos -- governance runtime-membership
npm run noos -- governance reconciliation-plan
npm run noos -- governance operator-membership plan --json
npm run noos -- governance operator-membership execute --plan-file operator-actions.json --dry-run
npm run noos -- governance operator-membership execute --plan-file operator-actions.json --yes

governance operator-membership plan compares three operator planes:

• governance active validators;
• runtime Raft voters/non-voters;
• local trusted_peers.

Applying a plan can add, update, or disable trusted peers and, for the HashiCorp Raft engine, execute approved runtime Raft membership actions. It does not create governance validators directly; registering, suspending, reactivating, or retiring validators remains a signed consensus transaction.

Peer commands:

npm run noos -- peers list
npm run noos -- peers scores
npm run noos -- peers score peer-a
npm run noos -- peers quarantine peer-a --reason "bad responses"
npm run noos -- peers ban peer-a --reason "operator decision" --yes
npm run noos -- peers unban peer-a --yes
npm run noos -- peers reset-score peer-a

Raft commands:

npm run noos -- raft status
npm run noos -- raft leader
npm run noos -- raft membership
npm run noos -- raft reconciliation-plan
npm run noos -- raft execute-membership-plan --plan-file plan.json --dry-run
npm run noos -- raft execute-membership-plan --plan-file plan.json --yes

Runtime membership execution requires --yes and an operator token. The Raft execute command uses the same operator membership execution endpoint as the governance operator-membership workflow, so trusted peer alignment and runtime Raft membership changes can be reviewed together.

For runbooks, see HashiCorp Raft Deployment, Raft Consensus Configuration, and Raft Sidecar Operations.

State-Root Commands

Use state-root commands for engine readiness, activation diagnostics, and public proof verification:

npm run noos -- state-root status
npm run noos -- state-root readiness --json
npm run noos -- state-root preflight
npm run noos -- state-root proof get --namespace bucket --id bucket-a --json
npm run noos -- state-root proof verify --file proof.json --json

These commands are read-only diagnostics. They do not schedule a migration or mutate chain state.

state-root preflight is intended for deployment scripts. It exits with an error unless readiness is green, including sidecar binary presence, exact sidecar protocol version, health, mutation, checkpoint round-trip, and production release-gate checks.

state-root proof get calls GET /state/proof and returns a per-entity proof for a public namespace/entity id. state-root proof verify calls POST /state/proof/verify and verifies a saved proof document without trusting local database contents.

Supported namespaces include organization, user, node, validator, chain_access_rule, state_root_engine_activation, bucket, bucket_access_rule, bucket_key, and encrypted_record.

For rollout and recovery, use State-Root Activation, Nervos Activation Runbook, and Nervos Sidecar Recovery.

Snapshots

Snapshot commands are local file/database operations. They use DATABASE_URL and do not call /snapshots/export.

npm run noos -- snapshots list
npm run noos -- snapshots export --output snapshot.noosnap.tar.gz --mode consensus_state_only
npm run noos -- snapshots export --output snapshot-with-ciphertext.noosnap.tar.gz --mode include_local_ciphertext
npm run noos -- snapshots export --format archive --output snapshot.noosnap --mode consensus_state_only
npm run noos -- snapshots export --format json --output legacy-snapshot.json --mode consensus_state_only
npm run noos -- snapshots export --output snapshot.noosnap.tar.gz --mode consensus_state_only --dry-run
npm run noos -- snapshots verify --file snapshot.noosnap
npm run noos -- snapshots verify --file snapshot.noosnap.tar.gz
npm run noos -- snapshots import --file snapshot.noosnap.tar.gz --mode empty_database_only --dry-run
npm run noos -- snapshots import --file snapshot.noosnap.tar.gz --mode empty_database_only --yes
npm run noos -- snapshots pack --input snapshot.noosnap --output snapshot.noosnap.tar.gz
npm run noos -- snapshots unpack --file snapshot.noosnap.tar.gz --output snapshot.noosnap

The default operator artifact is a packaged archive, normally snapshot.noosnap.tar.gz. Archive snapshots contain manifest.json plus one CSV file per table under tables/.

Legacy JSON snapshots are available with --format json, but they are intended for compatibility and debugging rather than large operational backups.

Progress is written to stderr so JSON stdout remains parseable. Use --no-progress to suppress it. In --json mode progress is suppressed unless you also pass --progress.

Operator restore additionally requires --operator-restore, --yes, and NOOSCHAIN_ALLOW_OPERATOR_RESTORE=true.

For procedures and restore decisions, see Backup, Restore, And Recovery and Snapshots. For the general snapshot concept, see General Snapshots.

Incidents And Conflicts

Use incident commands during active investigation and recovery:

npm run noos -- incidents active
npm run noos -- incidents list
npm run noos -- incidents doctor --json
npm run noos -- incidents resolve incident-id --reason "reviewed" --yes
npm run noos -- conflicts list
npm run noos -- support bundle --output noos-support-bundle.json

incidents doctor diagnoses active incidents and suggests next commands. It does not mark anything resolved. support bundle writes a redacted JSON bundle for operator troubleshooting.

If an incident requires restoring a node, run the role-specific recovery procedure before marking the incident resolved. See Incident Response, Conflict Handling, and Backup, Restore, And Recovery.

Smart-Contract Runtime Commands

Operators own runtime activation and node readiness, not contract authoring or package policy design.

Use the launch gate before production activation:

npm run noos -- contracts launch-gate --profile mainnet --json

The report is read-only. It checks runtime activation, Wasmtime sidecar preflight, rollout evidence, registry audit metadata, contract readiness, production alerts, snapshot/checkpoint metadata, and sidecar binary provenance. Human-only items such as external audit completion, threat-model review, operator key custody, and per-contract business-logic audits remain outside the automated report.

Inspect sidecar build provenance from the running node:

npm run noos -- contracts runtime provenance --json

Generate local sidecar provenance without a running node:

npm run contracts:sidecar:provenance

This page does not repeat smart-contract package, provenance, registry, or publishing rules. Use:

• Smart Contract Runtime Operations for operator runtime activation and preflight;
• Packages And Provenance for the package integrity chain;
• Package Provenance for descriptor signatures and active provenance policy;
• Contract Registry for network package approval;
• Publishing for package build/sign/publish flows.

Local Helper Commands

Some commands invoke local tooling or report local sidecar state:

npm run noos -- raft-go build
npm run noos -- raft-go version
npm run noos -- raft-go status --json
npm run noos -- raft-go health --json
npm run noos -- raft-go doctor --json
npm run noos -- raft-go restart --dry-run
npm run noos -- certs dev-generate

raft-go build and certs dev-generate invoke local tooling. raft-go status, health, and doctor read sidecar observability from the node. Direct forced restart/start/stop is not exposed by the current node API, so lifecycle commands provide manual recovery plans with --dry-run.

Command Map

Need	Commands	Runbook
Create or validate a dotenv file	config init, config show, config validate, config set, config unset, config diff, config edit	Configuration File Helper on this page
Check CLI access	doctor, node health, node overview	Production Readiness
Monitor a node	node metrics, node sync, production monitor-report	Monitoring And Alerting
Build transactions	tx types, tx schema, tx build, tx submit	Recipes
Manage common setup flows	recipe ...	Recipes
Reconcile peers and validators	governance ..., raft ..., peers ...	Raft Consensus Configuration
Check state-root readiness	state-root status, state-root preflight	State-Root Activation
Export or restore snapshots	snapshots export, snapshots verify, snapshots import	Backup, Restore, And Recovery
Investigate incidents	incidents ..., conflicts ..., support bundle	Incident Response
Operate smart-contract runtime	contracts launch-gate, contracts runtime provenance	Smart Contract Runtime Operations