improved version management (#67)

* improved version management

* Documentation updated

Author: Hahihula

.gitignore

@@ -14,6 +14,7 @@ dist-ssr
 
 # mdbook
 /docs/book
+/docs/theme
 
 # Editor directories and files
 .vscode/*

docs/src/SUMMARY.md

@@ -9,6 +9,7 @@
 - [Configuration](./configuration.md)
   - [GUI Configuration](./gui_configuration.md)
   - [CLI Configuration](./cli_configuration.md)
+  - [CLI Commands](./cli_commands.md)
 - [After Installing](./after_installing.md)
 - [Headless Usage](./headless_usage.md)
 - [FAQ](./faq.md)

docs/src/cli_commands.md

@@ -0,0 +1,173 @@
+# CLI Commands
+
+The ESP-IDF Installation Manager provides a comprehensive command-line interface with various commands to manage your ESP-IDF installations. This document details all available commands and their usage.
+
+## Available Commands
+
+```bash
+eim [OPTIONS] [COMMAND]
+```
+
+### Global Options
+
+These options can be used with any command:
+
+- `-l, --locale <LOCALE>`: Set the language for the wizard (en, cn)
+- `-v, --verbose`: Increase verbosity level (can be used multiple times)
+- `--log-file <LOG_FILE>`: File in which logs will be stored (default: eim.log)
+- `-h, --help`: Print help information
+- `-V, --version`: Print version information
+
+### Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `install` | Install ESP-IDF versions |
+| `wizard` | Run the ESP-IDF Installer Wizard (interactive mode) |
+| `list` | List installed ESP-IDF versions |
+| `select` | Select an ESP-IDF version as active |
+| `rename` | Rename a specific ESP-IDF version |
+| `remove` | Remove a specific ESP-IDF version |
+| `purge` | Purge all ESP-IDF installations |
+| `import` | Import existing ESP-IDF installation using tools_set_config.json |
+| `discover` | Discover available ESP-IDF versions (not implemented yet) |
+
+## Command Details
+
+### Install Command
+
+Non-interactive installation of ESP-IDF versions. This command runs in non-interactive mode by default.
+
+```bash
+eim install [OPTIONS]
+```
+
+Options:
+- `-p, --path <PATH>`: Base path to which all files and folders will be installed
+- `--esp-idf-json-path <ESP_IDF_JSON_PATH>`: Absolute path to save eim_idf.json file
+- `-c, --config <FILE>`: Path to configuration file
+- `-t, --target <TARGET>`: Target platforms (comma-separated)
+- `-i, --idf-versions <IDF_VERSIONS>`: ESP-IDF versions to install (comma-separated)
+- `--tool-download-folder-name <TOOL_DOWNLOAD_FOLDER_NAME>`: Name of the folder for tool downloads
+- `--tool-install-folder-name <TOOL_INSTALL_FOLDER_NAME>`: Name of the folder for tool installations
+- `--idf-tools-path <IDF_TOOLS_PATH>`: Path to idf_tools.py file relative from ESP-IDF installation folder
+- `--tools-json-file <TOOLS_JSON_FILE>`: Path to tools.json file relative from ESP-IDF installation folder
+- `-n, --non-interactive <NON_INTERACTIVE>`: Run in interactive mode if set to false (default is true for non-interactive mode)
+- `-m, --mirror <MIRROR>`: URL for tools download mirror to be used instead of github.com
+- `--idf-mirror <IDF_MIRROR>`: URL for ESP-IDF download mirror to be used instead of github.com
+- `-r, --recurse-submodules <RECURSE_SUBMODULES>`: Should the installer recurse into submodules of the ESP-IDF repository (default true)
+- `-a, --install-all-prerequisites <INSTALL_ALL_PREREQUISITES>`: Should the installer attempt to install all missing prerequisites (Windows only)
+- `--config-file-save-path <CONFIG_FILE_SAVE_PATH>`: Path to save the configuration file
+- `--idf-features <IDF_FEATURES>`: Comma-separated list of additional IDF features (ci, docs, pytests, etc.) to be installed with ESP-IDF
+
+### Wizard Command
+
+Run the interactive ESP-IDF Installer Wizard.
+
+```bash
+eim wizard [OPTIONS]
+```
+
+The wizard command accepts the same options as the install command but runs in interactive mode, guiding you through the installation process with a series of prompts.
+
+### List Command
+
+List all installed ESP-IDF versions.
+
+```bash
+eim list
+```
+
+This command displays all ESP-IDF versions installed on your system, with the currently selected version marked.
+
+### Select Command
+
+Select an ESP-IDF version as active.
+
+```bash
+eim select [VERSION]
+```
+
+If `VERSION` is not provided, the command will prompt you to select from available versions. Selecting version means setting the `idfSelectedId` in the `eim_idf.json` file. This is used by the IDEs to know which of the IDF versions you prefer to use.
+
+### Rename Command
+
+Rename a specific ESP-IDF version.
+
+```bash
+eim rename [VERSION] [NEW_NAME]
+```
+
+If `VERSION` is not provided, the command will prompt you to select from available versions.
+If `NEW_NAME` is not provided, the command will prompt you to enter a new name.
+
+### Remove Command
+
+Remove a specific ESP-IDF version.
+
+```bash
+eim remove [VERSION]
+```
+
+If `VERSION` is not provided, the command will prompt you to select from available versions.
+
+### Purge Command
+
+Purge all ESP-IDF installations.
+
+```bash
+eim purge
+```
+
+This command removes all known ESP-IDF installations from your system.
+
+### Import Command
+
+Import an existing ESP-IDF installation using a tools_set_config.json file.
+
+```bash
+eim import [PATH]
+```
+
+If `PATH` is not provided, the command will inform you that no config file was specified.
+
+### Discover Command
+
+Discover available ESP-IDF versions (not implemented yet).
+
+```bash
+eim discover
+```
+
+This command is planned to discover ESP-IDF installations on your system but is not yet implemented.
+
+## Examples
+
+```bash
+# Install ESP-IDF v5.3.2 non-interactively (default behavior)
+eim install -i v5.3.2
+
+# Install ESP-IDF v5.3.2 in interactive mode
+eim install -i v5.3.2 -n false
+
+# Run the interactive wizard
+eim wizard
+
+# List installed versions
+eim list
+
+# Select a specific version
+eim select v5.3.2
+
+# Rename a version
+eim rename v5.3.2 "ESP-IDF 5.3.2 Stable"
+
+# Remove a specific version
+eim remove v5.3.2
+
+# Purge all installations
+eim purge
+
+# Import from a config file
+eim import /path/to/tools_set_config.json
+```

docs/src/cli_configuration.md

@@ -7,29 +7,38 @@ The command-line interface supports multiple configuration methods with the foll
 3. Configuration files
 4. Default values
 
-## Command Line Arguments
+## Command Structure
+
+ESP-IDF Installation Manager (EIM) now uses a command-based structure with the following format:
 
-View all available options with:
 ```bash
-eim --help
+eim [OPTIONS] [COMMAND] [COMMAND_OPTIONS]
 ```
 
-Common arguments include:
+For example:
 ```bash
-# Install specific IDF version
-eim -i v5.3.2
+# Install ESP-IDF with specific version
+eim install -i v5.3.2
+
+# Run the interactive wizard
+eim wizard
+
+# List installed versions
+eim list
+```
 
-# Set installation path
-eim -p /opt/esp-idf
+For a complete list of available commands and their options, see [CLI Commands](./cli_commands.md).
 
-# Non-interactive installation
-eim -n true
+## Command Line Arguments
 
-# Use configuration file
-eim --config path/to/config.toml
+View all available options with:
+```bash
+eim --help
+```
 
-# Install prerequisites (Windows only)
-eim -a true
+For help with a specific command:
+```bash
+eim <command> --help
 ```
 
 ## Environment Variables
@@ -43,7 +52,7 @@ Example:
 ```bash
 export ESP_PATH="/opt/esp-idf"
 export ESP_IDF_VERSION="v5.3.2"
-eim
+eim install
 ```
 
 ## Configuration Files
@@ -70,22 +79,25 @@ install_all_prerequisites = false
 
 Load a configuration file:
 ```bash
-eim --config path/to/config.toml
+eim install --config path/to/config.toml
 ```
 
 ## Headless Configuration
 
-For automated installations, combine non-interactive mode with other configuration options:
+For automated installations, use the `install` command which runs in non-interactive mode by default:
 
 ```bash
 # Basic headless installation
-eim -n true
+eim install
 
 # Headless with specific version and path
-eim -n true -i v5.3.2 -p /opt/esp-idf
+eim install -i v5.3.2 -p /opt/esp-idf
 
 # Headless with config file
-eim -n true --config path/to/config.toml
+eim install --config path/to/config.toml
+
+# To run in interactive mode, explicitly set non-interactive to false
+eim install -n false
 ```
 
-See [Headless Usage](./headless_usage.md) for more details about automated installations. 
+See [Headless Usage](./headless_usage.md) for more details about automated installations.

docs/src/headless_usage.md

@@ -4,37 +4,58 @@ The ESP-IDF Installation Manager supports headless mode for automated installati
 
 ## Basic Headless Usage
 
-To run the installer in headless mode, use the `-n` or `--non-interactive` flag:
+The `install` command runs in non-interactive (headless) mode by default. You don't need to explicitly specify the `-n` or `--non-interactive` flag:
 
 ```bash
-eim -n true
+eim install
 ```
 
-This will install the latest version of ESP-IDF with default settings.
+This will install the latest version of ESP-IDF with default settings in non-interactive mode.
+
+If you want to run the install command in interactive mode, you would need to explicitly specify:
+
+```bash
+eim install -n false
+```
 
 ## Advanced Headless Usage
 
 ### Custom Installation Options
 
-Combine the non-interactive flag with other parameters:
+Use the install command with various parameters:
 
 ```bash
 # Install specific version
-eim -n true -i v5.3.2
+eim install -i v5.3.2
 
 # Custom installation path
-eim -n true -p /opt/esp-idf
+eim install -p /opt/esp-idf
 
 # Install prerequisites (Windows only)
-eim -n true -a true
+eim install -a true
 ```
 
 ### Using Configuration Files
 
 For reproducible installations, use a configuration file:
 
 ```bash
-eim -n true --config path/to/config.toml
+eim install --config path/to/config.toml
+```
+
+### Managing Installations
+
+You can also use other commands:
+
+```bash
+# List installed versions
+eim list
+
+# Select a specific version
+eim select v5.3.2
+
+# Remove a specific version
+eim remove v5.3.2
 ```
 
 ## CI/CD Integration
@@ -86,7 +107,7 @@ RUN set -x && \
     rm /tmp/eim.zip
 
 # Install ESP-IDF
-RUN eim -n true -i v5.3.2
+RUN eim install -i v5.3.2
 
 WORKDIR /workspace
 ENTRYPOINT ["/bin/bash", "-c", "source /root/.espressif/activate_idf_v5.3.2.sh && $0 $@"]
@@ -98,4 +119,4 @@ ENTRYPOINT ["/bin/bash", "-c", "source /root/.espressif/activate_idf_v5.3.2.sh &
 2. **Configuration Files**: Use configuration files for complex setups to ensure consistency
 3. **Error Handling**: In CI/CD environments, ensure proper error handling and logging
 4. **Prerequisites**: On Windows, use `-a true` to automatically install prerequisites
-5. **Path Management**: Use absolute paths to avoid any ambiguity 
+5. **Path Management**: Use absolute paths to avoid any ambiguity