Cortex CLI Cortex Cloud Application Security command line reference ↗

Use these command-line flags to configure Cortex Cloud Application Security scans. They are scoped to the code scan command and define what to scan and how results are reported. Their environment variables use the CORTEX_CODE_ prefix. The Application Security CLI also accepts flags that apply across modules, including authentication, TLS, proxy, logging, upload behavior, and exit-code policy.

--upload-mode and --no-fail-on-crash are the only flags supported in both global and command positions. They use the global variables $CORTEX_UPLOAD_MODE and $CORTEX_NO_FAIL_ON_CRASH, not CORTEX_CODE_ variables. Command-position support is retained for backward compatibility.

For global and common CLI commands, refer to Cortex CLI common command line reference guide.

Important

The Cortex CLI Cortex Cloud Application Security only supports single occurrences of each flag. If the same flag is passed multiple times, only the last provided value will be used. For example, in the following command, only TF CloudFormation will be the scanned framework.

EXAMPLE

cortexcli --api-base-url <YOUR_API_URL> --api-key <YOUR_API_KEY> --api-key-id <YOUR_API_KEY_ID> code scan --framework terraform --framework "terraform cloudformation

Command/Variable	Description
<p>`--source`</p><p>`$CORTEX_CODE_SOURCE`</p>	<p>(Optional, default `CORTEX_CLI`)</p><p>The execution environment that launched the scan.</p><p>Use one of the following values: `CORTEX_CLI`, `IDE_VSCODE`, `JENKINS`, `GITHUB_ACTIONS`, `CIRCLE_CI`, `AWS_CODE_BUILD`, `GIT_HOOK`, `GIT_HOOK_COMMITS`.</p><p>EXAMPLE: In a GitHub Actions pipeline, pass `--source GITHUB_ACTIONS`</p>
<p>`--repo-id`</p><p>`$CORTEX_CODE_REPO_ID`</p>	<p>The unique identifier used to associate scan results with the correct repository in Cortex.</p><ul><li>Value: `owner/repo` (for example, `my-org/my-repo`). Value must contain a forward slash `/`</li><li>Requirement: Required for upload mode; otherwise, optional</li><li>Auto-detection: If omitted, the CLI automatically extracts this value from your Git remote URL using the last two segments of the path</li><li>Do not use the tenant Asset ID hash, as it will fail validation. For more information on how to retrieve the repository ID, refer to #how-to-retrieve-the-repository-id</li></ul>
<p>`--repo-url` `$CORTEX_CODE_REPO_URL`</p>	Optional: URL of the repository being scanned (for example, `https://github.com/org/repo`). If omitted, the CLI attempts to auto-detect the URL from the local Git remote of the scanned directory
<p>`--branch`</p><p>`$CORTEX_CODE_BRANCH`</p>	<p>The branch name associated with the scan.</p><p>Default: The branch detected from your local Git checkout in `upload` mode when upload permissions are valid</p>
<p>`--directory`</p><p>`$CORTEX_CODE_DIRECTORY`</p>	<p>Required.</p><p>The directory path to scan. Cannot be used together with `--file`</p>
<p>`--file`</p><p>`$CORTEX_CODE_FILE`</p>	The file path to scan. Cannot be used together with `--directory`. When using this option, the Cortex CLI will filter runners based on the file type provided. For example, if you specify a `.tf` file, only the Terraform and secrets frameworks will be included. You can further limit this (for example; skip secrets) by using the `--skip-framework` argument
<p>`--var-file`</p><p>`$CORTEX_CODE_VAR_FILE`</p>	Variable files to load in addition to the default files. This feature is currently supported for both source Terraform (.tfvars files) and Helm chart scans (for providing custom values or variable overrides). Refer to https://www.terraform.io/docs/language/values/variables.html#variable-definitions-tfvars-files) below for more information
<p>`--framework`</p><p>`$CORTEX_CODE_FRAMEWORK`</p>	<p>Filter to scan specific frameworks. Example: `--framework arm`.</p><p>Syntax: Use a single flag with comma-separated values for multiple frameworks. Both quoted (`"arm,ansible"`) and unquoted (`arm,ansible`) formats are supported. Example: `--framework arm,ansible`.</p><p>Constraint: Do not use multiple --framework flags: `--framework terraform --framework sca_package`.</p><p>Environment variables: `export CORTEX_CODE_FRAMEWORK=arm,ansible`.</p><p>Supported frameworks: `ARM`, `ANSIBLE`, `BICEP`, `CLOUDFORMATION`, `DOCKER`, `DOCKERFILE`, `HELM`, `KUBERNETES`, `KUSTOMIZE`, `OPENAPI`, `SCA`, `SECRETS`, `SERVERLESS`, `TERRAFORM`, `TERRAFORMJSON`, `TERRAFORMPLAN`</p>
<p>`--skip-framework`</p><p>`$CORTEX_CODE_SKIP_FRAMEWORK`</p>	<p>Skip specific frameworks. Example: `--skip-framework terraform`.</p><p>Syntax: Use a single flag with comma-separated values for multiple frameworks. Both quoted (`"arm,ansible"`) and unquoted (`arm,ansible`) formats are supported. Example: `--skip-framework terraform, sca_package`.</p><p>Constraint: Do not use multiple skip --framework flags: `--skip-framework terraform --skip-framework sca_package`.</p><p>Environment variables: `export CORTEX_CODE_SKIP_FRAMEWORK="tf,sca"`</p>
<p>`--rule`</p><p>`$CORTEX_CODE_RULE`</p>	Restrict the scan to specific check IDs; all other checks are skipped. Enter one or more comma-separated check IDs, for example `--rule APPSEC_AWS_79,APPSEC_SECRET_80`
<p>`--severity` `$CORTEX_CODE_SEVERITY`</p>	<p>Filters scan results by severity level. Accepts one or more comma-separated values: unknown, low, medium, high, critical. Repeat the flag or use comma separation to specify multiple levels (for example, `--severity high,critical`).</p><p>Constraint: Only effective when `--upload-mode` is set to `no-upload`. When upload mode is active, the flag is ignored and an informational message is displayed</p>
<p>`--ignore-existing-secrets`</p><p>`$CORTEX_CODE_IGNORE_EXISTING_SECRETS`</p>	In CI/CD scans, report only newly introduced secrets. This flag filters out secret findings whose fingerprints already exist in the Cortex Cloud findings backlog, which a periodic baseline scan populates. This flag is ignored during pull request scans
<p>`--blocked-only`</p><p>`$CORTEX_CODE_BLOCKED_ONLY`</p>	Boolean flag. When set, shows only blocked findings in the output. Available only in `upload` mode
<p>`--summary-position`</p><p>`$CORTEX_CODE_SUMMARY_POSITION`</p>	Sets the position for displaying the summary information relative to the findings. Values: `top`, `bottom`
<p>`--upload-mode`</p><p>`$CORTEX_UPLOAD_MODE`</p>	Upload mode determines the method or mode used to upload data. See common flags for more information
<p>`--download-external-modules` `$``CORTEX_CODE_DOWNLOAD_EXTERNAL_MODULES`</p>	<p>(Optional, default `False`) Download external Terraform modules from public Git repositories and the Terraform Registry so they are included in the IaC scan. . Use `--external-modules-download-path` to control the download location (defaults to `.external_modules`). Requires outbound network access</p>
<p>`--external-modules-download-path`</p><p>`$CORTEX_CODE_EXTERNAL_MODULES_DOWNLOAD_PATH`</p>	Specifies the directory to download external modules to. Defaults to `.external_modules`
<p>`--external-checks-dir`</p><p>`$CORTEX_CODE_EXTERNAL_CHECKS_DIR`</p>	Local directory containing custom Cortex Python (`.py`) checks. The directory must be a Python package. This flag is repeatable and cannot be used with `--external-checks-git`.
<p>`--external-checks-git`</p><p>`$CORTEX_CODE_EXTERNAL_CHECKS_GIT`</p>	Git URL containing custom Cortex Python (`.py`) checks. Supports `//subdir` and `?ref=...`. This flag cannot be used with `--external-checks-dir`.
<p>`--external-checks-public-key`</p><p>`$CORTEX_CODE_EXTERNAL_CHECKS_PUBLIC_KEY`</p>	<p>Path to a PEM-encoded ECDSA P-256 public key used to verify signatures for custom Cortex Python (`.py`) checks.</p><p>When set, any tampered or unsigned file aborts the scan with exit code 2 before any check runs. When unset, verification is disabled for backward compatibility.</p><p>See Workflow: Sign and verify custom checks.</p>
<p>`--output`</p><p>`$CORTEX_CODE_OUTPUT`</p>	<p>Output format for reporting.</p><p>Supported formats: `cli`, `json`, `spdx`, `junitxml`, `sarif`, `cyclonedx`, `cyclonedx_json`</p>
<p>`--output-file-path`</p><p>`$CORTEX_CODE_OUTPUT_FILE_PATH`</p>	Specifies the output path for the scan result file
<p>`--deep-analysis`</p><p>`$CORTEX_CODE_DEEP_ANALYSIS`</p>	Enables or disables deep analysis of the Terraform plan and related files
<p>`--repo-root-for-plan-enrichment`</p><p>`$CORTEX_CODE_REPO_ROOT_FOR_PLAN_ENRICHMENT`</p>	Enriches Terraform plan findings by mapping them to their original `.tf` files
<p>`--skip-path`</p><p>`$CORTEX_CODE_SKIP_PATH`</p>	Specifies a path (file or directory) that should be skipped during the scanning process. This option is useful for excluding specific files or directories that are not relevant to the scanning analysis, increasing the efficiency and accuracy of scan results
<p>`--compact`</p><p>`$CORTEX_CODE_COMPACT`</p>	Do not display code blocks in the output
<p>`--no-fail-on-crash`</p><p>`$CORTEX_NO_FAIL_ON_CRASH`</p>	See common flags for a description
<p>`--validate-secrets`</p><p>`CORTEX_APPSEC_VALIDATE_SECRETS`</p>	Validate detected secrets against their respective services to confirm they are active. By default, this feature is disabled. Set `CORTEX_APPSEC_VALIDATE_SECRETS = true` to enable it
<p>`--timeout` `$CORTEX_CODE_TIMEOUT`</p>	<p>Sets the maximum time the Cortex CLI will wait for triggered local scan processes to complete. Default value: 15 minutes.</p><p>Syntax:</p><ul><li>To specify a duration: Use a numeric value followed by a unit (for example `--timeout 10m`)</li><li>Default unit: Numeric values entered without a unit are interpreted as seconds. For example, `30` is equal to 30 seconds.</li><li>Supported units: Milliseconds, seconds, minutes and hours</li></ul>
`--start-commit`	Starting commit hash for git history scanning (Git Hook flag). No environment-variable equivalent is available.
`--commit-list`	Comma-separated list of commit hashes to scan (Git Hook flag). No environment-variable equivalent is available.
`--hook-event`	Git hook event type, such as `pre-commit` (Git Hook flag). No environment-variable equivalent is available.
`--help`	See common flags for a description

