Cycode CLI User Guide

The Cycode Command Line Interface (CLI) is an application you can install locally to scan your repositories for secrets, infrastructure as code misconfigurations, software composition analysis vulnerabilities, and static application security testing issues.

This guide walks you through both installation and usage.

Table of Contents

1. Prerequisites
2. Installation
   1. Install Cycode CLI
      1. Using the Auth Command
      2. Using the Configure Command
      3. Add to Environment Variables
         1. On Unix/Linux
         2. On Windows
   2. Install Pre-Commit Hook
3. Cycode CLI Commands
4. Certificates and Proxies
5. MCP Command
   1. Starting the MCP Server
   2. Available Options
   3. MCP Tools
   4. Usage Examples
   5. Advanced Configuration
6. Platform Command
   1. Discovering Commands
   2. Examples
   3. Notes & Limitations
7. AI Guardrails
   1. Data Collected by AI Guardrails
8. Scan Command
   1. Running a Scan
      1. Options
         1. Severity Threshold
         2. Monitor
         3. Cycode Report
         4. Package Vulnerabilities
         5. License Compliance
         6. Lock Restore
         7. Stop on Error
      2. Repository Scan
         1. Branch Option
      3. Path Scan
         1. Terraform Plan Scan
      4. Commit History Scan
         1. Commit Range Option (Diff Scanning)
      5. Pre-Commit Scan
      6. Pre-Push Scan
   2. Scan Results
      1. Show/Hide Secrets
      2. Soft Fail
      3. Example Scan Results
         1. Secrets Result Example
         2. IaC Result Example
         3. SCA Result Example
         4. SAST Result Example
      4. Company Custom Remediation Guidelines
   3. Ignoring Scan Results
      1. Ignoring a Secret Value
      2. Ignoring a Secret SHA Value
      3. Ignoring a Path
      4. Ignoring a Secret, IaC, or SCA Rule
      5. Ignoring a Package
      6. Ignoring via a config file
9. Report command
   1. Generating SBOM Report
10. Import command
11. Scan logs
12. Syntax Help

Prerequisites

• The Cycode CLI application requires Python version 3.9 or later. The MCP command is available only for Python 3.10 and above. If you're using an earlier Python version, this command will not be available.
• Use the cycode auth command to authenticate to Cycode with the CLI
  • Alternatively, you can get a Cycode Client ID and Client Secret Key by following the steps detailed in the Service Account Token and Personal Access Token pages, which contain details on getting these values.

Installation

The following installation steps are applicable to both Windows and UNIX / Linux operating systems.

[!NOTE] The following steps assume the use of python3 and pip3 for Python-related commands; however, some systems may instead use the python and pip commands, depending on your Python environment’s configuration.

Install Cycode CLI

To install the Cycode CLI application on your local machine, perform the following steps:

1. Open your command line or terminal application.

2. Execute one of the following commands:

   • To install from PyPI:

     bashCopy code
     pip3 install cycode
     

   • To install from Homebrew:

     bashCopy code
     brew install cycode
     

   • To install from GitHub Releases navigate and download executable for your operating system and architecture, then run the following command:

   bashCopy code
   cd /path/to/downloaded/cycode-cli
   chmod +x cycode
   ./cycode
   

3. Finally authenticate the CLI. There are three methods to set the Cycode client ID and credentials (client secret or OIDC ID token):

   • cycode auth (Recommended)
   • cycode configure
   • Add them to your environment variables

Using the Auth Command

[!NOTE] This is the recommended method for setting up your local machine to authenticate with Cycode CLI.

1. Type the following command into your terminal/command line window:

   cycode auth

2. A browser window will appear, asking you to log into Cycode (as seen below):

3. Enter your login credentials on this page and log in.

4. You will eventually be taken to the page below, where you'll be asked to choose the business group you want to authorize Cycode with (if applicable):

   [!NOTE] This will be the default method for authenticating with the Cycode CLI.

5. Click the Allow button to authorize the Cycode CLI on the selected business group.

