Skip to content

cli.md

Latest commit

 

History

History
187 lines (126 loc) · 4.01 KB

cli.md

File metadata and controls

187 lines (126 loc) · 4.01 KB
Raw

CLI Reference

The current CLI is config-driven.

Except for aether start, CLI commands read and validate config files directly. They do not talk to a running server unless explicitly documented otherwise.

Runtime state changes happen through the local Control API.

Command Types

The current CLI surface falls into four categories:

  • server command
  • static config inspection command
  • validation command
  • file mutation command
  • runtime log assertion command

Start

aether start [--config <path>]

Starts the local HTTP server from the selected config file.

Notes:

  • reads config and builds the immutable runtime snapshot
  • initializes mutable active state
  • serves HTTP routes and Control API endpoints

Scenario Commands

Static config inspection

aether scenario list [--config <path>]
aether scenario describe <dimension=value> [--json] [--config <path>]
aether scenario export <dimension=value> --mode <metadata|behavior|full> [--config <path>]

These commands:

  • read the selected config file
  • do not require a running server
  • do not mutate the config file

Notes:

  • scenario describe --json produces machine-readable output
  • --mode metadata exports portable metadata only
  • --mode behavior exports route-dependent overrides
  • --mode full exports metadata and behavior together

Validation

aether scenario import <path> [--config <path>]

This command:

  • reads the selected config file
  • reads the import file
  • validates compatibility and conflicts
  • does not mutate the config file

File mutation

aether scenario import <path> --config <path> --write

This command:

  • validates the import first
  • rewrites the target config file on success
  • fails on conflicts by default
  • does not perform automatic merge or rename

Profile Commands

Static config inspection

aether profile list [--config <path>]
aether profile describe <name> [--config <path>]
aether profile export <name> [--config <path>]

These commands:

  • read the selected config file
  • do not require a running server
  • do not mutate the config file

Validation

aether profile apply <name> [--config <path>]
aether profile import <path> [--config <path>]

These commands:

  • read the selected config file
  • validate profile semantics against config
  • do not mutate runtime state
  • do not mutate the config file

profile apply validates the named profile and prints the next active state. It is a config-level preview, not a runtime command.

File mutation

aether profile import <path> --config <path> --write

This command:

  • validates the import first
  • rewrites the target config file on success
  • fails on conflicts by default
  • does not perform automatic merge or rename

Config Path

By default, CLI commands read:

.aether/aether.json

Override it explicitly when needed:

aether scenario list --config examples/ecommerce/aether.json

Runtime Control

Runtime state changes are intentionally kept out of the CLI in the current release.

Use the local Control API for:

  • changing active scenario values
  • applying profiles to the running server
  • inspecting runtime discovery data

See Control API.

Traffic Commands

Runtime log assertion

aether traffic assert --method <METHOD> --path <PATH> [--status <STATUS>]
aether traffic find --method <METHOD> --path <PATH> [--status <STATUS>]

This command:

  • reads the current day's .aether/traffic/YYYY-MM-DD.ndjson
  • does not require the server to be running at the moment of assertion
  • does not mutate runtime state
  • does not mutate the config file

Current matching fields:

  • --method
  • --path
  • optional --status

traffic find returns a JSON array of matching traffic events from the current day's NDJSON log.

Exit codes:

  • 0 = matching traffic found
  • 1 = no matching traffic found
  • 2 = invalid arguments or invalid traffic log data

traffic find exits with 2 on invalid arguments or invalid traffic log data.