wraith-cli 1.7.0

Sovereign Command Centre for a Ghost Stack

👻 Wraith-CLI

Sovereign Orchestration & NAS Management for the Ghost Stack

Wraith-CLI is the nervous system of the Ghost Stack. It bridges the gap between high-level container orchestration and bare-metal reality — instant project scaffolding, container operations, and a full NAS management suite in one binary.

---

🗄️ NAS Management Suite

Command	Purpose
wraith disks	Physical disk inventory — model, serial, capacity, HDD/SSD, bus
wraith storage	Filesystem usage with configurable warn/crit thresholds
wraith raid	mdraid array and ZFS pool health
wraith smart /dev/sda	SMART verdict + failure-predicting attributes per drive
wraith shares	NFS exports and Samba shares, guest access flagged
wraith snap	ZFS/btrfs snapshot create / list / prune (safe by design)
wraith doctor	Full health check suite — cron-friendly exit codes, webhook/ntfy alerts
wraith report	Timestamped markdown/JSON audit reports

Every read-only command takes --json — pipe Wraith straight into dashboards, monitoring stacks, or fleet tooling. Unattended monitoring is one cron line:

*/30 * * * * wraith doctor --notify

See the NAS Management docs for full coverage.

---

🚀 Installation & Updates

Wraith-CLI is managed via uv for hermetic stability.

# Initial Installation
uv tool install wraith-cli

# Sovereign Update
wraith update

---

🔐 Environment Configuration

Defined in your .env or system environment. HTTPS is required for automated Gitea provisioning.

Variable	Purpose	Required For
GITEA_API_URL	Base URL (e.g., https://git.domain.com)	spawn
GITEA_TOKEN	Personal Access Token (PAT)	spawn
GITEA_TEMPLATE_URL	HTTPS URL of your base ghost-template	spawn
GITEA_COMPOSE_PATH	Path to Gitea Docker directory	runner-reset
VIKING_BASE_URL	API endpoint for heartbeat checks	status
WRAITH_COMPOSE_PATH	Default path for stack logs/ps	tail, ps

---

🧪 Developer Quality Gate

We use uv for hermetic environment management and maintain a strict >80% coverage requirement.

# Initialise the Environment
uv sync --all-extras
uv run pre-commit install

# The Quality Gate
uv run pytest --cov=src

---

📜 Sovereign Principles

1. Distributed Sovereignty: Available on PyPI for the world, but optimised for local-first, private-registry mirrors.
2. Atomic Execution: Use uv run to ensure consistency across the stack.
3. Hardware First: Prioritise bare-metal health and container stability over abstraction.