> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-cli/connect-cortex-cli.md). # Connect Cortex CLI Connect Cortex CLI to scan supported Cortex Cloud modules and gain insights into your security posture, enabling you to identify, analyze and address potential risks. You can choose from three main installation workflows: * **Package Manager**: The most efficient developer workflow, utilizing Homebrew for macOS/Linux and Scoop for Windows * **Manual download**: Directly download the binaries for any operating system * **UI-based installation**: Onboard and download the CLI directly from your tenant {% hint style="warning" %} ### Prerequisites * **System requirements**: * **macOS** (Intel Core i7, such as Sequoia): To ensure all functionalities work correctly, you must install the `vectorscan` dependency via **Homebrew**, using this command: `brew install vectorscan` * **RHEL 8.10** and **Red Hat UBI9**. The following prerequisites must be met: * Install `patchelf` * Install `zstd` * **Ubuntu 20** requires the `prefetch` utility * **Ubuntu (for linux-amd64)** also requires the `libhyperscan5` library. To install, run `sudo apt install libhyperscan5` * **Linux for AppSec Module**: Support is provided for systems meeting the following specifications: * **RHEL 10**: Kernel: 6.12, glibc: 2.39 * **Debian 12**: Kernel: 6.1.27, glibc: 2.36 * **Ubuntu**: * Version 18.04 - Kernel: 4.15, glibc: 2.27 * Version 20.04 - Kernel: 5.4, glibc: 2.31 * Version 22.04 - Kernel: 5.15, Glibc: 2.35 * Version 24.04 - Kernel: 6.8, Glibc: 2.39 * **Windows**: AMD 64 and ARM 64 * **For cURL-based downloads**: * `curl` * `jq` * On **Ubuntu/Debian-based Linux** distributions: `sudo apt-get install jq` * On **RedHat/CentOS/Fedora**: `sudo yum install jq` * **macOS** (using `Homebrew`): `brew install jq` * **Windows**: * Download the executable from [jq GitHub releases](https://github.com/stedolan/jq/releases) * If `Chocolatey` is installed: `choco install jq` * **Permissions**: * **With upload results**: Requires a role with `CLI View/Edit` (write) permissions. * **Local scan only**: Requires a role with `CLI Read Only` (read-only) permissions For more information refer to [Cortex CLI](/cortex-cli/cortex-cli.md). * **Roles**: There are no out-of-the-box CLI roles. The CLI authenticates via an API key. Ensure the API key associated with your role includes the required permissions * **API Security level**: The API key must be set to the `Standard` security level. CLI scans will fail if the security level is set to `Advanced` * **Best practice** (required for SCA vulnerability suppression): * Run the CLI within your current working directory (\). It is recommended to use the absolute file path for your current working directory * Ensure that the `--repo-id` parameter includes the `/` structure, with the `` matching the exact name of the directory Example 246. Example The present working directory is `Users/test/`. Therefore, the `--repo-id` parameter must be `--repo-id /`, ensuring that `` precisely matches the directory name within the structure. * For terminal actions performed by Cortex XSIAM IDE extensions on Windows, Command Prompt (CMD) is the supported environment. PowerShell is not supported for these actions {% endhint %} ### Workflow 1: Install through a Package Manager Using a package manager is the recommended method for installing the Cortex CLI. Use `Homebrew` (for macOS and Linux) or `Scoop` (for Windows). #### macOS & Linux (Homebrew) Supported on macOS (Apple Silicon & Intel) and Linux (x86\_64 & arm64). Requires [Homebrew](https://brew.sh/). * **Standard installation** ```programlisting brew tap paloaltonetworks/cortexcli brew install cortexcli cortexcli --version ``` * **Pinning to a specific version (optional)** If your workflow requires a specific version, use one of the following methods instead: * **Pin to a release line** (for example stay with v 0.18.x ) Use this method to lock the CLI to a specific minor version but still receive automatic security patches. ```programlisting brew install cortexcli@0.18 # keg-only — add to PATH if needed: echo 'export PATH="$(brew --prefix cortexcli@0.18)/bin:$PATH"' >> ~/.zprofile ``` * **Pin to an exact version** (for example exactly 0.18.0): Use this method to strictly lock the CLI to a precise build. This prevents all automatic updates. #### Windows (Scoop) Supported on Windows x64. Requires [Scoop](https://scoop.sh/). * **Standard installation** ```programlisting scoop bucket add cortexcli https://github.com/PaloAltoNetworks/homebrew-cortexcli scoop install cortexcli cortexcli --version ``` * **Install a specific version (optional)** If your workflow requires a specific version, use this method instead: ```programlisting scoop install cortexcli@0.18.0 ``` ### Workflow 2: Manual download (any OS) You can manually download the binaries for macOS, Linux, or Windows. #### Step 1: Download the binary. Retrieve the specific archive for your platform from the [releases page](https://github.com/PaloAltoNetworks/homebrew-cortexcli/releases). * **macOS / Linux**: Download the appropriate `.tar.gz` archive for your system architecture * **Windows**: Download the appropriate `.zip` archive #### Step 2: Verify and Extract. Verify the download against the `SHA256SUMS` file provided on the releases page, then extract the archive. * **macOS / Linux**: The extracted executable will be named `cortexcli` * **Windows**: The extracted executable will be named `cortexcli.exe` #### Step 3: Add to PATH. Place the extracted file in a directory that is included in your system's `PATH` so you can run it from any terminal. * **macOS / Linux**: Move cortexcli to a directory such as `/usr/local/bin/` * **Windows**: Move `cortexcli.exe` to a dedicated folder and add that folder's path to your system's **Environment Variables** ### Workflow 3: UI-Based Installation This method allows you to install the CLI directly from your tenant. Instead of downloading a standard installation file through your web browser, the Cortex UI generates a custom installation command that you must run in your terminal to securely pull and authenticate the CLI binary. #### Step 1: Generate the installation command (in the UI) 1. On your tenant. 1. Navigate to **Settings** → **Data Sources** → **+ Data Source**. 2. **Enter Cortex CLI in the search bar** → **Hover over the Cortex CLI card** → **Connect or Connect Another Instance**. 2. On the **Configure** step of the integration wizard, select your operating system from the menu and click Next. 3. On The **Authenticate** step of the wizard. 1. **Generate an API**: 1. Select Generate API key. Permission options: * **With upload results permissions**. Creates a **CLI** role for the API key with CLI **View/Edit** options. It is recommended as it grants the API key permissions to not only access data, but also to upload or send data back * If you do not select this option, the generated API key creates a **CLI Read Only** role with CLI **View** permissions only

