Skip to main content

Command-Line Reference (aeth)

The aeth command-line tool runs test automation projects, imports collections, generates extensions, manages extensions and the package repository, controls service simulation, encrypts secrets, and authenticates with the Account Service — without opening Aethrix Studio. It is the primary integration point for CI/CD pipelines.

General Syntax​

aeth <command> [argument] [options]

Some commands use a nested subcommand form (aeth <group> <subcommand>). The following group aliases are also accepted:

GroupAliasSubcommands
sim—import, start
packagepkglist, search, view, download, upload
apiext—analyze, pack
test-designtdgenerate

Exit codes — a shell keeps only the low byte of a status, so every code below is under 128:

  • 0 — Success
  • 1 — The command ran and something it was asked to do failed (for run: test cases failed; for import, restore, cert, test-design and apiext: that operation failed)
  • 2 — The security gate tripped (--fail-on)
  • 3 — Bad or missing arguments, or an unknown verb; nothing was executed
  • 4 — The command started and could not complete (an exception, an unreadable project)
  • 5 — Credentials or a session were refused

The older numbers 400 and 500 are no longer returned: a POSIX shell turned them into 144 and 244, and 244 collides with the band a signal-killed process reports in.


Commands​

run — Run an Automation Project​

Run an Aethrix test automation project (.aprj file).

aeth run <project-file> [options]
OptionAliasDescription
<project-file>Path to the .aprj project file
--output <path>-o, --outDirectory where the test report will be saved
--env <name>-eName of the test environment to activate. Outside Default this also decides the host: every bound step sends to that environment's service endpoint instead of the URL stored on the step (Which URL a Request Uses)
--env-file <file>-efPath to a JSON file that overrides environment variables at runtime
--env-password <pwd>-epPassword for the environment override file (if encrypted)
--junit-jAlso generate a JUnit XML report in the output directory
--htmlAlso generate a self-contained HTML report (brand-themed, works offline)
--keepWait for ENTER before exiting (used when launched from Studio)
--ciForce CI output mode (no ANSI colors, fold groups, error annotations); auto-detected from environment when omitted
--ext <pkg-file>-x, --extensionLoad an additional .pkg extension for this run (repeatable)
--key <key>-k, --encryption-keyBase64-encoded encryption key for a password-protected project
--config <file>-cPath to an additional configuration file
--language <culture>-langReport language (e.g., en, fr, de, ja, ko, zh-Hans, zh-Hant); defaults to the system UI culture
--smart-stop <n>--smart-stop-thresholdOverride the data-driven smart-stop threshold for this run. After n consecutive same-kind environment (HTTP 502/503/504, timeout, connection refused) or authorization (HTTP 401/403) errors the run aborts. 0 disables smart-stop so all rows run. When omitted, the engine default or the Studio Settings value applies.
--progress-format ndjsonEmit machine-readable progress as one JSON object per line on stdout instead of the human console output. Intended for automation tooling; pair with --stop-file in daemon-style supervisors.
--stop-file <path>Poll the given sentinel file and cancel the run cooperatively as soon as it appears (checked every ~300 ms).
--export-contracts <dir>After the run, write one consumer contract file per test case that recorded interactions. Responses exist only during the run, so export must happen in the same session.

Examples:

# Basic run
aeth run MyProject.aprj

# With environment and JUnit report for CI/CD
aeth run MyProject.aprj --env staging --output ./reports --junit

# Protected project with encryption key
aeth run MyProject.aprj --key "base64encodedKey=="

# Load extra extension for this run only
aeth run MyProject.aprj --ext ./MyPlugin.pkg

# Offline HTML report in French
aeth run MyProject.aprj --html --language fr --output ./reports

# Data-driven run: abort after 3 consecutive same-kind environment/authorization errors
aeth run MyProject.aprj --env staging --smart-stop 3

# Data-driven run: disable smart-stop, always execute every row
aeth run MyProject.aprj --smart-stop 0

# Machine-readable progress for a supervisor script, cancellable via sentinel file
aeth run MyProject.aprj --progress-format ndjson --stop-file ./run.stop

analyze — Generate an Extension Package​

