### Install IDA Pro with Download ID Source: https://hcli.docs.hex-rays.com/user-guide/installing-ida Install IDA Pro by specifying the download ID directly, combining download and installation into a single command. This example also uses `--dry-run` for preview. ```bash $ hcli ida install --set-default --license-id 96-0000-0000-01 --download-id release/9.2/ida-pro/ida-pro_92_armmac.app.zip --dry-run Getting download URL for: release/9.2/ida-pro/ida-pro_92_armmac.app.zip Starting download of release/9.2/ida-pro/ida-pro_92_armmac.app.zip... Using cached file: /Users/user/.hcli/cache/ida-pro_92_armmac.app.zip Download complete! File saved to: ``` -------------------------------- ### Setup Development Environment with uv Source: https://hcli.docs.hex-rays.com/development/setup Install development dependencies using the uv package manager. This is the recommended method. ```bash uv sync --extra dev ``` -------------------------------- ### Perform Unattended IDA Installation Source: https://hcli.docs.hex-rays.com/user-guide/installing-ida Install IDA Pro non-interactively using the downloaded installer. This example includes options to set the installation as default, accept the EULA, and uses `--dry-run` to preview actions without making changes. ```bash $ hcli ida install --set-default --accept-eula --license-id 96-0000-0000-01 ida-pro_92_armmac.app.zip --dry-run Installation details: Installer: /Users/user/code/hex-rays/ida-hcli/ida-pro_92_armmac.app.zip Destination: /Applications/IDA Professional 9.2.app License: 96-0000-0000-01 Set as default: Yes Dry run mode - no changes will be made Would perform the following actions: 1. Extract installer to: /Applications/IDA Professional 9.2.app 2. Install license to: /Applications/IDA Professional 9.2.app/Contents/MacOS 3. Update default IDA path in: /Users/user/.idapro/ida-config.json 4. Accept EULA ``` -------------------------------- ### Setup Development Environment with pip Source: https://hcli.docs.hex-rays.com/development/setup Alternatively, set up a virtual environment and install development dependencies using pip. ```bash python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e ".[dev]" ``` -------------------------------- ### Install and Test Plugin Across IDA Versions Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Set the target IDA installation directory and install the plugin. Then, launch the specific IDA version to test compatibility. ```bash # Set specific IDA installation export HCLI_CURRENT_IDA_INSTALL_DIR="/Applications/IDA Professional 9.1.app" hcli plugin install /path/to/your-plugin # Test in IDA 9.1 /Applications/IDA\ Professional\ 9.1.app/Contents/MacOS/ida64 # Repeat for IDA 9.2 export HCLI_CURRENT_IDA_INSTALL_DIR="/Applications/IDA Professional 9.2.app" hcli plugin install /path/to/your-plugin --force # Test in IDA 9.2 /Applications/IDA\ Professional\ 9.2.app/Contents/MacOS/ida64 ``` -------------------------------- ### IDA Install Command Help Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Displays the usage and available options for the `hcli ida install` command, which installs IDA unattended. ```bash $ hcli ida install --help Usage: hcli ida install [OPTIONS] [INSTALLER] Installs IDA unattended. ╭─ Options ──────────────────────────────────────────────────────────────────────────╮ │ --yes -y Auto-accept confirmation prompts │ │ --dry-run Show what would be done without actually installing │ │ --set-default Mark this IDA installation as the default │ │ --accept-eula -a Accept EULA │ │ --install-dir -i TEXT Install dir │ │ --license-id -l TEXT License ID (e.g., 96-0000-0000-01) │ │ --download-id -d TEXT Installer slug │ │ --help Show this message and exit. │ ╰────────────────────────────────────────────────────────────────────────────────────╯ ``` -------------------------------- ### Verify HCLI Setup Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Run this command to verify your HCLI installation and authentication. ```bash hcli whoami You are logged in as user@example.com using an API key from HCLI_API_KEY environment variable ``` -------------------------------- ### Install an IDA Plugin Source: https://hcli.docs.hex-rays.com/user-guide/plugin-manager Install a specific plugin using 'hcli plugin install '. The command confirms the installation and version. ```bash ❯ hcli plugin install hint-calls Installed plugin: hint-calls==0.1.3 ``` -------------------------------- ### Install Plugin from Release URL Source: https://hcli.docs.hex-rays.com/reference/hex-rays-guide-for-suggesting-changes Install a plugin by providing the URL to its release zip file. ```bash hcli plugin install https://.../url/to/release/zip ``` -------------------------------- ### Basic Dockerfile for HCLI Source: https://hcli.docs.hex-rays.com/how-to/use-hcli-in-docker Sets up a minimal Docker image with HCLI installed. Includes dependency installation, HCLI download, and verification. ```Dockerfile FROM python:3.11-slim # Install dependencies RUN apt-get update && \ apt-get install -y curl unzip && \ rm -rf /var/lib/apt/lists/* # Install HCLI RUN curl -fsSL https://hcli.docs.hex-rays.com/install | sh # Set environment variables ENV PATH="/root/.local/bin:${PATH}" # Verify installation RUN hcli --version WORKDIR /workspace CMD ["hcli", "--help"] ``` -------------------------------- ### IDA Pro Installation Details Source: https://hcli.docs.hex-rays.com/user-guide/installing-ida Shows the details of a planned IDA Pro installation, including installer path, destination, license, and default settings. This output is from a dry run, so no changes are made. ```text /var/folders/55/f4jb4y1d6b74cdrp_gp45hlw0000gn/T/ida-pro_92_armmac.app.zip Successfully downloaded 1 file(s) Installation details: Installer: /var/folders/55/f4jb4y1d6b74cdrp_gp45hlw0000gn/T/ida-pro_92_armmac.app.zip Destination: /Applications/IDA Professional 9.2.app License: 96-0000-0000-01 Set as default: Yes Dry run mode - no changes will be made Would perform the following actions: 1. Extract installer to: /Applications/IDA Professional 9.2.app 2. Install license to: /Applications/IDA Professional 9.2.app/Contents/MacOS 3. Update default IDA path in: /Users/user/.idapro/ida-config.json 4. Accept EULA ``` -------------------------------- ### Download and Install IDA in One Command Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Downloads and installs a specific IDA version using a download ID, setting it as the default installation. This command includes a dry-run option to preview actions. ```bash $ hcli ida install --set-default --license-id 96-0000-0000-01 --download-id release/9.2/ida-pro/ida-pro_92_armmac.app.zip --dry-run Getting download URL for: release/9.2/ida-pro/ida-pro_92_armmac.app.zip Starting download of release/9.2/ida-pro/ida-pro_92_armmac.app.zip... Using cached file: /Users/user/.hcli/cache/ida-pro_92_armmac.app.zip Download complete! File saved to: /var/folders/55/f4jb4y1d6b74cdrp_gp45hlw0000gn/T/ida-pro_92_armmac.app.zip Successfully downloaded 1 file(s) Installation details: Installer: /var/folders/55/f4jb4y1d6b74cdrp_gp45hlw0000gn/T/ida-pro_92_armmac.app.zip ``` -------------------------------- ### Install License Automatically Source: https://hcli.docs.hex-rays.com/user-guide/licenses Installs a license by automatically downloading and configuring it. Ensure IDA Pro is not running during installation. ```bash hcli license install ``` -------------------------------- ### Install License Manually Source: https://hcli.docs.hex-rays.com/user-guide/licenses Installs a license from a local file. Provide the full path to your license file. ```bash hcli license install --file /path/to/license.lic ``` -------------------------------- ### Install an IDA Pro Plugin Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Installs a specific IDA Pro plugin. If multiple repositories contain a plugin with the same name, you may need to qualify the installation with the repository URL. ```bash $ hcli plugin install ipyida Installed plugin: ipyida==2.3 $ hcli plugin install ida-chat@https://github.com/HexRaysSA/ida-chat-plugin Installed plugin: ida-chat==1.0.0 ``` -------------------------------- ### Create Development Build with uv Source: https://hcli.docs.hex-rays.com/development/setup Install the project in editable mode for development using uv. ```bash uv pip install -e . ``` -------------------------------- ### Install Plugin from Local Directory or ZIP Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Install your plugin locally using HCLI, either from its source directory or a packaged ZIP file. This step is crucial for runtime testing. ```bash # Install from directory hcli plugin install /path/to/your-plugin ``` ```bash # Or from ZIP hcli plugin install ./your-plugin-v1.0.0.zip ``` -------------------------------- ### Install Specific Plugin Version with Repository Source: https://hcli.docs.hex-rays.com/user-guide/plugin-manager Install a plugin by specifying its name, version, and repository URL to resolve ambiguity or select a particular version. ```bash ❯ hcli plugin install ida-chat@https://github.com/HexRaysSA/ida-chat-plugin ❯ hcli plugin install ida-chat==1.0.0@https://github.com/HexRaysSA/ida-chat-plugin ``` -------------------------------- ### Download IDA Installer Interactively Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Interactively navigate through available releases and select an IDA Pro installer to download. The CLI caches downloaded files for reuse. ```bash $ hcli download Fetching available downloads... Current path: / ? Select an item to navigate or download: iles/release Current path: /release ? Select an item to navigate or download: iles/9.2 Current path: /release/9.2 ? Select an item to navigate or download: iles/ida-pro Current path: /release/9.2/ida-pro ? Select an item to navigate or download: (Use arrow keys, type to filter) iles/ Go back iles/ License Server 9.2 (hexlicsrv92_x64linux.run) » iles/ IDA Pro Mac Apple Silicon 9.2 (ida-pro_92_armmac.app.zip) iles/ Lumina Server 9.2 (lumina92_x64linux.run) iles/ Teams Server 9.2 (hexvault92_x64linux.run) iles/ IDA Pro Windows 9.2 (ida-pro_92_x64win.exe) iles/ IDA Pro Linux 9.2 (ida-pro_92_x64linux.run) iles/ IDA Pro Mac Intel 9.2 (ida-pro_92_x64mac.app.zip) Getting download URL for: release/9.2/ida-pro/ida-pro_92_armmac.app.zip Starting download of release/9.2/ida-pro/ida-pro_92_armmac.app.zip... Using cached file: /Users/user/.hcli/cache/ida-pro_92_armmac.app.zip Download complete! File saved to: ida-pro_92_armmac.app.zip Successfully downloaded 1 file(s) $ ls -lah *.app.zip -rw-r--r--@ 1 user staff 539M Sep 12 13:47 ida-pro_92_armmac.app.zip ``` -------------------------------- ### Check Installed Plugin Status Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Verify that your plugin has been successfully installed and its Python dependencies are listed. This command shows installed plugins and their versions. ```bash hcli plugin status ``` -------------------------------- ### Install Local Build Source: https://hcli.docs.hex-rays.com/development/setup Install the locally built package from the dist directory using pip. ```bash pip install dist/ida_hcli-*.whl ``` -------------------------------- ### GitHub Actions Workflow to Install IDA Pro Source: https://hcli.docs.hex-rays.com/advanced/ci-cd-integration This GitHub Actions workflow demonstrates installing HCLI and IDA Pro on an Ubuntu runner. It uses secrets for API keys and license IDs. ```yaml name: Test Plugin on: push: branches: [ main ] pull_request: branches: [ main ] jobs: test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.11' - name: Install HCLI run: | pip install ida-hcli - name: Authenticate HCLI env: HCLI_API_KEY: ${{ secrets.HCLI_API_KEY }} run: | hcli whoami - name: Install IDA Pro env: HCLI_API_KEY: ${{ secrets.HCLI_API_KEY }} run: | hcli ida install \ --yes \ --accept-eula \ --set-default \ --license-id ${{ secrets.IDA_LICENSE_ID }} \ --download-id release/9.2/ida-pro/ida-pro_92_x64linux.run ``` -------------------------------- ### Install Plugin from a Plugin Bundle (Offline) Source: https://hcli.docs.hex-rays.com/reference/plugin-bundle-spec Installs a specific plugin from a plugin bundle archive on an offline machine. The `--repo` option points to the bundle, and HCLI uses its contents for installation. ```bash hcli plugin --repo ./malware-vm-tools-2026-04.hcli-plugin-bundle.zip install hint-calls ``` -------------------------------- ### Verify HCLI Installation Source: https://hcli.docs.hex-rays.com/getting-started/installation Run this command after installation to confirm that HCLI is installed correctly and to check its version. ```shell hcli --version ``` -------------------------------- ### Quick Start: Upload, Share Code, and Delete Source: https://hcli.docs.hex-rays.com/how-to/share-files-with-support A concise workflow for uploading a file, obtaining its share code, and subsequently deleting it after resolution. ```bash hcli share put crash_sample.idb --acl authenticated ``` ```bash hcli share delete abc123 ``` -------------------------------- ### Download HCLI Installer (Windows) Source: https://hcli.docs.hex-rays.com/ Downloads the HCLI installation script to the local machine for later execution. ```powershell iwr https://hcli.docs.hex-rays.com/install.ps1 -OutFile install.ps1 ``` -------------------------------- ### Pip Install Command with Offline Mode Source: https://hcli.docs.hex-rays.com/reference/plugin-bundle-spec Example of the pip install command used by HCLI when the `--offline` flag is passed. This command restricts pip to only use local sources specified by `--find-links` and `--no-index`. ```bash python -m pip install \ --isolated \ --disable-pip-version-check \ --no-cache-dir \ [--no-index] # only when --offline is passed \ --find-links \ ``` -------------------------------- ### Test Plugin Installation on Clean IDA Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Temporarily move existing plugins to simulate a clean IDA installation for testing purposes. ```bash # Backup existing plugins mv ~/.idapro/plugins ~/.idapro/plugins.bak # Test plugin installation hcli plugin install /path/to/plugin # Restore mv ~/.idapro/plugins.bak ~/.idapro/plugins ``` -------------------------------- ### Example Settings Configuration Source: https://hcli.docs.hex-rays.com/reference/plugin-packaging-and-format Defines settings for a plugin, including key, type, requirement, default values, and display information. Use 'prompt: false' for advanced settings with sensible defaults. ```json { "settings": [ { "key": "api_key", "type": "string", "required": true, "name": "API Key", "documentation": "Your API key from https://example.com/keys" }, { "key": "cache_size", "type": "string", "required": false, "default": "100", "name": "Cache Size", "documentation": "Maximum number of cached items", "prompt": false } ] } ``` -------------------------------- ### Install IDA Unattended with Dry Run Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Performs a dry run of the unattended IDA installation, showing the actions that would be taken without making any changes. This includes extracting the installer, installing the license, and updating the default IDA path. ```bash $ hcli ida install --set-default --accept-eula --license-id 96-0000-0000-01 ida-pro_92_armmac.app.zip --dry-run Installation details: Installer: /Users/user/code/hex-rays/ida-hcli/ida-pro_92_armmac.app.zip Destination: /Applications/IDA Professional 9.2.app License: 96-0000-0000-01 Set as default: Yes Dry run mode - no changes will be made Would perform the following actions: 1. Extract installer to: /Applications/IDA Professional 9.2.app 2. Install license to: /Applications/IDA Professional 9.2.app/Contents/MacOS 3. Update default IDA path in: /Users/user/.idapro/ida-config.json 4. Accept EULA ``` -------------------------------- ### Dry Run IDA Installation Source: https://hcli.docs.hex-rays.com/advanced/ci-cd-integration Simulates an IDA Pro installation without actually performing it, useful for testing installation configurations. Requires IDA_LICENSE_ID to be set as a secret. ```yaml - name: Test installation (dry run) run: | hcli ida install \ --dry-run \ --yes \ --accept-eula \ --license-id ${{ secrets.IDA_LICENSE_ID }} \ --download-id release/9.2/ida-pro/ida-pro_92_x64linux.run ``` -------------------------------- ### Inspect Installation Script (macOS/Linux) Source: https://hcli.docs.hex-rays.com/ Allows inspection of the HCLI installation script before execution on macOS and Linux. ```shell $ curl -LsSf https://hcli.docs.hex-rays.com/install | less ``` -------------------------------- ### Example ida-plugin.json for Native Plugin Source: https://hcli.docs.hex-rays.com/reference/packaging-your-existing-plugin Illustrates the addition of the `ida-plugin.json` metadata file for a native plugin. This file includes platform-specific information. ```json { "plugin-id": "milankovo/zydishelper", "plugin-version": "1.0.0", "name": "Zydis Helper", "description": "Helper for Zydis disassembler.", "author": "milankovo", "license": "MIT", "entry-point": "zydishelper", "plugin.platforms": [ "linux", "windows", "macos" ] } ``` -------------------------------- ### Install HCLI (Windows) Source: https://hcli.docs.hex-rays.com/ Installs the HCLI standalone executable on Windows systems using PowerShell. ```powershell iwr -useb https://hcli.docs.hex-rays.com/install.ps1 | iex ``` -------------------------------- ### Install an Existing API Key Source: https://hcli.docs.hex-rays.com/getting-started/authentication Installs a pre-existing API key into HCLI. Alternatively, the API key can be provided via the HCLI_API_KEY environment variable. ```bash hcli auth key install ``` -------------------------------- ### Inspect Installation Script (Windows) Source: https://hcli.docs.hex-rays.com/ Allows inspection of the HCLI installation script before execution on Windows using PowerShell. ```powershell PS> powershell -c "irm https://hcli.docs.hex-rays.com/install.ps1 | more" ``` -------------------------------- ### Install HCLI (macOS/Linux) Source: https://hcli.docs.hex-rays.com/ Installs the HCLI standalone executable on macOS and Linux systems. ```shell curl -LsSf https://hcli.docs.hex-rays.com/install | sh ``` -------------------------------- ### Search for IDA Pro Plugins Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Lists all available IDA Pro plugins, their versions, and installation status. You can also search for specific plugins by name. ```bash $ hcli plugin search current platform: macos-aarch64 current version: 9.2 bindiff 8.0.0 installed binexport 12.0.0 installed bookmark-hints 0.1.3 capa (incompatible) 9.2.1 colorize-calls 0.1.3 comida (incompatible) 2025.9.24 deREferencing 2025.9.24 installed extensible-hints 0.1.3 hint-calls 0.1.3 upgradable from 0.1.2 ida-chat 1.0.0 ida-cyberchef 0.1.0 installed ida-settings-editor 1.0.2 upgradable from 1.0.1 ida-terminal-plugin 0.0.6 IFL 1.5.2 installed ipyida 2.3 oplog 0.1.3 installed tag-func 0.1.3 xray 2025.9.24 zydisinfo 1.1 upgradable from 1.0 $ hcli plugin search ipython ipyida 2.3 installed ``` -------------------------------- ### List Available IDA Licenses Source: https://hcli.docs.hex-rays.com/user-guide/installing-ida Check the licenses associated with your account before proceeding with downloads or installations. ```bash $ hcli license list Subscription Licenses (2): egin{tabular}{|l|l|l|l|l|l|} A 96-0000-01 │ IDA Essential PC │ named │ Active │ 2026-08-25 │ 2 decompiler(s) B 96-0000-0000-01 │ IDA Ultimate │ named │ Active │ 2026-07-02 │ 11 decompiler(s) + TEAMS, LUMINA ``` -------------------------------- ### Example GitHub Actions Workflow for Native Plugin Source: https://hcli.docs.hex-rays.com/reference/packaging-your-existing-plugin A sample GitHub Actions workflow file for building a native IDA Pro plugin. This workflow demonstrates fetching SDKs, configuring the build with CMake, and matrixing across different platforms. ```yaml name: Build and Release on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest strategy: matrix: python-version: ["3.9"] # Add other platforms as needed steps: - uses: actions/checkout@v3 - name: Set up Python \${{ matrix.python-version }} uses: actions/setup-python@v3 with: python-version: \${{ matrix.python-version }} - name: Fetch IDA Pro SDKs uses: ./.github/actions/fetch-ida-sdk with: ida-versions: "9.0,9.1,9.2" - name: Configure CMake project run: cmake -B build -DCMAKE_INSTALL_PREFIX=install - name: Build plugin run: cmake --build build - name: Upload artifact uses: actions/upload-artifact@v3 with: name: zydishelper-linux path: ./build/zydishelper ``` -------------------------------- ### Register Click Commands Source: https://hcli.docs.hex-rays.com/development/setup Example of how to register command groups with the main Click CLI instance in Python. ```python # src/hcli/commands/__init__.py def register_commands(cli): cli.add_command(auth_group) cli.add_command(license_group) cli.add_command(share_group) ``` -------------------------------- ### Example IDA Pro Analysis Output Source: https://hcli.docs.hex-rays.com/advanced/docker Illustrates the expected output format after analyzing a binary with the IDA Pro Docker container, showing function details and analysis completion. ```text Analyzing binary: binary Full path: /analysis/binary -------------------------------------------------------------------------------- Successfully opened database for: binary Total functions found: 14 sub_401000: 29 instructions sub_401040: 20 instructions sub_401070: 16 instructions sub_4010A0: 115 instructions sub_4011E0: 232 instructions _main: 338 instructions start: 77 instructions _XcptFilter: 1 instructions _initterm: 1 instructions __setdefaultprecision: 6 instructions UserMathErrorFunction: 2 instructions nullsub_1: 1 instructions _except_handler3: 1 instructions _controlfp: 1 instructions -------------------------------------------------------------------------------- Analysis complete! ``` -------------------------------- ### Example ida-plugin.json for Pure Python Plugin Source: https://hcli.docs.hex-rays.com/reference/packaging-your-existing-plugin Illustrates the addition of the `ida-plugin.json` metadata file for a pure-Python plugin. This file is essential for plugin discovery and configuration. ```json { "plugin-id": "eset/DelphiHelper", "plugin-version": "1.0.0", "name": "Delphi Helper", "description": "Helper for Delphi files.", "author": "ESET", "license": "MIT", "entry-point": "plugin_entry.py", "pythonDependencies": [ "ida_hexrays_api" ] } ``` -------------------------------- ### Verify Plugin Files in Installation Directory Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Check if all plugin files have been correctly copied to the IDA Pro plugins directory. The path varies by operating system. ```bash # macOS/Linux ls ~/.idapro/plugins/my-awesome-plugin/ ``` ```bash # Windows dir %APPDATA%\.idapro\plugins\my-awesome-plugin\ ``` -------------------------------- ### Run Tests with uv and pytest Source: https://hcli.docs.hex-rays.com/development/setup Install test dependencies and run the test suite using pytest. ```bash uv sync --extra test uv run pytest ``` -------------------------------- ### Install Plugin with Corporate Pip Index Source: https://hcli.docs.hex-rays.com/reference/plugin-bundle-spec Installs a plugin using a specified corporate pip index URL instead of the default PyPI configuration. The `--pip-index-url` option directs pip to the custom index. ```bash hcli plugin --pip-index-url https://pypi.example.corp/simple install ipyida ``` -------------------------------- ### Install Plugin with Explicit Local Wheel Source Source: https://hcli.docs.hex-rays.com/reference/plugin-bundle-spec Installs a plugin using an explicit local wheel source specified by `--pip-find-links`. This option is used in conjunction with `--offline` to ensure only local sources are used. ```bash hcli plugin --pip-find-links /mnt/wheelhouse --offline install ipyida ``` -------------------------------- ### GitHub Actions Workflow for Native Plugin Build Source: https://hcli.docs.hex-rays.com/reference/plugins-AGENT This example GitHub Actions workflow demonstrates how to build a native IDA Pro plugin. It is designed to be adapted for packaging plugins into the HCLI ecosystem. ```yaml name: Build native plugin on: [push] defaults: run: shell: bash jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v3 with: python-version: '3.10' - name: Install dependencies run: | python -m pip install --upgrade pip pip install wheel pip install -r requirements.txt - name: Build plugin run: python setup.py sdist bdist_wheel - name: Upload artifact uses: actions/upload-artifact@v3 with: name: plugin-dist path: dist/ ``` -------------------------------- ### Common IDA Plugin Manager Commands Source: https://hcli.docs.hex-rays.com/user-guide/plugin-manager A list of essential HCLI commands for managing IDA plugins, including search, install, status, upgrade, and uninstall. ```bash ❯ hcli plugin search ❯ hcli plugin search [keyword or plugin-name] ❯ hcli plugin install ❯ hcli plugin status ❯ hcli plugin upgrade ❯ hcli plugin uninstall ``` -------------------------------- ### Manage Plugin Configuration Settings Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Commands to list, set, and get configuration values for your plugin using the hcli tool. ```bash # List plugin settings hcli plugin config list my-awesome-plugin # Set a configuration value hcli plugin config set my-awesome-plugin api_key "test-key-123" # Get the value hcli plugin config get my-awesome-plugin api_key # Test in plugin # Your plugin should read: ida_settings.get_current_plugin_setting("api_key") ``` -------------------------------- ### HCLI Core Commands Overview Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Displays a summary of the main commands supported by HCLI. Use this to get a quick glance at the tool's capabilities. ```bash $ hcli ╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ download Download IDA binaries, SDKs, and utilities. │ │ ida Manage IDA installations. │ │ license Manage IDA licenses. │ │ plugin Manage IDA Pro plugins. │ │ share Share files with Hex-Rays. │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` -------------------------------- ### Search for IDA Plugins Source: https://hcli.docs.hex-rays.com/user-guide/plugin-manager Use 'hcli plugin search' to list available plugins, their versions, and repository URLs. It shows installed plugins and can filter by keyword or plugin name. ```bash ❯ hcli plugin search current platform: macos-aarch64 current version: 9.2 bookmark-hints 0.1.3 https://github.com/williballenthin/idawilli colorize-calls 0.1.3 https://github.com/williballenthin/idawilli extensible-hints 0.1.3 https://github.com/williballenthin/idawilli hint-calls 0.1.3 https://github.com/williballenthin/idawilli oplog 0.1.3 installed https://github.com/williballenthin/idawilli tag-func 0.1.3 https://github.com/williballenthin/idawilli ``` -------------------------------- ### Pure Python Plugin Directory Structure Source: https://hcli.docs.hex-rays.com/reference/packaging-your-existing-plugin Example directory structure for a simple pure-Python plugin with a single entry point and utility modules. This structure is suitable for plugins distributed via source archives. ```text plugins.zip └── plugin1 ├── ida-plugin.json ├── plugin_entry.py └── myutils.py # import myutils ``` -------------------------------- ### Setting Custom User Directory for IDA Pro Source: https://hcli.docs.hex-rays.com/reference/plugin-repository-architecture Demonstrates how to set a custom IDAUSR environment variable to manage IDA Pro user data, useful for testing across different versions. This is followed by installing a plugin using HCLI and launching IDA with the custom directory. ```bash $ export IDAUSR=~/.idapro91/ $ hcli plugin install ipyida $ ~/software/ida-9.1/ida ``` -------------------------------- ### Install HCLI on macOS/Linux Source: https://hcli.docs.hex-rays.com/changelog This command installs the latest version of HCLI on macOS and Linux systems. Ensure you have curl installed. ```bash curl -LsSf https://hcli.docs.hex-rays.com/install | sh ``` -------------------------------- ### Create Plugin Bundle for Current Platform and Python Source: https://hcli.docs.hex-rays.com/reference/plugin-bundle-spec Creates a plugin bundle archive for the current machine's platform and Python version. Both `--platform` and `--python` are required, with 'current' resolving to the active environment. ```bash hcli plugin bundle create \ --path malware-vm-tools-2026-04.hcli-plugin-bundle.zip \ --platform current --python current \ oplog==0.1.3 \ hint-calls==0.1.3 ``` -------------------------------- ### Verify ida-hcli Installation Source: https://hcli.docs.hex-rays.com/development/setup Check if the ida-hcli installation is successful by running the version command. ```bash uv run hcli --version ``` -------------------------------- ### Create Plugin Bundle for All Platforms and Specific Python Versions Source: https://hcli.docs.hex-rays.com/reference/plugin-bundle-spec Creates a plugin bundle targeting all supported platforms and specific Python versions. The 'all' keyword resolves to all supported platforms. ```bash hcli plugin bundle create \ --path bundle.zip \ --platform all --python 3.12 --python 3.13 \ oplog==0.1.3 \ hint-calls==0.1.3 ``` -------------------------------- ### Use IDA SDK for Paths Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Demonstrates the correct way to construct paths using IDA SDK functions to ensure cross-platform compatibility. ```python import ida_diskio import idaapi import os # ✗ Wrong # config_path = "/Users/me/.plugin-config" # ✓ Correct config_path = os.path.join(ida_diskio.get_user_idadir(), "plugin-config") ``` -------------------------------- ### Build Package with uv Source: https://hcli.docs.hex-rays.com/development/setup Build the project package using the uv build command. ```bash uv build ``` -------------------------------- ### Set Up Forked Repository URL Source: https://hcli.docs.hex-rays.com/reference/hex-rays-guide-for-suggesting-changes Update the ida-plugin.json to point to your fork for temporary use by the plugin repository. ```bash https://github.com/HexRays-plugin-contributions/foo ``` -------------------------------- ### Install Specific HCLI Version (macOS/Linux) Source: https://hcli.docs.hex-rays.com/ Installs a specific version of HCLI by including the version number in the URL. ```shell curl -LsSf https://hcli.docs.hex-rays.com/install | sh -s -- --version 0.12.0 ``` -------------------------------- ### Install Specific HCLI Version (Windows) Source: https://hcli.docs.hex-rays.com/ Installs a specific version of HCLI on Windows by running the downloaded script with the -Version argument. ```powershell .\install.ps1 -Version "0.12.0" ``` -------------------------------- ### Install Specific HCLI Version on Windows Source: https://hcli.docs.hex-rays.com/changelog Installs a specific version of HCLI on Windows. Download the script and then run it with the desired version. ```powershell iwr https://hcli.docs.hex-rays.com/install.ps1 -OutFile install.ps1 .\install.ps1 -Version "0.12.6" ``` -------------------------------- ### Install Specific HCLI Version on macOS/Linux Source: https://hcli.docs.hex-rays.com/changelog Installs a specific version of HCLI on macOS and Linux. Replace '0.12.6' with the desired version number. ```bash curl -LsSf https://hcli.docs.hex-rays.com/install | sh -s -- --version 0.12.6 ``` -------------------------------- ### Load and Run Plugin in IDA Pro Console Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Use this command in the IDA Python console to load and execute your plugin for initial testing. ```python # In IDA Python console import ida_loader ida_loader.load_and_run_plugin("my-awesome-plugin", 0) ``` -------------------------------- ### HCLI Plugin Command Help Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Displays the usage and available commands for managing IDA Pro plugins with HCLI. ```bash ❯ hcli plugin Usage: hcli plugin [OPTIONS] COMMAND [ARGS]... Manage IDA Pro plugins. ╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────╮ │ config Manage plugin configuration settings. │ │ install │ │ lint Lint an IDA plugin directory, archive (.zip file), or HTTPS URL. │ │ search │ │ status │ │ uninstall │ │ upgrade │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` -------------------------------- ### Uninstall Plugin Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Command to remove the plugin from your IDA Pro installation. ```bash hcli plugin uninstall my-awesome-plugin ``` -------------------------------- ### List Available Licenses Source: https://hcli.docs.hex-rays.com/user-guide/licenses Use this command to see all licenses currently available and managed by HCLI. ```bash hcli license list ``` -------------------------------- ### Typical ida-plugin.json Configuration Source: https://hcli.docs.hex-rays.com/reference/plugin-packaging-and-format This JSON file provides metadata for an IDA Pro plugin, including its name, entry point, version, dependencies, and author information. It is required for HCLI compatibility. ```json { "$schema": "https://hcli.docs.hex-rays.com/schemas/ida-plugin.json", "IDAMetadataDescriptorVersion": 1, "plugin": { "name": "oplog", "entryPoint": "oplog_entry.py", "version": "0.1.2", "idaVersions": ["9.1", "9.2"], "description": "oplog is an IDA Pro plugin that records operations during analysis.", "license": "Apache 2.0", "categories": [ "ui-ux-and-visualization" ], "pythonDependencies": ["pydantic>=2"], "urls": { "repository": "https://github.com/williballenthin/idawilli" }, "authors": [{ "name": "Willi Ballenthin", "email": "wballenthin@hex-rays.com" }], "keywords": [ "activity-tracking", "workflow-analysis", "reverse-engineering-methodology", "ai-training-data", "analysis-visualization" ] } } ``` -------------------------------- ### Get License Details Source: https://hcli.docs.hex-rays.com/user-guide/licenses Retrieve detailed information about a specific license using its unique identifier. ```bash hcli license get ``` -------------------------------- ### Create Plugin Bundle for Specific Platforms and Python Versions Source: https://hcli.docs.hex-rays.com/reference/plugin-bundle-spec Creates a plugin bundle for a defined set of platforms and Python versions. HCLI builds a cross-product of all specified targets. ```bash hcli plugin bundle create \ --path malware-vm-tools-2026-04.hcli-plugin-bundle.zip \ --platform linux --platform windows --platform macos-arm64 \ --python 3.12 --python 3.13 \ oplog==0.1.3 \ hint-calls==0.1.3 ``` -------------------------------- ### Add Missing Plugin Version Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Example of adding the required semantic version to the `plugin` object in `ida-plugin.json`. ```json { "plugin": { "version": "1.0.0" } } ``` -------------------------------- ### Specify Python Dependency Versions Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Example of how to define version constraints for Python dependencies in the plugin's configuration. ```json { "pythonDependencies": [ "requests>=2.28.0", // Specify minimum version "pydantic>=2.0,<3.0" // Or version range ] } ``` -------------------------------- ### Initial File Upload Source: https://hcli.docs.hex-rays.com/user-guide/file-sharing Perform an initial upload of a file. The command returns a code for future reference. ```bash # Initial upload hcli share put analysis_v1.txt # Returns code: ABC123 ``` -------------------------------- ### Fix Trailing Comma in JSON Source: https://hcli.docs.hex-rays.com/how-to/test-plugin-before-publishing Example of correcting a trailing comma in a JSON object, specifically within the `plugin` field of `ida-plugin.json`. ```json { "plugin": { "name": "my-plugin", "version": "1.0.0" // ← Remove comma if this is the last field } } ``` -------------------------------- ### Download with Custom Filename Source: https://hcli.docs.hex-rays.com/user-guide/file-sharing Download a shared file and specify an exact output file path and name. Use the --output-file option. ```bash hcli share get ABC123 --output-file /path/to/renamed-file.idb ``` -------------------------------- ### Check IDA Pro Plugin Status Source: https://hcli.docs.hex-rays.com/getting-started/quick-start Displays the status of installed IDA Pro plugins, indicating which ones are upgradable, not found in the repository, or incompatible. ```bash $ hcli plugin status ida-settings-editor 1.0.1 upgradable to 1.0.2 zydisinfo 1.0 upgradable to 1.1 plugin1 5.0.0 not found in repository oplog 0.1.3 ida_vmray_presence 0.1.0 not found in repository HashDB 1.10.0 not found in repository DelphiHelper 1.21 not found in repository ipyida 2.3 bindiff 8.0.0 ida-cyberchef 0.1.0 deREferencing 2025.9.24 binexport 12.0.0 xrefer 2025.10.14 not found in repository IFL 1.5.2 hint-calls 0.1.2 upgradable to 0.1.3 (incompatible) yarka 0.7.0 found at: $IDAPLUGINS/yarka/ (legacy) foo.py found at: $IDAPLUGINS/foo.py Incompatible plugins don't work with this version of hcli. They might be broken or outdated. Try using `hcli plugin lint /path/to/plugin`. Legacy plugins are old, single-file plugins. They aren't managed by hcli. Try finding an updated version in the plugin repository. ```