CLI Reference¶
The astraeus launcher is the supported installed command surface. Use
astraeus --version, astraeus --help, or <command> --help to inspect the
exact version installed on a machine.
Supported Command Set¶
| Command | Purpose |
|---|---|
astraeus activate |
Activate online, from a signed offline file, or by trial invitation |
astraeus license |
Inspect, refresh, or deactivate the current licence |
astraeus run |
Validate or execute one RunSpec |
astraeus sweep |
Plan, execute, resume, or rerun related variants |
astraeus batch |
Plan, execute, resume, or rerun explicit RunSpec collections |
astraeus campaign-plan |
Validate or execute deployment campaigns |
astraeus monitor serve |
Watch core, sweep, and batch progress read-only |
astraeus console |
Configure supported runs and inspect completed results locally |
astraeus resources |
List or copy bundled user resources |
astraeus review |
Generate deterministic run or campaign reviews |
astraeus report scenario |
Generate a scenario report and plot pack |
astraeus skills |
List, install, or verify user AI skills |
The supported command set is the table above. Additional launcher commands are internal or transitional; in particular, standalone mission planning is an internal development workflow and campaign planning is the supported user planning surface.
Activation And Licence Status¶
astraeus activate --activation-key
astraeus activate --activation-key-env <variable>
astraeus activate --license-file <signed-entitlement.json>
astraeus activate trial
astraeus license status [--json]
astraeus license refresh
astraeus license deactivate
Interactive activation reads secrets from a secure prompt. The environment form names the variable containing an activation key; it does not place the key on the command line. Status output is redacted and reports whether new execution is allowed plus the next action. See Installation and Lifecycle for the activation flows and authorization behavior.
Run One Scenario¶
astraeus run <runspec.yaml> [options]
| Option | Meaning |
|---|---|
--dry-run |
Resolve imports, validate, and build the execution plan without running the engineering stages |
--strict |
Treat validation warnings as failures |
--run-id <id> |
Override the RunSpec run identifier |
--output-root <directory> |
Override the default runs/core root |
--profile-root <directory> |
Set a stable root for layered imports |
--seed <integer> |
Override the runtime seed |
The reserved --mission-plan-result flag supports an internal integration. The
user-facing planning surface is the campaign command family.
On success the command prints the run directory. An existing run identifier is not silently overwritten; choose a new identifier or manage the earlier bundle deliberately.
Sweeps¶
astraeus sweep plan <runspec.yaml> [options]
astraeus sweep run <runspec.yaml> [options]
astraeus sweep resume <bundle-or-artifact> [options]
astraeus sweep rerun <bundle-or-artifact> (--failed | --case <id> | --all) [options]
| Subcommand | Result |
|---|---|
plan |
Validates and materializes sweep_plan.json without executing cases |
run |
Plans and executes isolated child cases, then prints sweep_results.json |
resume |
Executes unfinished cases; add --retry-failed to include current failures |
rerun |
Starts a new attempt for failed, selected, or all cases |
Planning and execution options include:
| Option | Meaning |
|---|---|
--sweep-id <id> |
Override the deterministic study identifier |
--output-root <directory> |
Override runs/sweeps |
--profile-root <directory> |
Set the import root |
--max-cases <n> |
Record a warning above the selected case count; execution may continue |
--workers <n> |
Bound local child-process concurrency; default is serial |
--write-summary-csv / --no-write-summary-csv |
Override CSV summary output |
resume and rerun accept the bundle directory or a canonical sweep artifact.
Recovery appends to the attempt history so earlier attempts remain in the
bundle.
Batches¶
astraeus batch plan <batch.yaml> [options]
astraeus batch run <batch.yaml> [options]
astraeus batch resume <bundle-or-artifact> [options]
astraeus batch rerun <bundle-or-artifact> (--failed | --case <id> | --all) [options]
Batches use the same plan/run/resume/rerun lifecycle as sweeps, but the input is
a batch_v1 manifest containing explicit RunSpec references.
| Option | Meaning |
|---|---|
--batch-id <id> |
Override the deterministic batch identifier |
--output-root <directory> |
Override runs/batches |
--profile-root <directory> |
Set the import root |
--max-cases <n> |
Record a warning above the selected count |
--workers <n> |
Bound local concurrency; default is serial |
--write-summary-csv / --no-write-summary-csv |
Override CSV summary output |
Use a sweep when cases are variants of one base RunSpec; use a batch when the cases are independently authored RunSpecs.
Campaign Planning¶
astraeus campaign-plan validate --input <request.yaml>
astraeus campaign-plan run --input <request.yaml> [options]
| Run option | Meaning |
|---|---|
--output <path> |
Override runs/campaign/<campaign-id>/campaign_plan_result.json |
--mission-artifact-detail summary|full |
Select embedded summaries or additional per-satellite mission bundles |
--mission-workers <n> |
Bound campaign mission workers; default is four |
--mission-execution-backend serial|thread|process|auto |
Select the mission execution backend |
--mission-auto-parallel-threshold <n> |
Set the satellite-count threshold used by auto |
--mission-timeout-s <seconds> |
Set the per-mission timeout where timeout handling applies |
--mission-timeout-policy mark_failed|fail_campaign |
Choose the campaign response to a mission timeout |
--campaign-execution-diagnostics / --no-campaign-execution-diagnostics |
Override execution-policy diagnostics |
Campaign status is recorded inside the result. A normally completed command may produce a scientifically useful partial or infeasible outcome; interpret the result rather than equating campaign closure with process success.
Console¶
astraeus console [options]
| Option | Default | Meaning |
|---|---|---|
--host <host> |
127.0.0.1 |
Loopback bind host |
--port <port> |
8765 |
Local service port |
--workspace-root <directory> |
.astraeus_console |
Editable Console workspace |
--runs-root <directory> |
./runs |
Readable run root; repeat to expose more than one |
--no-browser |
off | Start without opening a browser |
--startup-timeout <seconds> |
product default | Bound startup health waiting |
The Console is local and single-user. CLI and RunSpec remain the complete authoring and execution interfaces.
Run Monitor¶
astraeus monitor serve [options]
| Option | Default | Meaning |
|---|---|---|
--runs-root <directory> |
runs |
Root containing core, sweep, and batch bundles |
--host <host> |
127.0.0.1 |
Bind host |
--port <port> |
8780 |
Service port |
--token-env <name> |
product default | Environment variable containing the bearer token |
--cors-origin <origin> |
none | Allowed browser origin; repeat as needed |
--allow-unsafe-no-token |
off | Permit an unauthenticated non-loopback bind |
Non-loopback use should be authenticated and protected by an appropriate private network, tunnel, or HTTPS proxy. The Monitor observes saved state, while run control remains with the CLI and operating-system process tools.
Resources¶
astraeus resources list [--json]
astraeus resources copy <empty-destination>
list reports the installed user resource sets. copy writes the complete
editable resource tree: bundled examples, component profiles, geography, and
communications profiles.
Reviews And Reports¶
astraeus review run --run-dir <run-directory> [--output <review.md>]
astraeus review campaign --result <result.json> [--request <request.yaml>] [--output <review.md>]
astraeus report scenario --run-dir <run-directory> [options]
Review commands create compact deterministic markdown. Scenario reports add a decision-level narrative and supported plot pack.
| Report option | Meaning |
|---|---|
--output <path> |
Choose the report markdown path |
--title <text> |
Set the report title |
--beam-source ue|gw |
Select user- or gateway-facing beam evidence |
--satellite-id <id> |
Focus supported plots on one satellite |
--max-orbit-sats <n> |
Bound satellites shown in orbit figures |
--scale <factor> |
Scale exported figures |
--skip-plot-export |
Write markdown without exporting figures |
Browser-path and write-timeout options exist for constrained plot-export
environments; use astraeus report scenario --help for their exact names.
User AI Skills¶
astraeus skills list [--json]
astraeus skills install (<skill-name> | --all) --target <target> [options]
astraeus skills verify (<skill-name> | --all) --target <target> [options]
Targets are codex, agents, gemini, and claude. --scope user|project
selects the normal install scope, --dest selects an explicit containing
directory, and --force intentionally replaces an installed skill during
installation.
The skills call or explain supported product workflows. Astraeus commands and deterministic review/report outputs remain directly usable on their own.