cycode-cli

Purpose

Cycode CLI is a command-line application that can be installed locally to scan code repositories for security risks. It covers four types of security scans:

• Secrets: detects secret leakage
• IaC: detects infrastructure as code misconfigurations
• SCA: software composition analysis, detects dependency vulnerabilities
• SAST: static application security testing

Installation

The tool requires Python version 3.10 or higher. Installation methods include:

• Install from PyPI:

pip3 install cycode

• Install from Homebrew:

brew install cycode

• Download the executable file for the corresponding operating system and architecture from GitHub Releases, then run:

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

Authentication

There are three ways to set the Cycode client ID and credentials (client secret or OIDC ID token):

• cycode auth(recommended): After running it in the terminal, a login page will pop up in the browser. Enter your credentials to log in, select the business group to authorize, and click Allow to complete authorization. The terminal will display Successfully logged into cycode. If the client ID and secret have already been set through Linux or Windows environment variables, the environment variables take precedence over this method.
• cycode configure: Interactively enter the Cycode API URL, APP URL, Client ID, Client Secret (can be skipped if using OIDC), and optional OIDC ID Token. On success, it displays Successfully configured CLI credentials! or Successfully configured Cycode URLs!. The credentials are saved in the .cycode folder under the user directory in credentials.yaml, and the URL is saved in config.yamlin the same directory.
• Environment variables: On Windows, you can use the System menu in Control Panel, Advanced system settings, and the Environment Variables button to create CYCODE_CLIENT_ID and CYCODE_CLIENT_SECRET; if using OIDC authentication, you can also add CYCODE_ID_TOKEN, and add cycode.exe to PATH.

Usage

The CLI provides the following command groups:

• Authentication and configuration commands:cycode auth、cycode configure
• scan command: performs scans and supports various options, such as severity threshold, Monitor Cycode, report package vulnerabilities, license compliance, lock, restore, fail on error, etc. Scan scopes include repository scan, branch options, path scan, Terraform Plan scan, commit history scan, commit range options (Diff scan), Pre-Commit scan, local Diff scan (IDE integration), and Pre-Push scan. Scan results can show or hide secrets and support soft fail. Result examples cover Secrets, IaC, SCA, and SAST. It also supports company-custom remediation guidance.
• Ignoring scan results: can be ignored by secret value, secret SHA value, path, secret/IaC/SCA rules, package ignore, or through a configuration file.
• report command: generates an SBOM report.
• platform command: includes command discovery, examples, precautions, and limitations.
• MCP command (experimental): can start an MCP server, including available options, MCP tools, usage examples, and advanced configuration.
• AI Guardrails: explains the data it collects.

Integration into the Git workflow

Cycode's pre-commit and pre-push hooks can be set up in a local repository so that the CLI automatically identifies issues before code is committed or pushed. Note: the pre-commit and pre-push hooks do not support IaC scanning.

Steps to install the pre-commit hook:

1. Install the pre-commit framework (requires Python 3.10 or higher):

pip3 install pre-commit

1. Go to the top-level directory of the local Git repository to configure.
2. Create .pre-commit-config.yamlat the top level of the repository, with example content:

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

It can be modified as needed: hook ID cycode is used for Secrets scanning,cycode-sca for SCA scanning,cycode-sast for SAST scanning. To enable all scan types, configure as:

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

1. Install the hook:

pre-commit install

On success, it prompts Pre-commit installed at .git/hooks/pre-commit.

1. Keep the hook up to date:

pre-commit autoupdate

Automatically updates the rev in .pre-commit-config.yaml to the latest version of the Cycode CLI.

The pre-commit hook is triggered on git commit , and only scans files staged for commit.

To install the pre-push hook: add the following in .pre-commit-config.yaml :

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

Then install:

pre-commit install --hook-type pre-push

To install both hooks at the same time:

pre-commit install
pre-commit install --hook-type pre-push

The pre-push hook is triggered on git push , and only scans the commits about to be pushed.

Certificates and Proxy

By default, the Cycode CLI verifies HTTPS connections using the CA bundle shipped with the CLI. If your organization uses a proxy that inspects HTTPS traffic, or uses a local deployment with its own CA, there are two approaches:

• Approach 1: Use certificates already installed on the machine. If the CA is in the machine certificate store (common on managed devices), you can enable: the CLI will verify against the Windows certificate store, macOS Keychain, or the Linux system CA directory, with no need to configure a certificate path. This option is intentionally opt-in; trusting the machine store means trusting all root certificates on that machine, including certificates installed by administrators or malware. Enable it only when you are sure the machine certificate store is trusted.
• Approach 2: Point the CLI to a CA bundle file, with no opt-in required.

The two approaches can be combined: after setting CYCODE_CLI_ENABLE_TRUSTSTORE=1 , the certificates inREQUESTS_CA_BUNDLE will be trusted alongside the machine store, rather than replacing it. Run any command with -v to view the current trust sources, for example cycode -v status. On Windows, when REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE is not set, the CLI always falls back to the system certificate store.

Applicable Scenarios and Limitations

Suitable for teams that need to improve security throughout the development lifecycle, enabling scanning of repositories for secret leaks, IaC misconfigurations, dependency vulnerabilities, and code security issues at the local development, commit, and push stages. In terms of limitations: the pre-commit and pre-push hooks do not support IaC scanning; MCP commands are marked as experimental; the trust option that uses the machine certificate store must be enabled with caution.