> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cybedefend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Options for Local Scanner

> Quickly install and use the CybeDefend CLI to scan your code locally, fetch results, and integrate secure checks into CI/CD.

The **CybeDefend CLI** provides an efficient way to run local code scans and view results on our platform. It supports **Linux, macOS, and Windows** and is easily integrated into **CI/CD pipelines** or used in **offline** environments.

## Usage

```bash theme={null}
cybedefend [command] [flags]
```

```bash theme={null}
CybeDefend CLI is a CLI tool to interact with the CybeDefend API.

Usage:
  cybedefend [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  login       Authenticate with CybeDefend (OAuth browser flow or PAT)
  logout      Clear stored credentials
  results     Get scan results
  scan        Start a new scan
  version     Show the version of cybedefend

Flags:
      --api-url string    API URL (default "https://api-us.cybedefend.com")
      --region string     Platform region: us or eu (default "us")
      --ci                CI mode
      --config string     Config file (default is $HOME/.cybedefend/config.yaml) (optional)
      --debug             Debug mode
  -h, --help              help for cybedefend

Use "cybedefend [command] --help" for more information about a command.
```

## Installation

You can install the CybeDefend CLI using one of the following methods:

### 1. Pre-built Binaries

**Supported Platforms:**

* **macOS**: `cybedefend-darwin-amd64` (Intel) or `cybedefend-darwin-arm64` (Apple Silicon M1/M2)
* **Linux**: `cybedefend-linux-amd64` (64-bit) or `cybedefend-linux-386` (32-bit)
* **Windows**: `cybedefend-windows-amd64.exe` (64-bit) or `cybedefend-windows-386.exe` (32-bit)

**Installation Steps:**

