Reference

CLI commands, management API, configuration, and slice API.

Status: in active development — release-candidate series toward GA; current candidate 1.0.0-rc3 (2026-09-02). Not yet production-ready.

CLI Tools

Tool	Purpose
`aether`	Cluster management CLI — 60+ commands, batch and REPL modes
`aether-node`	Run a cluster node
`aether-forge`	Local cluster simulator with visual dashboard
`jbct`	Code validation, formatting, project scaffolding

CLI Command Groups

Group	Commands
`status`	Cluster status, leader, node count, health
`nodes`	List nodes, roles, states
`slices`	Cluster-wide and per-node slice listing
`routes`	HTTP routes, cluster-wide and per-node
`metrics`	System metrics, historical queries (5m/15m/1h/2h)
`health`	Cluster health score, component status
`scale`	Manual scaling, instance count adjustment
`deploy`	Blueprint deployment with strategy selection
`artifact`	Upload, list, inspect artifacts
`blueprint`	List, inspect, delete blueprints
`config`	View and update runtime configuration
`logging`	Dynamic log level management
`events`	Cluster event history and streaming
`node`	Drain, activate, shutdown individual nodes
`cluster`	Bootstrap, scale, upgrade cluster
`observability`	Enable/disable tracing and metrics per method
`alerts`	Active and historical alerts
`thresholds`	Warning/critical threshold configuration
`backup`	Trigger, list, restore cluster backups
`schema`	Migration status, manual retry
`node-slices`	Per-node slice listing
`node-routes`	Per-node route listing
`invocation-metrics`	Per-method P50/P95/P99 latency
`controller`	Scaling controller configuration
`scheduled-tasks`	List, pause, resume, trigger scheduled tasks
`topology`	Compile-time data-flow graph
`workers`	Worker pool management and health
`stream`	Stream management, consumer groups, lag
`storage`	AHSE storage management
`cert`	Certificate operations
`ab-test`	A/B test management

Authentication

# Via flag
aether --api-key mykey123 status

# Via environment
export AETHER_API_KEY=mykey123
aether status

Management API

190+ REST endpoints, every one under /api/v1 except the two health probes. All endpoints accept JSON and return JSON. The table below shows key endpoints — see the full API in the management API reference.

Endpoint	Method	Description
`/health/live`	GET	Liveness probe (not under /api/v1)
`/health/ready`	GET	Readiness probe (not under /api/v1)
`/api/v1/cluster/status`	GET	Cluster status: leader, core count, phase
`/api/v1/cluster/…`	GET	Topology, generation, membership, provisioning
`/api/v1/nodes`	GET	List cluster nodes
`/api/v1/nodes/routes`	GET	List HTTP routes
`/api/v1/nodes/drain/{id}`	POST	Drain a node
`/api/v1/nodes/shutdown/{id}`	POST	Shut down a node
`/api/v1/slices`	GET	List deployed slices
`/api/v1/scale`	POST	Set scaling config
`/api/v1/deploy`	POST	Deploy a blueprint (canary, blue-green, rolling)
`/api/v1/blueprints`	GET/POST	Blueprint CRUD
`/api/v1/config/…`	PUT	Runtime configuration overrides
`/api/v1/metrics/…`	GET	System, per-node, per-slice metrics
`/api/v1/metrics/prometheus`	GET	Prometheus scrape endpoint

WebSocket Endpoints

Endpoint	Description
`/ws/dashboard`	Live metrics stream
`/ws/status`	Cluster state changes
`/ws/events`	Real-time cluster events with delta broadcasting

Default Ports

Port	Purpose	Notes
8070	App HTTP (slice endpoints)	TCP, per node. Configurable
8080	Management API	TCP, per node. Configurable
8090	Cluster transport (QUIC: consensus, KV-Store, HTTP forwarding, DHT)	UDP, per node
8190	SWIM failure detection	UDP, per node
8888	Dashboard (Forge)	Configurable via `FORGE_PORT`

Slice API

Built-In Annotations

Annotation	Target	Purpose
`@Slice`	Interface (TYPE)	Marks a service interface for annotation processing
`@ResourceQualifier`	Annotation (ANNOTATION_TYPE)	Meta-annotation for defining custom resource qualifiers
`@PgSql`	Parameter, Interface	PostgreSQL type-safe persistence (Aether Store)
`@Sql`	Parameter	Generic SQL connector (config: `"database"`)
`@Http`	Parameter	HTTP client (config: `"http"`)
`@Notify`	Parameter	Notification sender (config: `"notification"`)
`@ContentStoreQualifier`	Parameter	Content store access
`@PartitionKey`	Record component	Marks partition key field for stream routing

Custom Qualifier Patterns

These are defined per-project using @ResourceQualifier. The resource type and target determine the behavior:

Resource Type	Target	Purpose
`Subscriber.class`	METHOD	Pub-sub topic subscription
`Scheduled.class`	METHOD	Scheduled task (cron/interval configured in TOML)
`StreamPublisher.class`	PARAMETER	Stream publishing
`StreamSubscriber.class`	METHOD	Stream push-based consumption
`StreamAccess.class`	PARAMETER	Stream pull-based access
`PgNotificationSubscriber.class`	METHOD	PostgreSQL LISTEN/NOTIFY
`ConfigurationSection.class`	PARAMETER, METHOD	Typed config injection + runtime update notification
`MethodInterceptor.class`	METHOD	Method-level interceptors (retry, circuit breaker)

Core Types

Type	Purpose
`Promise<T>`	Asynchronous computation result. All slice methods return this
`Result<T>`	Success or failure. Used for validation, parsing, error handling
`Option<T>`	Present or absent value. Replaces null
`Cause`	Sealed error interface. Replaces exceptions
`Unit`	Void replacement for `Promise<Unit>`

Configuration

Aether is configured via aether.toml. Key sections:

Section	Purpose
`[cluster]`	Cluster name, peer addresses, ports
`[server]`	HTTP server port, worker threads
`[app-http]`	Application HTTP server, API keys, RBAC
`[database.*]`	Database connections
`[http.*]`	HTTP client configurations
`[cloud]`	Cloud provider settings
`[timeouts.*]`	13 subsystem-specific timeout groups
`[storage]`	AHSE tier configuration (memory/disk/S3)
`[app.*]`	Application configuration (merged with slice defaults)
`[endpoints.*]`	Infrastructure endpoint definitions

Environment Variables

Variables with AETHER_ prefix are imported automatically. Converted from SCREAMING_SNAKE_CASE to dot.notation.lowercase:

Environment Variable	Config Key
`AETHER_DATABASE_HOST`	`database.host`
`AETHER_SERVER_PORT`	`server.port`
`AETHER_CLUSTER_SECRET`	`cluster.secret`

For complete configuration reference including all timeout groups, see configuration.md and timeout-configuration.md in the repository.