Service Simulation via CLI
The Aethrix CLI can start simulated servers and monitor live traffic directly in the terminal. This is useful for integration testing, debugging simulated endpoints without the Studio UI, and including simulation in CI/CD pipelines.
The sim subcommands can also be written in the legacy flat form — aeth sim-start, aeth sim-import, aeth sim-export. Both forms are accepted; this page uses the nested aeth sim … form.
Listing Available Servers
Run without arguments to see all configured simulation servers:
aeth sim start
Output:
Available simulation servers:
1. HttpServer (Instance: Default) - HTTP Mock Server
2. SoapServer (Instance: Default) - SOAP Mock Server
Each server is identified by its short name (e.g., HttpServer), not its full display name.
HTTPS / TLS Prerequisite
If any server is configured with HTTPS or TLS enabled, a development certificate must be present before starting. Run aeth cert init once to create it. For CI/CD pipelines, where the administrator or keychain approval a store write needs cannot be granted, run aeth cert init --in-memory instead: servers then generate a throwaway certificate at each start (not persisted, not trusted, and a new fingerprint every run).
If no certificate is available, the server still starts and serves HTTP — the HTTPS endpoint is not created, and the reason appears in the server's diagnostics rather than failing the start.
Starting a Server
aeth sim start <server-name>
aeth sim start HttpServer
The server starts and the terminal displays its parameters (with password values masked as *****):
Server 'HttpServer' started. Press Ctrl+C to stop.
Parameters for server 'HttpServer':
- Port: 8080
- EnableHttps: true
Start All Servers
aeth sim start all
Starts every configured server simultaneously. Each server's status and parameters are logged.
Starting from a Configuration File
Start servers directly from an exported .mockconfig.json configuration — the import happens before the servers start, so responses attach to the handlers:
aeth sim start --config petstore.mockconfig.json
aeth sim start HttpServer --config petstore.mockconfig.json --strategy Overwrite
The --strategy option accepts the same strategies as aeth sim import (default Overwrite). The extension providing the API metadata must already be installed (aeth install <package>.pkg), otherwise the endpoints do not exist and the configuration cannot be applied.
Background Mode
On CI agents you don't want the simulation to block the terminal. --background starts the servers in a detached process and returns control once the servers are ready (up to 60s):
aeth sim start --background --config petstore.mockconfig.json
The detached process writes its state (pid, stop sentinel path, and the base URL of each started HTTP server) to %APPDATA%\AethrixTech\Aethrix\sim-start.json, and its console output to sim-start.json.log next to it. Stop it with:
aeth sim start --stop
--stop asks the detached process to shut down gracefully (it removes sim-start.json), and force-kills it if it does not exit within ~20 seconds.
Only one background simulation owner is allowed per machine, and it is mutually exclusive with the Aethrix daemon: if the daemon is running, aeth sim start --background refuses to start (and aeth daemon refuses while a background simulation runs). A second aeth sim start --background is refused the same way while one is already running: the message names the process and the addresses it serves, and the remedy is aeth sim start --stop — without that refusal the first server would keep holding its ports while its only record was replaced, leaving it unstopable.
Live Message Monitoring
While a server is running, incoming messages are displayed in real-time:
2026-05-04 14:32:15 | Service: GetOrders | Uri: /api/orders | Response: Default OK | Status: 200 | Delay: 0ms
2026-05-04 14:32:18 | Service: CreateOrder | Uri: /api/orders | Response: Created | Status: 201 | Delay: 150ms
Each log line shows:
- Timestamp — local date and time
- Service — operation name
- Uri — request path
- Response — name of the matched response
- Status — HTTP status code
- Delay — configured response delay in milliseconds
Stopping a Server
Press Ctrl+C to stop all running servers. Each server is stopped gracefully:
Server 'HttpServer' stopped.
Exporting Simulation Configurations
Export the saved responses of a simulation server to a .mockconfig.json file:
aeth sim export <output-file> --server <server-name> [--description <text>]
Only responses of services present in the server routes are exported. Run aeth sim start without arguments to list available servers:
aeth sim export payment-mock.json --server HttpServer
aeth sim export payment-mock.json --server HttpServer --description "Payment mock for CI"
The exported file can be re-imported with aeth sim import, shared with teammates, or committed to version control.
Importing Simulation Configurations
Import a previously exported .json configuration file:
aeth sim import <config-file> [--strategy <strategy>]
Import Strategies
| Strategy | Behavior |
|---|---|
Overwrite (default) | Per service in the file: delete all its responses, then load the file's. Services not in the file are left untouched. |
Merge | Replace responses with matching names and add new ones; responses not in the file are kept. |
FullReplace | Remove all responses for the server, then load the file's responses. |
Skip | "Fill only missing": only import responses for services that have none configured yet; services with existing responses are skipped entirely. |
aeth sim import ./simulation.json
aeth sim import ./simulation.json --strategy Merge
aeth sim import ./prod-simulation.json --strategy FullReplace
After import, the command displays a summary with per-service details:
Importing configuration into workspace...
12 handlers processed: 8 added, 3 updated, 1 skipped.
- GetOrders (/api/orders): Updated (3 => 5 responses)
- CreateOrder (/api/orders): Added (0 => 2 responses)
- GetInventory (/api/inventory): Skipped (already exists)
CI/CD Integration
Service simulation can be part of a CI/CD pipeline — start servers, run tests, and stop:
# Initialize ephemeral dev certificate for HTTPS servers (CI/CD)
aeth cert init --in-memory
# Start simulation servers in a detached background process
aeth sim start --background --config petstore.mockconfig.json
# Run tests against simulated endpoints
aeth run MyProject.aprj --env simulated --output ./results --junit
# Stop the background simulation servers
aeth sim start --stop
For production CI/CD use, consider using the Aethrix Studio UI to pre-configure servers and export the configuration. The CLI then imports it with --strategy FullReplace before starting.