Connect Cortex CLI - Administrator Guide - Cortex CLOUD

Cortex Cloud Posture Management Documentation
Product
Cortex Cloud Application Security > Cortex CLOUD
License
Cloud Posture Management
Creation date
2025-01-22
Last date published
2026-06-04
Category
Administrator Guide

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:

  • 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 113. 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 Cloud 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.

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

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

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

    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:

  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.