Note

The Cortex CLI requires an API key with the Standard security level.

2. Copy and save the the generated `API Key ID` and `API key` that are displayed in their respective fields. 3. Copy and save the the generated API key from the **Retrieve your API key** field. The UI generates and displays a code command. Copy this provided code block.

Note

On macOS arm 64 architecture you must unpack the downloaded file to retrieve the executable.

4. Verify that the generated API key is displayed under the API Keys inventory. #### Step 2: Download the CLI (in your terminal). Before running the command, you may need to insert your specific credentials into the code you just copied: 1. If the code contains placeholders, replace `${API_KEY}` with the API key you saved. 2. If needed, retrieve your public API URL by navigating to **Settings** → **Configurations** → **API Keys** and clicking Copy API URL, then paste it into the code. 3. Paste the finalized copied command into your local terminal and press Enter. The command you are running uses the following underlying syntax: ```programlisting curl -k -u $CORTEX_API_ID::$CORTEX_API_KEY --output ./cortexcli $CORTEX_FQDN/api/v2/remote-li/{version}/{platform}/artifacts ``` What this does: This securely connects to your specific Cortex tenant (`$CORTEX_FQDN`) using your newly generated API credentials and downloads the `cortexcli` application directly to your current folder. #### Step 3: Make the CLI Executable (macOS & Linux only). By default, macOS and Linux restrict downloaded files from running as programs. You must explicitly grant the downloaded file permission to execute by running: ```programlisting chmod +x cortexcli ``` #### Step 4: Verify the installation. Confirm that the CLI was downloaded and authenticated successfully by asking it to report its version. The command you use depends on where the file is currently located: * If you moved the file to a directory on your system `PATH`: ```programlisting cortexcli -v ``` * If the file is still in your current download folder (not in your system `PATH`): ```programlisting ./cortexcli -v ``` If the terminal displays the version number, the installation is complete and the CLI is ready to use. You can now return to the Cortex Cloud UI and click Done. ### Post-installation actions Use the following methods to manage your CLI application lifecycle after the initial installation. You can use either the automated download script or package managers for both your CI/CD pipelines and local end-user environments. #### Method 1: Package managers Manage the CLI lifecycle using your system's package manager. #### macOS and Linux * **Upgrade to latest version** ```programlisting brew upgrade cortexcli ``` * **Freeze whatever you have now** (blocks `brew upgrade` from touching it) ```programlisting brew pin cortexcli ``` * **Uninstall** ```programlisting brew uninstall cortexcli ``` #### Windows * **Upgrade to latest version** ```programlisting scoop update cortexcli ``` * **Prevent upgrades** ```programlisting scoop hold cortexcli ``` * **Allow upgrades again** ```programlisting scoop unhold cortexcli ``` * **Uninstall** ```programlisting scoop uninstall cortexcli ``` #### Method 2: Automated download script To upgrade your CLI to the latest version, you can run the automated download script. This script will fetch the most recent release, make it executable, and overwrite your existing binary. ```programlisting crtx_resp=$(curl --fail "/public_api/v1/unified-cli/releases/download-link?os=&architecture=" \ -H "x-xdr-auth-id: " \ -H "Authorization: ${CORTEX_API_KEY}") \ && crtx_url=$(echo $crtx_resp | jq -r ".signed_url") \ && crtx_file=$(echo $crtx_resp | jq -r ".file_name") \ && curl -o $crtx_file $crtx_url ``` #### Required environment variable substitutions * `CORTEX_API_KEY`: Your API key * ``: Your tenant API base URL * ``: Your API key ID value * ``: Your operating system (`linux`, `darwin`, or `windows`) * ``: Your system architecture (such as `amd64`, `arm64`) #### How it works The script: 1. Requests a signed download link from Cortex Cloud for the latest release matching your OS and architecture. 2. Parses the JSON response using `jq` to extract the temporary download URL (`signed_url`) and the target binary file name (`file_name`). 3. Downloads the new binary with a second curl call to the signed URL, replacing your older version of the CLI. ### Troubleshooting #### `cortexcli --version` shows a different version than I just installed You likely have an older copy of `cortexcli` earlier on your `PATH` — for example from the macOS `.pkg` installer, a manual download, or a previous tenant download. The shell is finding that one first. #### Find every copy: `macOS / Linux which -a cortexcli` `Windows (PowerShell) where.exe cortexcli` #### Expected location for the package-manager install: * macOS (Homebrew): `/opt/homebrew/bin/cortexcli` or `/usr/local/bin/cortexcli` * Linux (Homebrew): `/home/linuxbrew/.linuxbrew/bin/cortexcli` * Windows (Scoop): `%USERPROFILE%\scoop\shims\cortexcli.exe` #### Remove the old copy: * **macOS `.pkg` installer** → `sudo rm /usr/local/bin/cortexcli` * **Manual / tenant download** → delete the binary at the path shown by `which -a` / `where.exe` * **Windows installer** → uninstall via Settings → Apps → Installed apps, or delete the `.exe` shown by `where.exe` #### Finalize: Open a **new terminal** (so the shell drops its command cache) and re-run `cortexcli --version`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/cortex-cli/connect-cortex-cli.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.