6. Once completed, you'll see the following screen if it was selected successfully:

7. In the terminal/command line screen, you will see the following when exiting the browser window:

   Successfully logged into cycode

Using the Configure Command

[!NOTE] If you already set up your Cycode Client ID and Client Secret through the Linux or Windows environment variables, those credentials will take precedent over this method.

1. Type the following command into your terminal/command line window:

   bashCopy code
   cycode configure
   

2. Enter your Cycode API URL value (you can leave blank to use default value).

   Cycode API URL [https://api.cycode.com]: https://api.onpremise.com

3. Enter your Cycode APP URL value (you can leave blank to use default value).

   Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com

4. Enter your Cycode Client ID value.

   Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d

5. Enter your Cycode Client Secret value (skip if you plan to use an OIDC ID token).

   Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e

6. Enter your Cycode OIDC ID Token value (optional).

   Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

7. If the values were entered successfully, you'll see the following message:

   Successfully configured CLI credentials!

   or/and

   Successfully configured Cycode URLs!

If you go into the .cycode folder under your user folder, you'll find these credentials were created and placed in the credentials.yaml file in that folder. The URLs were placed in the config.yaml file in that folder.

Add to Environment Variables

On Unix/Linux:

bashCopy code
export CYCODE_CLIENT_ID={your Cycode ID}

and

bashCopy code
export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

If your organization uses OIDC authentication, you can provide the ID token instead (or in addition):

bashCopy code
export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

On Windows

1. From the Control Panel, navigate to the System menu:

2. Next, click Advanced system settings:

3. In the System Properties window that opens, click the Environment Variables button:

4. Create CYCODE_CLIENT_ID and CYCODE_CLIENT_SECRET variables with values matching your ID and Secret Key, respectively. If you authenticate via OIDC, add CYCODE_ID_TOKEN with your OIDC ID token value as well:

5. Insert the cycode.exe into the path to complete the installation.

Install Pre-Commit Hook

Cycode's pre-commit and pre-push hooks can be set up within your local repository so that the Cycode CLI application will identify any issues with your code automatically before you commit or push it to your codebase.

[!NOTE] pre-commit and pre-push hooks are not available for IaC scans.

Perform the following steps to install the pre-commit hook:

Installing Pre-Commit Hook

1. Install the pre-commit framework (Python 3.9 or higher must be installed):

   bashCopy code
   pip3 install pre-commit
   

2. Navigate to the top directory of the local Git repository you wish to configure.

3. Create a new YAML file named .pre-commit-config.yaml (include the beginning .) in the repository’s top directory that contains the following:

   yamlCopy code
   repos:
     - repo: https://github.com/cycodehq/cycode-cli
       rev: v3.5.0
       hooks:
         - id: cycode
           stages: [pre-commit]
   

4. Modify the created file for your specific needs. Use hook ID cycode to enable scan for Secrets. Use hook ID cycode-sca to enable SCA scan. Use hook ID cycode-sast to enable SAST scan. If you want to enable all scanning types, use this configuration:

   yamlCopy code
   repos:
     - repo: https://github.com/cycodehq/cycode-cli
       rev: v3.5.0
       hooks:
         - id: cycode
           stages: [pre-commit]
         - id: cycode-sca
           stages: [pre-commit]
         - id: cycode-sast
           stages: [pre-commit]
   

5. Install Cycode’s hook:

   bashCopy code
   pre-commit install
   

   A successful hook installation will result in the message: Pre-commit installed at .git/hooks/pre-commit.

6. Keep the pre-commit hook up to date:

   bashCopy code
   pre-commit autoupdate
   

   It will automatically bump rev in .pre-commit-config.yaml to the latest available version of Cycode CLI.

[!NOTE] Trigger happens on git commit command. Hook triggers only on the files that are staged for commit.

Installing Pre-Push Hook

To install the pre-push hook in addition to or instead of the pre-commit hook:

1. Add the pre-push hooks to your .pre-commit-config.yaml file:

   yamlCopy code
   repos:
     - repo: https://github.com/cycodehq/cycode-cli
       rev: v3.5.0
       hooks:
         - id: cycode-pre-push
           stages: [pre-push]
   

2. Install the pre-push hook:

   bashCopy code
   pre-commit install --hook-type pre-push
   

3. For both pre-commit and pre-push hooks, use:

   bashCopy code
   pre-commit install
   pre-commit install --hook-type pre-push
   

[!NOTE] Pre-push hooks trigger on git push command and scan only the commits about to be pushed.

Cycode CLI Commands

The following are the options and commands available with the Cycode CLI application:

Certificates and Proxies

By default, Cycode CLI verifies HTTPS connections against the CA bundle shipped with the CLI.

If your organization uses a proxy that inspects HTTPS traffic, or an on-premises installation with its own CA, you have two options.

Option 1 — use the certificates already installed on the machine. If your CA is in the machine certificate store (as is usually the case on a managed device), opt in:

bashCopy code
export CYCODE_CLI_ENABLE_TRUSTSTORE=1

The CLI then verifies against the Windows certificate store, the macOS Keychain, or the system CA directory on Linux, and no certificate paths need to be configured.

[!IMPORTANT] This is opt-in on purpose. Trusting the machine store means trusting every root certificate present on that machine, including any an administrator or malicious software installed. Enable it when you know your machine's certificate store is one you trust.

Option 2 — point the CLI at a CA bundle file. Works without opting in:

The two options combine: with CYCODE_CLI_ENABLE_TRUSTSTORE=1, certificates from REQUESTS_CA_BUNDLE are trusted in addition to the machine store, not instead of it.

[!TIP] Run any command with -v to see which trust source is in use, for example cycode -v status.

Notes:

• CYCODE_CLI_ENABLE_TRUSTSTORE requires Python 3.10 or newer. On Python 3.9 the CLI logs a warning and falls back to the bundled CA bundle; use REQUESTS_CA_BUNDLE instead, or upgrade Python. The standalone executables and the Docker image already ship a supported Python.
• On Windows, the CLI has always fallen back to the system certificate store when neither REQUESTS_CA_BUNDLE nor CURL_CA_BUNDLE is set. That behavior is unchanged.
• Proxies themselves are configured with the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables.

MCP Command [EXPERIMENT]

[!WARNING] The MCP command is available only for Python 3.10 and above. If you're using an earlier Python version, this command will not be available.

The Model Context Protocol (MCP) command allows you to start an MCP server that exposes Cycode's scanning capabilities to AI systems and applications. This enables AI models to interact with Cycode CLI tools via a standardized protocol.

[!TIP] For the best experience, install Cycode CLI globally on your system using pip install cycode or brew install cycode, then authenticate once with cycode auth. After global installation and authentication, you won't need to configure CYCODE_CLIENT_ID and CYCODE_CLIENT_SECRET environment variables in your MCP configuration files.

Starting the MCP Server

To start the MCP server, use the following command:

bashCopy code
cycode mcp

By default, this starts the server using the stdio transport, which is suitable for local integrations and AI applications that can spawn subprocesses.

Available Options

MCP Tools

The MCP server provides the following tools that AI systems can use:

Each scan tool accepts two mutually exclusive input modes:

• paths (preferred) — one or more file or directory paths that exist on disk. Directories are scanned recursively. The Cycode engine handles file discovery and filtering, just as cycode scan -t <type> path ./src does from the CLI.
• files (fallback) — a dictionary mapping file paths to their full content as strings. Use this only when the files are not available on disk (e.g. in-memory edits not yet saved).

[!TIP] Use paths whenever possible. Passing large files (like package-lock.json) as inline content can exceed token limits and slow down the AI client. With paths, the Cycode engine reads files directly from disk.

All scan tools return a JSON object that includes a "summary" field with a human-readable violation count (e.g. "Cycode found 3 violations: 1 CRITICAL, 2 HIGH.") in addition to the full "detections" array.

Usage Examples

Basic Command Examples

Start the MCP server with default settings (stdio transport):

bashCopy code
cycode mcp

Start the MCP server with explicit stdio transport:

bashCopy code
cycode mcp -t stdio

Start the MCP server with Server-Sent Events (SSE) transport:

bashCopy code
cycode mcp -t sse -p 8080

Start the MCP server with streamable HTTP transport on custom host and port:

bashCopy code
cycode mcp -t streamable-http -H 0.0.0.0 -p 9000

Learn more about MCP Transport types in the MCP Protocol Specification – Transports.

Configuration Examples

Using MCP with Cursor/VS Code/Claude Desktop/etc (mcp.json)

[!NOTE] For EU Cycode environments, make sure to set the appropriate CYCODE_API_URL and CYCODE_APP_URL values in the environment variables (e.g., https://api.eu.cycode.com and https://app.eu.cycode.com).

Follow this guide to configure the MCP server in your VS Code/GitHub Copilot. Keep in mind that in settings.json, there is an mcp object containing a nested servers sub-object, rather than a standalone mcpServers object.

For stdio transport (direct execution):

jsonCopy code
{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

For stdio transport with pipx installation:

jsonCopy code
{
  "mcpServers": {
    "cycode": {
      "command": "pipx",
      "args": ["run", "cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

For stdio transport with uvx installation:

jsonCopy code
{
  "mcpServers": {
    "cycode": {
      "command": "uvx",
      "args": ["cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

For SSE transport (Server-Sent Events):

jsonCopy code
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

For SSE transport on custom port:

jsonCopy code
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

For streamable HTTP transport:

jsonCopy code
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Running MCP Server in Background

For SSE transport (start server first, then configure client):

bashCopy code
# Start the MCP server in the background
cycode mcp -t sse -p 8000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

For streamable HTTP transport:

bashCopy code
# Start the MCP server in the background
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.2:9000/mcp"
    }
  }
}

Advanced Configuration

Timeouts and Custom Certificates (Proxy Environments)

If long-running scans are being cut short by your MCP client, increase the tool call timeout.

Behind a corporate proxy, set the certificate variables in the MCP server's env block. See Certificates and Proxies for the options: either CYCODE_CLI_ENABLE_TRUSTSTORE=1 to use the certificates already on the machine, or REQUESTS_CA_BUNDLE pointing at a CA bundle file.

Example mcp.json configuration with a custom CA bundle and a longer timeout:

jsonCopy code
{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
        "MCP_TOOL_TIMEOUT": "1800"
      }
    }
  }
}

[!NOTE] The MCP server requires proper Cycode CLI authentication to function. Make sure you have authenticated using cycode auth or configured your credentials before starting the MCP server.

Pre-authorizing Tools for Subagents (Claude Code)

When Claude Code delegates work to background subagents (e.g. to run scans in parallel), those subagents cannot display interactive permission prompts. If the Cycode tools have not been pre-approved, scans will fail silently in subagent contexts.

To pre-authorize the Cycode MCP tools so they work in all contexts including subagents, add them to the allowedTools list in your Claude Code settings (~/.claude/settings.json):

jsonCopy code
{
  "allowedTools": [
    "mcp__cycode__cycode_secret_scan",
    "mcp__cycode__cycode_sca_scan",
    "mcp__cycode__cycode_iac_scan",
    "mcp__cycode__cycode_sast_scan",
    "mcp__cycode__cycode_status"
  ]
}

Once added, Claude Code will not prompt for approval when these tools are called, and they will work correctly inside subagents.

Troubleshooting MCP

If you encounter issues with the MCP server, you can enable debug logging to get more detailed information about what's happening. There are two ways to enable debug logging:

1. Using the -v or --verbose flag:

bashCopy code
cycode -v mcp

2. Using the CYCODE_CLI_VERBOSE environment variable:

bashCopy code
CYCODE_CLI_VERBOSE=1 cycode mcp

The debug logs will show detailed information about:

• Server startup and configuration
• Connection attempts and status
• Tool execution and results
• Any errors or warnings that occur

This information can be helpful when:

• Diagnosing connection issues
• Understanding why certain tools aren't working
• Identifying authentication problems
• Debugging transport-specific issues

MCP Configuration

Platform Command [BETA]

[!WARNING] The platform command is in beta. Commands, arguments, and output formats are generated dynamically from the Cycode API spec and may change between releases without notice. Do not rely on them in production automation yet.

The cycode platform command exposes the Cycode platform's read APIs as CLI commands. It groups endpoints by resource (e.g. projects, violations, workflows) and turns each endpoint's parameters into typed CLI arguments and --option flags.

bashCopy code
cycode platform projects list --page-size 50
cycode platform violations count
cycode platform workflows view <workflow-id>

The OpenAPI spec is fetched from the Cycode API on first use and cached at ~/.cycode/openapi-spec.json for 24 hours. Unrelated commands (cycode scan, cycode status, etc.) do not trigger a fetch.

[!NOTE] You must be authenticated (cycode auth or CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET environment variables) for cycode platform to discover and run commands. Other Cycode CLI commands work without authentication.

Discovering Commands

Because commands are generated from the spec, the source of truth for what's available is --help:

bashCopy code
cycode platform --help                  # list all resource groups
cycode platform projects --help         # list actions on a resource
cycode platform projects list --help    # list options/arguments for an action

Platform Examples

bashCopy code
# List projects with pagination
cycode platform projects list --page-size 25

# View a single project by ID
cycode platform projects view <project-id>

# Count violations across the tenant
cycode platform violations count

# Filter using query parameters (see `--help` for what each endpoint supports)
cycode platform violations list --severity CRITICAL

All output is JSON by default — pipe it through jq for ad-hoc filtering:

bashCopy code
cycode platform projects list --page-size 100 | jq '.items[].name'

Platform Notes & Limitations

• Read-only today. Only GET endpoints are exposed in this beta.
• Spec-driven. Adding a new endpoint to the API surfaces it automatically the next time the cache is refreshed.
• No bundled spec. The first cycode platform invocation after install (or after the 24h cache expires) performs a network fetch. On slow connections this first call may take a few seconds; subsequent calls are near-instant until the cache expires.
• Override the cache TTL with CYCODE_SPEC_CACHE_TTL=<seconds>.

AI Guardrails [BETA]

AI Guardrails installs hooks into supported AI coding agents (Claude Code, Cursor, Copilot, Codex) so that prompts, files the agent reads, and MCP tool arguments are scanned for secrets before they reach the model.

Data Collected by AI Guardrails

Scanning happens server-side, so the scanned content leaves the machine: the prompt text, the contents of files the agent reads, and MCP tool arguments are sent to your Cycode tenant to be checked for secrets.

Each event is also reported with context about the developer and the machine, so a finding can be attributed to the device and user it came from. Some of this is personal data:

• Device identifiers — the machine's hostname and hardware serial number.
• User identifiers — the email address of the user signed in to the AI coding agent, and the local operating-system username.
• Environment details — operating system and version, the AI agent, its version and the model in use, the contents of the agent's MCP configuration files, and its enabled plugins.

The hardware serial number is cached in a local temporary file, readable only by the user who ran the command, so repeated hook invocations don't re-query the hardware.

If collecting this data is not acceptable in your environment, do not install the guardrails hooks (cycode ai-guardrails uninstall removes hooks that are already installed).

Scan Command

Running a Scan

The Cycode CLI application offers several types of scans so that you can choose the option that best fits your case. The following are the current options and commands available:

Options

Severity Option

To limit the results of the scan to a specific severity threshold, the argument --severity-threshold can be added to the scan command.

For example, the following command will scan the repository for policy violations that have severity of Medium or higher:

cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase

Monitor Option

[!NOTE] This option is only available to SCA scans.

To push scan results tied to the SCA policies found in an SCA type scan to Cycode, add the argument --monitor to the scan command.

For example, the following command will scan the repository for SCA policy violations and push them to Cycode platform:

cycode scan -t sca --monitor repository ~/home/git/codebase

Cycode Report Option

For every scan performed using the Cycode CLI, a report is automatically generated and its results are sent to Cycode. These results are tied to the relevant policies (e.g., SCA policies for Repository scans) within the Cycode platform.

To have the direct URL to this Cycode report printed in your CLI output after the scan completes, add the argument --cycode-report to your scan command.

cycode scan --cycode-report repository ~/home/git/codebase

All scan results from the CLI will appear in the CLI Logs section of Cycode. If you included the --cycode-report flag in your command, a direct link to the specific report will be displayed in your terminal following the scan results.

[!WARNING] You must have the owner or admin role in Cycode to view this page.

The report page will look something like below:

Package Vulnerabilities Option

[!NOTE] This option is only available to SCA scans.

To scan a specific package vulnerability of your local repository, add the argument --sca-scan package-vulnerabilities following the -t sca or --scan-type sca option.

In the previous example, if you wanted to only run an SCA scan on package vulnerabilities, you could execute the following:

cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase

License Compliance Option

[!NOTE] This option is only available to SCA scans.

To scan a specific branch of your local repository, add the argument --sca-scan license-compliance followed by the name of the branch you wish to scan.

In the previous example, if you wanted to only scan a branch named dev, you could execute the following:

cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev

Unmaintained Packages Option

[!NOTE] This option is only available to SCA scans.

To scan only for unmaintained packages (packages whose OpenSSF Scorecard Maintained check is low, meaning little or no recent commit and issue activity), add the argument --sca-scan unmaintained-packages following the -t sca or --scan-type sca option.

[!NOTE] Whether unmaintained packages are reported at all is controlled by your organization's policy. This option narrows what a scan reports; it cannot enable a policy that is turned off for your tenant.

In the previous example, if you wanted to only run an SCA scan on unmaintained packages, you could execute the following:

cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase

Lock Restore Option

[!NOTE] This option is only available to SCA scans.

When running an SCA scan, Cycode CLI automatically attempts to restore (generate) a dependency lockfile for each supported manifest file it finds. This allows scanning transitive dependencies, not just the ones listed directly in the manifest. To skip this step and scan only direct dependencies, use the --no-restore flag.

The following ecosystems support automatic lockfile restoration:

If a lockfile already exists alongside the manifest, Cycode reads it directly without running any install command.

SBT prerequisite: The sbt-dependency-lock plugin must be installed. Add the following line to project/plugins.sbt:

textCopy code
addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "1.5.1")

Stop on Error Option

By default, Cycode continues scanning even if a file cannot be read (e.g. due to a permission error) or a dependency lockfile cannot be generated during an SCA scan. The failed item is skipped with a warning and the scan proceeds with the remaining files.

Use --stop-on-error to change this behaviour: the scan aborts immediately on the first such failure and reports the error.

bashCopy code
cycode scan -t sca --stop-on-error path ~/home/git/codebase

This is useful in CI pipelines where a silent failure would produce an incomplete scan result. When --stop-on-error is triggered you can either fix the underlying issue or, for SCA restore failures specifically, add --no-restore to skip lockfile generation and scan direct dependencies only.

When --stop-on-error is used, the CLI distinguishes between scan errors and policy violations via exit codes:

Repository Scan

A repository scan examines an entire local repository for any exposed secrets or insecure misconfigurations. This more holistic scan type looks at everything: the current state of your repository and its commit history. It will look not only for secrets that are currently exposed within the repository but previously deleted secrets as well.

To execute a full repository scan, execute the following:

cycode scan repository {{path}}

For example, if you wanted to scan a repository stored in ~/home/git/codebase, you could execute the following:

cycode scan repository ~/home/git/codebase

The following option is available for use with this command:

Branch Option

To scan a specific branch of your local repository, add the argument -b (alternatively, --branch) followed by the name of the branch you wish to scan.

Given the previous example, if you wanted to only scan a branch named dev, you could execute the following:

cycode scan repository ~/home/git/codebase -b dev

Path Scan

A path scan examines a specific local directory and all the contents within it, instead of focusing solely on a GIT repository.

To execute a directory scan, execute the following:

cycode scan path {{path}}

For example, consider a scenario in which you want to scan the directory located at ~/home/git/codebase. You could then execute the following:

cycode scan path ~/home/git/codebase

Terraform Plan Scan

Cycode CLI supports Terraform plan scanning (supporting Terraform 0.12 and later)

Terraform plan file must be in JSON format (having .json extension)

If you just have a configuration file, you can generate a plan by doing the following:

1. Initialize a working directory that contains Terraform configuration file:

   terraform init

2. Create Terraform execution plan and save the binary output:

   terraform plan -out={tfplan_output}

3. Convert the binary output file into readable JSON:

   terraform show -json {tfplan_output} > {tfplan}.json

4. Scan your {tfplan}.json with Cycode CLI:

   cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json

Commit History Scan

[!NOTE] Commit History Scan is not available for IaC scans.

The commit history scan command provides two main capabilities:

1. Full History Scanning: Analyze all commits in the repository history
2. Diff Scanning: Scan only the changes between specific commits

Secrets scanning can analyze all commits in the repository history because secrets introduced and later removed can still be leaked or exposed. For SCA and SAST scans, the commit history command focuses on scanning the differences/changes between commits, making it perfect for pull request reviews and incremental scanning.

A commit history scan examines your Git repository's commit history and can be used both for comprehensive historical analysis and targeted diff scanning of specific changes.

To execute a commit history scan, execute the following:

cycode scan commit-history {{path}}

For example, consider a scenario in which you want to scan the commit history for a repository stored in ~/home/git/codebase. You could then execute the following:

cycode scan commit-history ~/home/git/codebase

The following options are available for use with this command:

Commit Range Option (Diff Scanning)

The commit range option enables diff scanning – scanning only the changes between specific commits instead of the entire repository history. This is particularly useful for:

• Pull request validation: Scan only the changes introduced in a PR
• Incremental CI/CD scanning: Focus on recent changes rather than the entire codebase
• Feature branch review: Compare changes against main/master branch
• Performance optimization: Faster scans by limiting scope to relevant changes

Commit Range Syntax

The --commit-range (-r) option supports standard Git revision syntax:

Diff Scanning Examples

Scan changes in the last commit:

bashCopy code
cycode scan commit-history -r HEAD~1 ~/home/git/codebase

Scan changes between two specific commits:

bashCopy code
cycode scan commit-history -r abc123..def456 ~/home/git/codebase

Scan changes in your feature branch compared to main:

bashCopy code
cycode scan commit-history -r main..HEAD ~/home/git/codebase

Scan changes between main and a feature branch:

bashCopy code
cycode scan commit-history -r main..feature-branch ~/home/git/codebase

Scan all changes in the last 3 commits:

bashCopy code
cycode scan commit-history -r HEAD~3..HEAD ~/home/git/codebase

[!TIP] For CI/CD pipelines, you can use environment variables like ${{ github.event.pull_request.base.sha }}..${{ github.sha }} (GitHub Actions) or $CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA (GitLab CI) to scan only PR/MR changes.

Pre-Commit Scan

A pre-commit scan automatically identifies any issues before you commit changes to your repository. There is no need to manually execute this scan; configure the pre-commit hook as detailed under the Installation section of this guide.

After installing the pre-commit hook, you may occasionally wish to skip scanning during a specific commit. To do this, add the following to your git command to skip scanning for a single commit:

bashCopy code
SKIP=cycode git commit -m <your commit message>`

Pre-Push Scan

A pre-push scan automatically identifies any issues before you push changes to the remote repository. This hook runs on the client side and sc