How to retrieve the repository ID

Option 1: From the local repository checkout (Recommended)

git config --get remote.origin.url

Remove any trailing .git and take the final two path segments. For example, https://github.com/my-org/my-repo.git yields my-org/my-repo. This matches the exact logic the CLI uses to auto-derive the value.

Option 2: From the Cortex Cloud console

Navigate to Inventory → All Assets → Repositories.
Select the repository row to open the side card.
Copy the title displayed at the top of the side card (in owner/repo format).

Note: Two console fields are commonly mistaken for this value and neither is valid:

Asset ID (in the side card Properties section) is an internal platform hash, not a repository path. Passing it will fail validation

Repository Name (in the table column) is only the repository name without the owner

Option 3: From the Public API

GET /public_api/appsec/v1/repositories

In the response, locate your repository and join the owner and name fields with a forward slash (owner/name).

EXAMPLES

Explicitly defining the repository path and branch

Use this pattern for local scans or custom builds. It sets the repository and branch manually.

cortexcli code scan \
  --directory . \
  --branch main \
  --repo-id my-org/my-repo \
  --upload-mode upload

Providing --repo-id and --branch explicitly associates results with the correct platform asset. This works regardless of local Git status or API key permission levels.

Auto-deriving values from the local Git checkout

Use this minimal syntax from a developer workstation inside an active Git working tree.