Analyse a service description and generate an API extension package (.pkg).

aeth analyze <service-description> [options]
OptionAliasDescription
<service-description>URL, local file path, or UNC path to the service description
--type <type>-tService type: OpenAPI, SOAP
--app-name <name>-anApplication name (used for classification/organization)
--service-name <name>-snService name (used for classification/organization)
--namespace <ns>-nsTarget C# namespace for generated types. Optional: defaults to EXT.<app>.<service> with both names reduced to identifier form, the same namespace the import wizard derives
--output <path>-o, --outOutput directory for the generated .pkg
--version <ver>Package version. Optional: defaults to a UTC timestamp revision yyyy.M.d.HHMM, identical whether the package is generated here or imported in Studio
--username <user>-uUsername or API key for authenticated spec endpoints
--password <pwd>-pPassword or API secret for authentication
--export-report <path>On failure, write a support bundle ZIP (support-bundle-<timestamp>.zip) to the given directory (or file path). Contains diagnostics, logs, compilation errors, and the specification/generated code. Credentials are always redacted.
--export-report-no-redactKeep credentials in the exported support bundle. DEBUG builds only — ignored in release builds.

Example:

aeth analyze https://api.example.com/swagger.json \
--type OpenAPI \
--app-name "OrderSystem" \
--service-name "OrderAPI" \
--namespace OrderSystem.OrderAPI \
--output ./extensions

Example — capture a support bundle when the import fails:

aeth analyze ./broken-spec.yaml --type OpenAPI ... --export-report ./bundles

See Import Diagnostics & Error Codes for what the bundle contains.


apiext analyze — Re-import an API Extension Project​

