AM CLI Architecture & Global Execution

Installation, global execution flags, script automation, and deterministic exit codes.

Last updated: Sep 23, 2026

The Rokka Distributed Control Plane CLI (am) is the primary operational tool for storage engineers, site reliability engineers (SREs), and distributed systems operators managing production Aarkam clusters.

1. Global Options Reference

All commands in am inherit universal execution flags designed for both interactive terminals and headless automation pipelines:

Option	Flag	Default	Operational Purpose
`--format` / `--output-format`	`-f`	`table`	Select output structure: `table`, `json`, `yaml`, `ndjson`, or `csv`.
`--watch`	`-w`	None	Non-blocking live refresh engine (e.g. `am cluster status -w 2s`).
`--output`	`-o`	stdout	Directly stream formatted output to a specified disk file without shell redirection.
`--dry-run`		`false`	Run preflight validation checks without mutating cluster state.
`--yes`	`-y`	`false`	Automatically confirm interactive destructive prompts for CI/CD scripting.
`--force`		`false`	Override safety preflight blocks during emergency disaster recovery.

Practical Examples

# Export over-utilized storage nodes in JSON format for automated alerting
am node list --format json | jq '.[] | select(.usedPercentage > 85)'

# Run safety preflight before placing a node into maintenance
am maintenance start storage-node-03 --reason "Kernel Upgrade" --dry-run

2. Deterministic Exit Codes

The am CLI returns standardized exit codes, allowing shell scripts and orchestrators to handle failures deterministically:

Code	Constant	Meaning	Recommended Action
`0`	`Success`	Operation completed normally.	Continue automation pipeline.
`1`	`GeneralFailure`	Unhandled error or internal daemon fault.	Check coordinator daemon logs.
`2`	`InvalidArguments`	Syntax error or invalid parameter.	Run `am <command> --help`.
`3`	`AuthenticationFailure`	Master key invalid or KMS error.	Check operator certificate or HSM token.
`5`	`NetworkFailure`	Socket timeout or port unreachable.	Verify firewall ports `57774`/`57775`.
`7`	`QuorumUnavailable`	Raft consensus has no elected leader.	Run `am mon status` and `am mon peers`.
`8`	`ClusterUnhealthy`	Cluster health degraded or critical.	Run `am diagnose cluster`.
`9`	`ResourceNotFound`	Node, volume, bucket, or object missing.	Verify resource naming.
`10`	`Conflict`	State collision (e.g. node already locked).	Check `am maintenance list`.
`11`	`SafetyCheckFailed`	Preflight blocked action to prevent loss.	Review warning; verify redundancy.
`13`	`DataIntegrityFailure`	CRC hash mismatch or bitrot detected.	Trigger `am repair scrub`.