Quick Start
First Steps
- Install HCLI (see Installation)
- Authenticate (see Authentication)
- Verify your setup:
hcli whoami You are logged in as user@example.com using an API key from HCLI_API_KEY environment variable
Command Overview (abbreviated)
Here are the core operations supported by HCLI:
$ 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. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
All Available Commands
$ hcli commands
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Command ┃ Description ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ hcli auth default │ Set or show the default credentials. │
│ hcli auth key create │ Create a new API key. │
│ hcli auth key install │ Install an API key as a new credentials. │
│ hcli auth key list │ List all API keys. │
│ hcli auth key revoke │ Revoke an API key. │
│ hcli auth list │ List all credentials. │
│ hcli auth switch │ Switch the default credentials. │
│ hcli commands │ List all available command combinations. │
│ hcli download │ Download IDA binaries, SDKs, and utilities. │
│ hcli hcli-extensions create │ Create an hcli extension │
│ hcli hcli-extensions list │ List hcli extensions │
│ hcli ida install │ Installs IDA unattended. │
│ hcli ida set-default │ Set or show the default IDA installation directory. │
│ hcli license get │ Download license files with optional filtering. │
│ hcli license install │ Install a license file to an IDA Pro installation directory. │
│ hcli license list │ List available licenses with rich formatting. │
│ hcli login │ Log in to the Hex-Rays portal and create new credentials. │
│ hcli logout │ Log out and remove stored credentials. │
│ hcli mcp install │ Install IDA MCP for Claude, Codex, Copilot, Pi, or OMP. │
│ hcli plugin config del │ Delete a plugin configuration setting. │
│ hcli plugin config export │ Export plugin configuration settings as JSON. │
│ hcli plugin config get │ Get a plugin configuration setting. │
│ hcli plugin config import │ Import plugin configuration settings from JSON. │
│ hcli plugin config list │ List all configuration settings for a plugin. │
│ hcli plugin config set │ Set a plugin configuration setting. │
│ hcli plugin install │ Install a plugin from a repository, URL, or local path. │
│ hcli plugin lint │ Lint an IDA plugin directory, archive (.zip file), or HTTPS URL. │
│ hcli plugin repo add │ Add a plugin repository. │
│ hcli plugin repo list │ List the configured plugin repositories. │
│ hcli plugin repo remove │ Remove a plugin repository. │
│ hcli plugin repo set-default │ Set the repository used for references with no repo/ prefix. │
│ hcli plugin repo snapshot │ Create a snapshot of the repository. │
│ hcli plugin search │ Search for plugins across configured repositories. │
│ hcli plugin status │ Show installed plugins and available upgrades. │
│ hcli plugin uninstall │ Uninstall an installed plugin. │
│ hcli plugin upgrade │ Upgrade an installed plugin to the latest version. │
│ hcli share delete │ Delete shared file by code. │
│ hcli share get │ Download a shared file using its shortcode. │
│ hcli share list │ List and manage your shared files. │
│ hcli share put │ Upload a shared file. │
│ hcli update │ Check for hcli updates. │
│ hcli whoami │ Display the currently logged-in user. │
└───────────────────────────┴──────────────────────────────────────────────────────────────────┘
Examples
Install IDA
First, lets check what licenses are associated with our account:
$ hcli license list
Subscription Licenses (2):
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID ┃ Edition ┃ Type ┃ Status ┃ Expiration ┃ Addons ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 96-0000-0000-01 │ IDA Essential PC │ named │ Active │ 2026-08-25 │ 2 decompiler(s) │
│ 96-0000-0000-01 │ IDA Ultimate │ named │ Active │ 2026-07-02 │ 11 decompiler(s) + TEAMS, LUMINA │
└─────────────────┴──────────────────┴───────┴────────┴────────────┴──────────────────────────────────┘
Now lets download the IDA installer, though we'll see in a subsequent step we can also download it on-demand:
$ hcli download
Fetching available downloads...
Current path: /
? Select an item to navigate or download: 📁 release
Current path: /release
? Select an item to navigate or download: 📁 9.2
Current path: /release/9.2
? Select an item to navigate or download: 📁 ida-pro
Current path: /release/9.2/ida-pro
? Select an item to navigate or download: (Use arrow keys, type to filter)
← Go back
📄 License Server 9.2 (hexlicsrv92_x64linux.run)
» 📄 IDA Pro Mac Apple Silicon 9.2 (ida-pro_92_armmac.app.zip)
📄 Lumina Server 9.2 (lumina92_x64linux.run)
📄 Teams Server 9.2 (hexvault92_x64linux.run)
📄 IDA Pro Windows 9.2 (ida-pro_92_x64win.exe)
📄 IDA Pro Linux 9.2 (ida-pro_92_x64linux.run)
📄 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/Library/Caches/hex-rays/hcli/downloads/release/9.2/ida-pro/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
For a little context, here are the options that the automated installer supports:
$ hcli ida install --help
Usage: hcli ida install [OPTIONS] [INSTALLER]
Installs IDA unattended.
The --download-id option supports tags for simplified version specification:
- 'category:version' (e.g., 'ida-pro:latest') - OS is auto-detected
- 'category:version:os' (e.g., 'ida-pro:9.2:x64linux') - explicit OS
If install_dir is /tmp/myida, the ida binary will be located:
- on Windows: /tmp/myida/ida
- on Linux: /tmp/myida/ida
- on Mac: /tmp/myida/Contents/MacOS/ida
╭─ Options ──────────────────────────────────────────────────────────────────────────╮
│ --create-python-environment After installing IDA, create a │
│ virtual environment for its Python at │
│ $IDAUSR/venv (see `ida python │
│ create-environment`). │
│ --yes -y Auto-accept confirmation prompts │
│ --dry-run Show what would be done without │
│ actually installing │
│ --set-default/--no-set-default Mark this IDA installation as the │
│ default │
│ --accept-eula/--no-accept-eula -a/-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 Full installer asset key, or tag │
│ (e.g., 'ida-pro:latest', │
│ 'ida-essential:9.2') │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────╯
Now lets run the automated installer, which doesn't show any dialog or popups - really convenient!
Note:
--set-defaultand--accept-eulaare on by default: the installation becomes the one idalib and the plugin manager use, and the EULA is accepted without prompting. Pass--no-set-defaultor-A/--no-accept-eulato opt out. The example spells both out for clarity, but they are redundant- the installer is cached, so a second run reuses the download. The per-platform cache locations and the
HCLI_CACHE_DIRoverride are listed under Cache & Storage in Environment Variables --create-python-environmentsets up a virtualenv for IDAPython at$IDAUSR/venvand configuresIDAPYTHON_VENV_EXECUTABLE; plugins that need Python packages are installed here- in this example we set
--dry-run, but you should remove this in real-life - HCLI also fetches and installs the associated license key file so everything's ready to go
$ hcli ida install --set-default --create-python-environment --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
Now, if you know exactly which version of IDA you want, you can download and install it in a single command.
Note the use of --download-id release/9.2/ida-pro/ida-pro_92_armmac.app.zip, the path is derived from the hcli download output above.
$ hcli ida install --set-default --create-python-environment --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/Library/Caches/hex-rays/hcli/downloads/release/9.2/ida-pro/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
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-id also accepts a tag instead of a full asset key, so you do not have to look the key up. A tag is category:version, which resolves the OS automatically, or category:version:os to pin it:
hcli ida install --license-id 96-0000-0000-01 --download-id ida-pro:9.2 --dry-run
hcli ida install --license-id 96-0000-0000-01 --download-id ida-pro:latest:x64linux --dry-run
Share a file with Hex-Rays Support
You can use HCLI to upload files into a shared space available to Hex-Rays Support. This is really useful when you've found a bug in IDA Pro and want to help the engineers reproduce it.
There are three visibilities:
- private: Just for me
- domain: Anyone from my domain (@example.com)
- authenticated: Anyone authenticated with the link
$ hcli share list
No shared files found.
$ hcli share put /tmp/1/a49e9ff8d53a9af8ef20a383a276449d.exe_.i64
? Pick a visibility 🔎 [authenticated] Anyone authenticated with the link
Upload Complete 100% 434.6/434.6 kB 2.1 MB/s 0:00:00
✓ File uploaded successfully!
Share Code: efja98
Share URL: https://my.hex-rays.com/share/efja98
Download URL: https://api.eu.hex-rays.com/api/assets/s/efja98
$ hcli share list
» ○ a49e9ff8d53a9af8ef20a383a276449d.exe_.i64 (efja98) - 424.4 KB
At this point, you can share the short code (efja98) with support@hex-rays.com and they can access the file:
$ hcli share get efja98
Downloading a49e9ff8d53a9af8ef20a383a276449d.exe_.i64 100%
✓ File downloaded successfully!
File: a49e9ff8d53a9af8ef20a383a276449d.exe_.i64
Size: 424.4 KB
Saved to: a49e9ff8d53a9af8ef20a383a276449d.exe_.i64
$ hcli share delete efja98
File to delete:
Name: a49e9ff8d53a9af8ef20a383a276449d.exe_.i64
Code: efja98
Size: 424.4 KB
Delete file a49e9ff8d53a9af8ef20a383a276449d.exe_.i64 ? [y/n]: y
✓ Deleted: efja98
Find and Install an IDA Pro plugin
❯ 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 Install a plugin from a repository, local directory, local .zip file, or URL. │
│ lint Lint an IDA plugin directory, archive (.zip file), or HTTPS URL. │
│ repo Manage plugin repositories. │
│ search Search for plugins by name, keyword, category, or author. │
│ status Show installed plugins and their upgrade status. │
│ uninstall Remove an installed plugin. │
│ upgrade Upgrade an installed plugin to the latest compatible version. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────╯
$ 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-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
If two plugins share the same bare name, HCLI will ask you to qualify the reference with the plugin's repository URL, for example hcli plugin install ida-chat@https://github.com/HexRaysSA/ida-chat-plugin. To install a private plugin from the Hex-Rays repository, prefix the name with hexrays/:
$ hcli plugin install hexrays/some-private-plugin
See Plugin Manager for details on repositories and disambiguation.
$ hcli plugin install ipyida
Installed plugin: ipyida==2.3
$ 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.
Next Steps
- IDA's Python Environment - Check and manage the Python environment that IDA and plugins use
- License Management - Managing your IDA licenses
- File Sharing - Share and collaborate on files