Cortex CloudCortex CLI

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

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
    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.
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 (<current_directory_path>). It is recommended to use the absolute file path for your current working directory
- Ensure that the --repo-id parameter includes the <repo_owner_name>/<repo_name> structure, with the <repo_name> matching the exact name of the directory
  Example 246. Example
  The present working directory is Users/test/<repo_name>. Therefore, the --repo-id parameter must be --repo-id <repo_owner_name>/<repo_name>, ensuring that <repo_name> 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

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.

Standard installation

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.
  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.

Standard installation

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:
```
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.

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)

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.
On the Configure step of the integration wizard, select your operating system from the menu and click Next.
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:

If the code contains placeholders, replace ${API_KEY} with the API key you saved.
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.
Paste the finalized copied command into your local terminal and press Enter. The command you are running uses the following underlying syntax:
```
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:

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:
```
cortexcli -v
```
If the file is still in your current download folder (not in your system PATH):
```
./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
```
brew upgrade cortexcli
```
Freeze whatever you have now (blocks brew upgrade from touching it)
```
brew pin cortexcli     
```
Uninstall
```
brew uninstall cortexcli
```

Windows

Upgrade to latest version
```
scoop update cortexcli
```
Prevent upgrades
```
scoop hold cortexcli  
```
Allow upgrades again
```
scoop unhold cortexcli     
```
Uninstall
```
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.

crtx_resp=$(curl --fail "<CORTEX_API_URL>/public_api/v1/unified-cli/releases/download-link?os=<OS>&architecture=<ARCH>" \
  -H "x-xdr-auth-id: <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
<CORTEX_API_URL>: Your tenant API base URL
<AUTH_ID>: Your API key ID value
<OS>: Your operating system (linux, darwin, or windows)
<ARCH>: Your system architecture (such as amd64, arm64)

How it works

The script:

Requests a signed download link from Cortex Cloud for the latest release matching your OS and architecture.
Parses the JSON response using jq to extract the temporary download URL (signed_url) and the target binary file name (file_name).
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.

PreviousCortex CLI

NextAuthenticate credentials

Last updated 22 days ago

Was this helpful?