AM CLI Architecture & Global Execution Reference

Document Identifier ARK-CLI-0301

Standard Status

Production Standard

Architecture Tier Unified Operator Tool (SAT & SCT)

Release Version V-1.0.0-GA (Production Stable)

Architecture Tier Scope: Unified Operator Tool (Primary for SAT) The AM CLI (am) is the authoritative command-line interface for the Aarkam storage fabric. In the Aarkam Standalone Tier (SAT: Rokka + Abodi), am is the primary operational management interface, functioning with zero dependency on the external web console. In the Aarkam Storage Centers Tier (SCT), am serves as the low-level administrative engine invoked by automation pipelines and bastion hosts.

The Rokka Distributed Control Plane CLI (am / am.exe) is a single-binary, high-performance administrative command-line utility built for managing, diagnosing, and securing sovereign storage clusters across Linux and Windows Server environments. It communicates directly with the distributed consensus plane over gRPC and TLS 1.3 / mTLS.

1. Fabric Architecture, Endpoints & Network Protocols

The am CLI interfaces directly with each distributed subsystem in the storage fabric across dedicated network ports:

Subsystem	Port (Plain / H2C)	Port (TLS / mTLS)	Protocol	Operational Purpose
Coordinator Service	`7774`	`57774`	gRPC (HTTP/2)	Cluster metadata, topology state, token enrollment, and placement.
Storage Daemon Fleet (Abodi)	`7775`	`57775`	gRPC (HTTP/2)	Raw Cauchy chunk I/O, direct page access, and disk operations.
Abodi Telemetry Engine	`7776`	`57776`	REST / gRPC	Real-time latency scoring, predictive drive failure, and SMART telemetry.
S3 Gateway (Core API)	`7771`	`57771`	HTTP / REST	Low-level S3 protocol translation and internal routing.
S3 Gateway (Public SigV4)	`7772`	`57772`	HTTPS / SigV4	S3 client endpoint fully compatible with AWS SigV4 SDKs.
Raft Consensus Monitors	—	`57777`	Raft RPC	Quorum elections, heartbeat monitoring, and distributed epoch log.
Kdouja LSM Sync Engine	—	`57778`	gRPC (HTTP/2)	Internal metadata write-ahead log (WAL) peer reconciliation.

2. Environment Configuration Overrides

The CLI respects standard environment variables for headless scripting and CI/CD pipelines:

ROKKA_COORDINATOR_URL / AARKAM_COORDINATOR_URL: Base URL of primary coordinator (e.g. https://coord-01.storage.internal:57774).
ROKKA_ABODI_URL / AARKAM_ABODI_URL: Base URL of Abodi diagnostics (default: http://localhost:7776).
AARKAM_ENROLLMENT_TOKEN: Single-use zero-trust token read during node bootstrapping (ET1....).
ROKKA_WAL_ENCRYPTION_KEY: 256-bit AES-GCM key (64 hex characters) for write-ahead log encryption (NCA ECC-2:2024 compliant).
SECURITY_ALLOW_INSECURE_TLS: When set to true, bypasses x509 chain verification for air-gapped dev/lab environments.
AARKAM_BASE_DIRECTORY: Local metadata and WAL storage path (default: aarkam_metadata).

3. Standardized Global Options

All commands in am accept standardized global execution options:

Option Flag	Alias	Type	Default	Operational Purpose
`--output-format`	`--format`	Enum	`table`	Output format: `table`, `json`, `yaml`, `ndjson`, or `csv`.
`--json`	—	bool	`false`	Shorthand for `--output-format json` for scripting with `jq`.
`--yaml`	—	bool	`false`	Shorthand for `--output-format yaml` configuration dumps.
`--output`	`-o`	string	stdout	Directs formatted output to file path without shell redirection.
`--watch`	`-w`	duration	null	Non-blocking live refresh mode (e.g. `am cluster status -w 2s`).
`--timeout`	`-t`	int	`30`	Operation timeout in seconds before client cancellation.
`--force`	`-f`	bool	`false`	Bypasses safety preflight checks (e.g. minimum online node counts).
`--yes`	`-y`	bool	`false`	Confirms destructive prompts without disabling safety preflights.
`--dry-run`	—	bool	`false`	Simulates planned mutations without mutating cluster state.
`--coordinator`	`-c`	string	null	Explicit Coordinator URL (e.g. `https://coord-01:57774`).

4. Deterministic POSIX Exit Codes

The am CLI emits deterministic exit codes for predictable shell scripting and automated orchestration:

Exit Code	Identifier	Operational Meaning	Recommended Remediation
`0`	`Success`	Command completed successfully.	Proceed with automation workflow.
`1`	`GeneralFailure`	Unhandled runtime fault or exception.	Inspect coordinator journal logs.
`2`	`InvalidArguments`	Malformed or missing CLI arguments.	Check command syntax via `am <cmd> --help`.
`3`	`AuthenticationFailure`	Invalid session token or bad key file.	Re-authenticate using `am auth login`.
`5`	`NetworkFailure`	Connection refused or TLS handshake timeout.	Run `am network ping`; check ports 57774/57775.
`7`	`QuorumUnavailable`	Raft consensus has no elected leader.	Check monitors via `am mon status`.
`8`	`ClusterUnhealthy`	Cluster state is degraded or critical.	Run `am cluster doctor`.
`9`	`ResourceNotFound`	Target node, volume, or object key missing.	Verify identifier with corresponding `list`.
`10`	`Conflict`	Resource state collision (e.g. maintenance active).	Check `am maintenance list`.
`11`	`SafetyCheckFailed`	Action blocked by preflight safety guard.	Review capacity; use `--force` only if authorized.
`13`	`DataIntegrityFailure`	CRC32C mismatch or bitrot detected.	Execute `am repair scrub`.