docs/user-guide/cli.md

0001 # AID2E CLI
0002
0003 ## Overview
0004
0005 The AID2E CLI provides commands for inspecting configuration files and running optimization workflows. See the [configuration guide](configuration.md) for supported configuration types.
0006
0007 ## CLI Commands
0008
0009 The available commands are:
0010
0011 ```text
0012 aid2e
0013 |-- describe     configuration summary
0014 |-- inspect      detailed configuration inspection
0015 |-- validate     configuration validation
0016 |-- optimize     config-driven optimization
0017 |-- list         available optimizers/templates/problems
0018 `-- version      framework version
0019 ```
0020
0021 ## Implemented Commands
0022
0023 ### `aid2e describe <config_file>`
0024
0025 **Purpose:** Quick, human-readable summary with automatic configuration type detection.
0026
0027 **Features:**
0028
0029 - Detects `full`, `problem`, `optimizer`, or `design` configurations.
0030 - Supports compact and detailed output.
0031 - Supports text, JSON, and YAML output.
0032
0033 **Usage:**
0034
0035 ```bash
0036 aid2e describe config.yml
0037 aid2e describe design.params --compact
0038 aid2e describe config.yml --format json
0039 aid2e describe config.yml --format yaml
0040 ```
0041
0042 ### `aid2e inspect <config_file>`
0043
0044 **Purpose:** Detailed inspection with optional section filtering.
0045
0046 **Features:**
0047
0048 - Filters with `--section [problem|optimizer|design|all]`.
0049 - Displays parameter bounds, choices, and constraints.
0050
0051 **Usage:**
0052
0053 ```bash
0054 aid2e inspect config.yml
0055 aid2e inspect config.yml --section optimizer
0056 aid2e inspect config.yml --section design
0057 aid2e inspect config.yml --section problem
0058 ```
0059
0060 ### `aid2e validate <config_file>`
0061
0062 **Purpose:** Validate configuration syntax and structure without executing it.
0063
0064 **Features:**
0065
0066 - Detects the configuration type.
0067 - Validates with the corresponding loader and model.
0068 - Reports validation errors.
0069 - Returns `0` on success, `1` when validation fails, and `2` for invalid CLI
0070   usage. Any other nonzero exit code also indicates failure.
0071
0072 **Usage:**
0073
0074 ```bash
0075 aid2e validate config.yml
0076 aid2e validate design.params
0077 aid2e validate problem.yml
0078 ```
0079
0080 ### `aid2e optimize <config_file>`
0081
0082 **Purpose:** Run config-driven optimization through the configured optimizer, scheduler, and workflow.
0083
0084 **Options:**
0085
0086 - `--validate-only`: Validate the configuration without executing it.
0087 - `-v`, `--verbosity`: Increase logging verbosity; may be repeated.
0088 - `--log FILE`: Write logs to a file.
0089 - `--workflow TEXT`: Select a workflow when the configuration declares more than one.
0090 - `--output DIRECTORY`: Override the configured output directory.
0091 - `--run-id TEXT`: Set the run directory name under the output directory. When
0092   omitted, AID2E uses a timestamp in `YYYYMMDD_HHMM` format.
0093
0094 **Usage:**
0095
0096 ```bash
0097 aid2e optimize workflow.yml
0098 aid2e optimize workflow.yml --validate-only
0099 aid2e optimize workflow.yml --workflow workflow_name
0100 aid2e optimize workflow.yml -vv --log output.log
0101 ```
0102
0103 ### `aid2e list [optimizers|templates|problems]`
0104
0105 **Purpose:** Display available optimizers, templates, and problem types.
0106
0107 **Usage:**
0108
0109 ```bash
0110 aid2e list
0111 aid2e list optimizers
0112 aid2e list templates
0113 aid2e list problems
0114 ```
0115
0116 ### `aid2e version`
0117
0118 **Purpose:** Display the installed AID2E framework version.
0119
0120 ```bash
0121 aid2e version
0122 ```
0123
0124 ## Verify the CLI
0125
0126 ```bash
0127 aid2e --help
0128 aid2e describe examples/dtlz2/configurations/dtlz2_ax_joblib.yml
0129 aid2e inspect examples/dtlz2/configurations/dtlz2_ax_joblib.yml
0130 aid2e validate examples/dtlz2/configurations/dtlz2_ax_joblib.yml
0131 aid2e optimize examples/dtlz2/configurations/dtlz2_ax_joblib.yml --validate-only
0132 aid2e list
0133 aid2e version
0134 ```
0135
0136 ## Run records
0137
0138 After each completed batch, `aid2e optimize` saves `optimization_results.json` (trial results) and `pareto_front.json` (Pareto solutions) under `<output>/<run-id>/`. Records include design parameters, objectives, objective errors, and trial metadata. Trial results also include status. Trial workflow outputs are kept under `trials/trial_<index>/`. Use `--log FILE` and verbosity settings to save trial progress.
0139
0140 Objective fields named `<objective>_err` are saved as `objective_errors`; they are not yet passed to Ax as standard errors. Penalized trials retain the penalty flag and failure reason in metadata, and count toward `max_failed_trials`.
0141
0142 `--validate-only` checks configuration loading; it does not execute jobs or verify the external software environment. Saved results do not provide automatic CLI resume.
0143
0144 See the [CLI and runtime notes](notes/cli.md) for module structure, planned commands, and runtime responsibilities.