Re-import every application of an API Extension Project (*.aep — the document Studio's API Extension designer authors) from the spec URIs recorded inside it, then save the project.

aeth apiext analyze <project-file>

Notes:

  • The project file is rewritten only when every application re-imports successfully; a failure names the failed applications and leaves the file byte-identical.
  • One project can hold several applications, each with several services — a project group keeps its whole module surface in one document and distributes it as one versioned package.

apiext pack — Pack an API Extension Project​

Pack an API Extension Project into a distributable extension package. The project is analyzed from its recorded spec sources as part of packing, so the package always reflects the current spec. The package carries the project's metadata: package id, tags, visibility, icon, and changelog.

aeth apiext pack <project-file> [options]
OptionAliasDescription
<project-file>Path to the API Extension Project file (*.aep)
--output <dir>-o, --outDirectory to copy the produced .pkg into. Optional: without it the package is staged in temp and its path is printed
--version <ver>Package version for this build, overriding the project's AutoVersion date scheme. The project file itself is never rewritten by pack

Example — the CI loop for a project group whose module depends on another group's API:

# Group A's pipeline: refresh the project, pack under the pipeline's version, publish
aeth apiext analyze Module-A.aep
aeth apiext pack Module-A.aep --version 2.1.0 -o ./pkg
aeth publish ./pkg/Module-A-2.1.0.pkg

# Group B runs the same three steps for its own module

# On a test machine: A installs as the driver, B as the stub for service simulation
aeth install Module-A-2.1.0.pkg
aeth install Module-B-1.7.3.pkg

Exit codes follow the global table: 0 success, 1 a failed re-import or analysis (nothing is written), 3 a missing project file, 4 the project could not be read.

The flat spellings apiext-analyze and apiext-pack are accepted as well. aeth analyze remains the single-spec, stateless path — the two are separate on purpose.


import — Import a Collection​

Convert a Postman, Bruno, or Insomnia collection into an Aethrix Automation Project.

aeth import [<source>] [options]
OptionAliasDescription
<source>Path to the collection file or directory. Supported: Postman (.postman_collection.json), Bruno (directory or .bru), Insomnia (Insomnia_*.json / Insomnia_*.yaml)
--output <path>-o, -outOutput directory for the generated project; defaults to a folder named after the source
--openapi <spec>Path or URL of an explicit OpenAPI/Swagger spec to use when building the API extension
--no-openapiSkip OpenAPI extension generation entirely; all test steps use the Generic HTTP fallback
--flattenFlatten all collection folders into a single TestSuite
--format <format>Hint the import format: postman, bruno, insomnia (auto-detected when omitted)
--app-name <name>Application name for the generated extension
--service-name <name>Service name for the generated extension

Examples:

aeth import ./MyCollection.postman_collection.json
aeth import ./bruno-folder --flatten --output ./Imported
aeth import ./Insomnia.json --no-openapi
aeth import ./collection.json --format postman --app-name "Shop" --service-name "ShopAPI"

install — Install an Extension​

aeth install <extension-package-file>|<extension-id> [options]
OptionAliasDescription
--version <ver>Target version when installing from a repository; defaults to latest stable
--repo <path>-rRepository path (local folder or URL)
--force-fForce installation even if a version conflict exists

Examples:

aeth install ./MyExtension.1.0.0.pkg # From local file
aeth install my-extension-id # From repository (latest)
aeth install my-extension-id --version 2.1.0 # Specific version
aeth install ./MyExtension.1.0.0.pkg --force # Force reinstall

uninstall — Uninstall an Extension​

aeth uninstall <extension-name> [options]
OptionAliasDescription
--force-fSkip the confirmation prompt

list-extensions — List Installed Extensions​

aeth list-extensions

Alias: aeth list

Displays each installed extension's ID, name, version, developer, type, source, repository (if applicable), summary description, services list, pre-release flag, and error message (if the extension failed to load due to a missing protocol dependency).


publish — Publish to a Local Repository​

aeth publish <extension-package-file> [options]
OptionAliasDescription
<extension-package-file>Path to the .pkg file to publish
--repo <path>-rLocal repository folder path
note

aeth publish publishes to a local folder repository. Use aeth package upload for remote HTTP(S) repositories.


package list — List Repository Packages​

List packages available in the remote extension repository.

aeth package list [options]
OptionAliasDescription
--repo <url>-rRepository URL; defaults to the configured repository
--page <N>Page number (default: 1)
--page-size <N>--sizeItems per page (default: 20)
--pre-release--prereleaseInclude pre-release versions

Example output:

Repository: https://extensions.aethrixstudio.com
Page 1 — 12 package(s):
------------------------------------------------------------
Vendor.PaymentGateway v1.2.0
PCI-compliant payment processing extension
Developer: VendorName Downloads: 340

package search — Search the Repository​

aeth package search [<query>] [options]
OptionAliasDescription
<query>Search term (matches package ID, name, description, and tags)
--repo <url>-rRepository URL
--page <N>Page number
--page-size <N>--sizeItems per page
--pre-release--prereleaseInclude pre-release versions

package view — View Package Details​

aeth package view <package-id> [options]
OptionAliasDescription
<package-id>Package identifier
--version <ver>Specific version; defaults to latest
--repo <url>-rRepository URL

Displays: name, version, summary, developer, type, publish date, downloads, size, description, tags, and available versions.


package download — Download a Package​

aeth package download <package-id> [options]
OptionAliasDescription
<package-id>Package identifier
--version <ver>Specific version; defaults to latest
--output <path>-o, --outOutput directory or file path
--repo <url>-rRepository URL

package upload — Upload to Remote Repository​

aeth package upload <package-file> [options]
OptionAliasDescription
<package-file>Path to the .pkg file to upload
--repo <url>-rTarget repository URL

Uploading to a remote repository requires authentication. See Pipeline Authentication.


verify-contract — Verify Consumer Contracts​

aeth verify-contract [<contract-file>] --project <project-file> [options]
OptionAliasDescription
<contract-file>Verify one specific .contract file. Omit it to verify every contract in the provider project's contracts folder
--project <aprj>-pRequired. Provider automation project whose installed extensions define the service
--contract <name>Verify only the contract with this file or contract name
--key <key>-k, --encryption-keyEncryption key of a password-protected provider project
--env <name>-eTest environment of the provider project to run against
--url <url>Replace the URL recorded in every interaction (point at another host or port)
--strict <level>status, type or exact — overrides the strictness stored in the contracts

Each interaction is replayed through the provider project and checked at the selected strictness: HTTP status always, typed specification conformance at type and above, and exact body comparison at exact. An operation the provider no longer defines invalidates its contract and is reported before anything is sent. Exit 0 means every contract verified; exit 1 means an interaction failed or a contract was invalidated.

Contracts are ordinary files that live next to the project, so nothing is fetched at verification time: no repository login, no running service.

Examples:

# Verify every contract the provider project carries
aeth verify-contract --project ./Airline.aprj --env staging

# Verify one named contract
aeth verify-contract --project ./Airline.aprj --contract Booking-Flow

# Strictest comparison against a local build
aeth verify-contract ./Booking-Flow.contract --project ./Airline.aprj --strict exact \
--url http://localhost:8080/api/v1/pet/1

See Contract Testing for the full workflow.


edit — Change a Project from the Command Line​

aeth -edit <project-file> <command-id> [--parameter value]... [options]

A pipeline could run an automation project but could not change one. edit runs a single workspace command against a project file — the same commands the Studio command palette, the project tree, the AI assistant and the daemon share, so the rules are the same on every door: a rename that collides with a sibling is refused here exactly as it is refused in Studio, and so is a delete that a data-driven case's loop marker or another step's data-transfer rule still reads. On a refusal nothing is written to the project file.

CommandArguments
environment.add--name (required), --scope
environment.activate--environment (required), --scope
environment.variable.set--variable (required), --environment, --value, --scope
structure.item.rename--item_type, --old_name, --new_name (required), --suite_name, --test_case_name
structure.item.delete--item_type, --name (required), --suite_name, --test_case_name
structure.suite.add--suite_name (required)
structure.case.add--suite_name, --test_case_name (required), --data_driven
structure.step.send.add--suite_name, --test_case_name, --operation_id (required), --step_name, --insert_after, --url

--item_type is one of test_suite, test_case, test_step. --scope is project (default) or global; the two are isolated — a project environment is never used for a manual send and a global one never feeds a test run. A step inside a loop or a conditional is addressed by its own name, and --test_case_name names the case that holds it.

Creating is a command of its own, and no command creates two things at once: adding a case to a suite that is not there is refused, and the refusal names the command to run first. That is deliberate — a pipeline builds project shape in the order it says, rather than discovering a suite it never asked for. structure.step.send.add adds a Send Request step bound to --operation_id: the step arrives with the operation's own address and a request skeleton, so the only thing left to fill in is the data. Which machine the step reaches stays the environment's decision at run time — the step is not a photograph of one environment, and switching environments later does not rewrite it. --url stores an address exactly as you write it, for a step that must keep its own host; --insert_after places the step behind a named sibling instead of at the end of the case, because integration flows are built in business order.

OptionPurpose
--key, -kEncryption key of a password-protected project. It opens the file; it is never a command argument
--jsonPrint a single JSON document on stdout: command, success, message, failure, data, log

A flag written with dashes is read as the underscore name the command declares, so --item-type and --item_type mean the same argument. An argument a command does not declare is refused with the list it does accept, rather than silently dropped. Exit code 0 when the command did its work, 1 when it ran and was refused, 3 for a bad command line.

# Point a variable at another host before a run
aeth -edit Airline.aprj environment.variable.set \
--environment Staging --variable baseUrl --value https://staging.example.com

# Rename a step nested inside a loop
aeth -edit Airline.aprj structure.item.rename \
--item_type test_step --suite_name Smoke --test_case_name Login \
--old_name Step1 --new_name "Request token"

# Machine-readable answer for a pipeline to branch on
aeth -edit Airline.aprj structure.item.delete \
--item_type test_case --suite_name Smoke --name "Old flow" --json

# Build a case and its first request step in the order you say
aeth -edit Airline.aprj structure.suite.add --suite_name Smoke
aeth -edit Airline.aprj structure.case.add --suite_name Smoke --test_case_name Login
aeth -edit Airline.aprj structure.step.send.add --suite_name Smoke --test_case_name Login \
--operation_id "Swagger.PetStore.POST /pet/{petId}" --step_name "Add a pet"

sim start — Start a Simulation Server​

aeth sim start [<server-name>|all] [options]
OptionAliasDescription
<server-name>Short server name (e.g., HttpServer). Use all to start all configured servers. Omit to list available servers.
--instance <id>-iInstance ID for non-singleton servers
--config <file>-cImport a .mockconfig.json configuration before starting (extension metadata must be installed first)
--strategy <s>-sImport strategy for --config: Merge, FullReplace, Skip, or Overwrite (default: Overwrite)
--project <aprj>Project mode: load the project (side-loading its embedded extensions) and start the servers bound to the project's simulation context
--backgroundStart the servers in a detached background process and return once they are ready
--stopStop the background simulation process started with --background

Running without arguments lists available servers. While running, incoming messages are logged with local timestamps. Press Ctrl+C to stop. In background mode the process state (pid, stop sentinel, HTTP base URLs) is published to %APPDATA%\AethrixTech\Aethrix\sim-start.json; see Simulation CLI for the full recipe, and Daemon for the mutually exclusive daemon alternative.

aeth sim start # List available servers
aeth sim start HttpServer # Start a specific server
aeth sim start all # Start all configured servers

sim import — Import a Simulation Configuration​

aeth sim import <config-file> [options]
OptionAliasDescription
<config-file>Path to the .json simulation configuration file
--strategy <s>-sImport strategy: Merge, FullReplace, Skip, or Overwrite (default: Overwrite)

sim export — Export a Simulation Configuration​

Export the saved responses of a simulation server to a .mockconfig.json file:

aeth sim export <output-file> --server <server-name> [options]
OptionAliasDescription
<output-file>Destination path for the exported configuration
--server <name>Short server name to export (e.g., HttpServer)
--description <text>Optional description embedded in the exported file

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"

daemon — Run the Remote Control Daemon​

Start or stop the Aethrix daemon, a background service exposing a local HTTP control API (run automation projects, manage simulation servers, install extensions). See Daemon for the full API reference.

aeth daemon [options]
OptionAliasDescription
(default)Start in the background and return control once ready
--startSame as the default action
--foregroundRun attached to the terminal; Ctrl+C stops it
--stopGracefully shut down a running daemon
--workspace <path>-wCustom workspace root (default: the daemon state root)
--port <port>Fixed TCP port instead of an ephemeral one
aeth daemon # Start in background, returns immediately
aeth daemon --stop # Shut it down

One daemon is allowed per machine. Its discovery file (%APPDATA%\AethrixTech\Aethrix\daemon.json) carries the port and access token used by API callers.


encrypt — Encrypt a Secret​

Encrypt a plain-text secret using AES-GCM and output the Base64-encoded ciphertext and IV.

aeth encrypt [<secret>] [options]
OptionAliasDescription
<secret>Plain-text value to encrypt. If omitted, prompts securely.
--key <key>-kBase64-encoded encryption key. If omitted, the machine-stored key is used.

Output:

Encrypted Secret: <base64 ciphertext>
IV: <base64 IV>

For portable secrets across machines or CI/CD, always supply an explicit --key.


rotate-credentials — Rotate Project Encryption Key​

Re-encrypt all passwords in a project with a new key.

aeth rotate-credentials <project-file> --new-key <new-key> [options]
OptionAliasDescription
<project-file>Path to the .aprj project file
--new-key <key>-nkNew Base64-encoded encryption key — required
--key <key>-kCurrent encryption key (required for password-protected projects)
--output <path>-o, --outDirectory to save the rotated project; overwrites original if omitted

login — Authenticate with Account Service​

aeth login [options]
OptionAliasDescription
--user <email>-uEmail address for interactive (or non-interactive) login
--password <pwd>-pPassword for interactive login
--ci-token <pat>-ctPersonal Access Token for CI/CD non-interactive login
--region <region>-regTarget region: global (default), eu, us, cn. In debug builds only: staging, local

If no credentials are provided, prompts interactively. With --ci-token, authenticates via PAT and does not persist local state. The AETHRIX_CI_TOKEN environment variable is checked as a fallback for the CI token.

aeth login # Interactive
aeth login -u alice@corp.com -p secret # Non-interactive
aeth login --ci-token "$AETHRIX_CI_TOKEN" # CI/CD
aeth login --region eu --ci-token "$MY_PAT" # Specific region

logout — Sign Out​

aeth logout

Clears the locally persisted session (refresh token) and signs out from the Account Service.


cert — Manage Development TLS Certificate​

Manage the self-signed development certificate used by service simulation servers (HTTP and gRPC) for HTTPS/TLS.

aeth cert <action> [options]
ActionDescription
checkShow current certificate status (exists, subject, thumbprint, expiry, trusted, expiring)
initCreate or load a development certificate
trustTrust the certificate. Windows: adds it to the CurrentUser Root store (requires an elevated prompt). macOS: records per-user trust settings silently, falling back to an admin authorization dialog for system-wide trust. Linux: adds it to the per-user trust store used by .NET.
renewReplace the current certificate with a new one
removeDelete the certificate from the system store
OptionApplies ToDescription
--in-memory / --meminitSwitch servers to ephemeral certificates: instead of the stored certificate, each server generates its own self-signed one at start-up. Intended for CI/CD and headless runs, where writing to the system certificate store would ask for administrator or keychain approval nobody can give. The mode is remembered and applies to later runs until aeth cert init is run again; to control a single run instead, set AETHRIX_HTTPS_EPHEMERAL=1 (or =0 to force it off). An ephemeral certificate is not persisted, not trusted, changes its fingerprint on every start and belongs to one process — enough for a test that drives its own server, not for a browser you want to stop warning.

Examples:

aeth cert check # Show certificate status
aeth cert init # Create or load a development certificate
aeth cert init --in-memory # Switch servers to ephemeral certificates (CI/CD)
aeth cert trust # Trust the certificate (Windows: elevated prompt)
aeth cert renew # Renew an expiring certificate
aeth cert remove # Remove the certificate

If a server is configured for HTTPS but no certificate can be obtained, the server still starts and serves HTTP: the HTTPS endpoint is simply not created, and the reason is reported in the server's Diagnostics — check there first when an HTTPS port refuses connections. Create a certificate with aeth cert init, or use aeth cert init --in-memory for CI. aeth cert check reports whether the managed certificate exists, or that ephemeral mode is on.


license — Manage License and Access Tokens​

aeth license # Show current license info
aeth license --show # Same as above
aeth license --create-token <name> # Create a Personal Access Token
aeth license --revoke-token <token-id> # Revoke a Personal Access Token
aeth license --list-tokens # List your Personal Access Tokens
OptionAliasDescription
--show-showShow the active license and account (online or from the 7-day offline cache)
--create-token <name>-ctCreate a new Personal Access Token with the given name; the token value is shown once
--revoke-token <id>-rtRevoke the Personal Access Token with the given ID
--list-tokens-ltList all Personal Access Tokens (ID, name, created, expires, last used)
note

--create-token, --revoke-token, and --list-tokens require an authenticated session (aeth login). The created token is only displayed once — store it securely and use it for CI/CD with aeth login --ci-token <token>.


test-design generate — Generate Test Combinations​

Generate test combinations from a .td.yaml test design configuration file and write them to a CSV file or stdout.

aeth test-design generate [<config.td.yaml>] [options]
OptionAliasDescription
<config.td.yaml>Path to the .td.yaml test design configuration file
--output <file>-oOutput CSV file; if omitted, the combinations are printed to stdout

Examples:

aeth test-design generate design.td.yaml
aeth test-design generate design.td.yaml --output combinations.csv

version — Show Version​

aeth version

Alias: aeth ver. Displays version number, build date, product info, copyright, and target .NET framework.


help — Show Help​

aeth help

Global Options Summary​

OptionAliasApplies To
--output <path>-o, --outrun, analyze, package download, rotate-credentials, import, test-design generate
--repo <path>-rinstall, publish, package list/search/view/download/upload
--force-finstall, uninstall
--key <key>-krun, rotate-credentials, encrypt
--version <ver>install, analyze, package view, package download
--junit-jrun
--htmlrun
--cirun
--ext <pkg>-x, --extensionrun
--smart-stop <n>--smart-stop-thresholdrun
--in-memory--memcert init
--instance <id>-isim start
--strategy <s>-ssim import

See Also​