1. **Download** the latest release for your platform from the [GitHub Releases page](https://github.com/CybeDefend/cybedefend-cli/releases)
2. **Make Executable** (Linux/macOS):
   ```bash theme={null}
   chmod +x cybedefend-<platform>
   ```
3. **Move to PATH**:
   ```bash theme={null}
   sudo mv cybedefend-<platform> /usr/local/bin/cybedefend
   ```
4. **Verify Installation**:
   ```bash theme={null}
   cybedefend version
   ```

### 2. Build from Source

```bash theme={null}
# Ensure you have Go installed
git clone https://github.com/CybeDefend/cybedefend-cli.git
cd cybedefend-cli
go build -o cybedefend
# Move the binary to your PATH
sudo mv cybedefend /usr/local/bin/
cybedefend version
```

### 3. Docker Image

A pre-built Docker image is available on GitHub Container Registry:

```bash theme={null}
docker pull ghcr.io/cybedefend/cybedefend-cli:latest

# Example usage:
docker run --rm -v $(pwd):/app -w /app \
       -e CYBEDEFEND_PAT=$CYBEDEFEND_PAT \
       -e CYBEDEFEND_PROJECT_ID=$CYBEDEFEND_PROJECT_ID \
       ghcr.io/cybedefend/cybedefend-cli:latest scan --dir . --ci
```

***

## Authentication

The CLI supports two authentication modes. Both store credentials in `~/.cybedefend/credentials.json` and are picked up automatically by subsequent commands.

### OAuth Browser Flow (recommended for local use)

```bash theme={null}
cybedefend login --region eu
```

Opens the CybeDefend login page in your default browser. After completing authentication, the CLI stores your session automatically. Access tokens are refreshed transparently when they expire.

### PAT-Based Login (recommended for CI/CD)

```bash theme={null}
cybedefend login --pat YOUR_PAT --region eu
```

Validates your Personal Access Token and saves it locally. All subsequent commands use it automatically.

```bash theme={null}
# One-time login
cybedefend login --pat YOUR_PAT --region eu

# From now on, no credentials needed per-command
cybedefend scan --dir .
cybedefend results --project-id YOUR_PROJECT_ID
```

### Environment Variable (no login step)

For CI/CD environments, skip `cybedefend login` entirely and set the PAT as an environment variable:

```bash theme={null}
export CYBEDEFEND_PAT=your_pat_here
```

### Credential Priority Order

1. `--pat` flag (highest priority)
2. `CYBEDEFEND_PAT` environment variable
3. `pat` field in config file
4. Stored credentials from `cybedefend login`

### Logout

```bash theme={null}
cybedefend logout
```

Deletes `~/.cybedefend/credentials.json` and clears the stored session.

<Warning>
  **Deprecated**: The `--api-key` flag has been removed. API Keys are no longer supported.
</Warning>

***

## Configuration

**Config File** (`config.yaml` in `./`, `$HOME/.cybedefend`, or `/etc/cybedefend`):

```yaml theme={null}
api_url: "https://api-us.cybedefend.com"  # Default if not overridden
pat: "your-personal-access-token"  # PAT from Profile → Personal Access Tokens
project_id: "your-project-id"
# Optional: choose region (us/eu)
# region: "eu"
```

**Environment Variables:**

* `CYBEDEFEND_API_URL` - API base URL
* `CYBEDEFEND_REGION` - Platform region (`us` or `eu`). Ignored if `CYBEDEFEND_API_URL` is set
* `CYBEDEFEND_PAT` - Personal Access Token (PAT) for authentication
* `CYBEDEFEND_PROJECT_ID` - Default project ID

**Command-Line Flags** (override config and env vars):

* `--region` - Platform region (`us` or `eu`). Selects `https://api-us.cybedefend.com` or `https://api-eu.cybedefend.com`
* `--api-url` - API base URL (manual override; takes precedence over `--region`)
* `--project-id` - Project ID

> **Deprecated**: The `--api-key` flag and `CYBEDEFEND_API_KEY` environment variable have been removed. Use `CYBEDEFEND_PAT` with a Personal Access Token instead.

***

## Commands

### 1. `scan`

```bash theme={null}
cybedefend scan [flags]
```

Starts a new scan by uploading a directory or a pre-zipped file to the CybeDefend platform. By default, the command waits for the scan to complete and displays a summary of findings.

**Flags:**

* `--dir, -d` - Directory to scan (will be zipped before uploading). Cannot be used with `--file`
* `--file, -f` - Pre-zipped file to scan. Cannot be used with `--dir`
* `--project-id` - Project ID for the scan (required if not set in config/env)
* `--region` - Platform region: `us` (default) or `eu`
* `--api-url` - Manual API URL override (takes precedence over `--region`)
* `--wait, -w` - Wait for scan completion before exiting (default: `true`)
* `--interval` - Polling interval in seconds when waiting (default: `5`)
* `--break-on-fail` - Exit with error code if scan fails (default: `false`)
* `--break-on-severity` - Exit with error code if vulnerabilities of specified severity or higher are found. Values: `critical`, `high`, `medium`, `low`
* `--ci` - CI/CD-friendly output (no colors, ASCII art, or extra formatting)

#### Examples

```bash theme={null}
# Scan a directory, wait for completion, and show summary (default behavior)
# Assumes PAT is set via `cybedefend login` or CYBEDEFEND_PAT env var
cybedefend scan --dir ./my-app --project-id your-project-id

# Scan a pre-zipped file (PAT must be configured via login or env var)
cybedefend scan --file ./my-app.zip --project-id your-project-id

# Start a scan but don't wait for completion
cybedefend scan --dir ./my-app --project-id your-project-id --wait=false

# Scan, wait, and fail the CI job if the scan process itself fails
cybedefend scan --dir ./my-app --project-id your-project-id --break-on-fail

# Scan, wait, and fail the CI job if any CRITICAL vulnerabilities are found
cybedefend scan --dir ./my-app --project-id your-project-id --break-on-severity critical

# Scan, wait, and fail the CI job if any MEDIUM or higher vulnerabilities are found
cybedefend scan --dir ./my-app --project-id your-project-id --break-on-severity medium

# Select the EU region
cybedefend scan --dir ./my-app --region eu

# Manually override the API URL
cybedefend scan --dir ./my-app --api-url https://api-eu.cybedefend.com

# Change polling interval to 10 seconds
cybedefend scan --dir ./my-app --interval 10

# CI-friendly mode
cybedefend scan --dir ./my-app --ci
```

### 2. `results`

```bash theme={null}
cybedefend results [flags]
```

Retrieves scan results for a specific project. By default, fetches SAST results in JSON format and saves to `results.json` in the current directory.

**Flags:**

* `--project-id` - Project ID to fetch results (required if not set in config/env)
* `--type, -t` - Type of results: `sast` (default) or `iac`
* `--page, -p` - Page number to fetch (default: `1`). Ignored if `--all` is set
* `--all, -a` - Fetch all results across all pages
* `--output, -o` - Output format: `json` (default), `html`, or `sarif`
* `--filename, -f` - Output file name (default: `results.json`)
* `--filepath` - Path to save file (default: `.`)
* `--ci` - CI/CD-friendly output

#### Examples

```bash theme={null}
cybedefend results --project-id your-project-id
cybedefend results --all --output html --filename results.html
cybedefend results --type iac --output sarif --filepath ./reports
```

### 3. `version`

Displays the CLI version:

```bash theme={null}
cybedefend version
```

### 4. `completion`

Generates shell autocompletion for bash, zsh, etc.:

```bash theme={null}
cybedefend completion [shell]
```

***

## CI/CD Integration

Combine the `scan` and `results` commands in your pipelines. The `scan` command's `--wait`, `--break-on-fail`, and `--break-on-severity` flags are particularly useful for controlling pipeline flow based on scan outcomes.

For example, in GitHub Actions:

```yaml theme={null}
- name: Install CybeDefend CLI # Or use the Docker image method
  run: |
    # Download commands...
    curl -L https://github.com/CybeDefend/cybedefend-cli/releases/latest/download/cybedefend-linux-amd64 -o cybedefend
    chmod +x cybedefend
    sudo mv cybedefend /usr/local/bin/

- name: Run security scan and break on High severity
  env:
    CYBEDEFEND_PAT: ${{ secrets.CYBEDEFEND_PAT }}
  run: cybedefend scan --dir ./ --ci \
         --project-id ${{ secrets.CYBEDEFEND_PROJECT_ID }} \
         --break-on-severity high # Fail build if High or Critical vulns found

# Optionally, fetch detailed results artifact if needed, e.g., for reporting
# This step might only run if the previous one succeeded, depending on workflow setup
- name: Fetch Detailed Results as SARIF
  env:
    CYBEDEFEND_PAT: ${{ secrets.CYBEDEFEND_PAT }}
  run: cybedefend results --project-id ${{ secrets.CYBEDEFEND_PROJECT_ID }} \
                          --output sarif --filename results.sarif --ci

# - name: Upload SARIF results (Example using GitHub action)
#   uses: github/codeql-action/upload-sarif@v2
#   with:
#     sarif_file: results.sarif
```

Use `--ci` for minimal logs during the scan. The `--break-on-*` flags allow automatic build failure based on your security policies. You can still use `cybedefend results` to fetch detailed reports if the scan passes the break conditions or if you need the data regardless.

***

**Related:** [Code Repository Scanning](/latest/code-scanning/scanning-options/code-repository-scanning) · [CI/CD Integrations](/latest/code-scanning/ci-cd-integrations/github-actions) · [GitHub CLI Repository](https://github.com/CybeDefend/cybedefend-cli)