# Auto-derive the repository path and branch from the local Git remote
cortexcli code scan \
  --directory . \
  --upload-mode upload

When omitted, the CLI derives --repo-id from the origin remote URL. It derives --branch from the local HEAD checkout. Auto-derivation requires an API key with write or upload permissions. With a read-only API key, pass both values explicitly.

Running in GitHub Actions workflows

Use native GitHub Actions context variables to set the repository and branch dynamically.

# In GitHub Actions workflows
cortexcli code scan \
  --directory . \
  --branch ${{ github.ref_name }} \
  --repo-id ${{ github.repository }} \
  --upload-mode upload

Always pass --repo-id and --branch explicitly in CI. GitHub Actions checkouts often use a detached HEAD. Auto-derivation can resolve the branch as HEAD, rather than the target branch.

Running in GitLab CI pipelines

Use predefined GitLab CI variables to populate the repository path and branch.

# In GitLab CI pipelines
cortexcli code scan \
  --directory . \
  --branch $CI_COMMIT_BRANCH \
  --repo-id $CI_PROJECT_PATH \
  --upload-mode upload

GitLab CI supports multi-segment subgroup paths, such as my-group/my-subgroup/my-repo. $CI_PROJECT_PATH provides the complete forward-slash-delimited path required by --repo-id.