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

# ZeroPath CLI

> Command-line access to ZeroPath's AI-powered security scanning platform

## Overview

ZeroPath CLI provides command-line access to ZeroPath's AI-powered security scanning platform. Upload and scan your code directly from your terminal with support for multiple output formats and CI/CD integration.

<Card title="Get the CLI" icon="github" href="https://github.com/ZeroPathAI/zeropath-cli">
  Download the latest release from our GitHub repository
</Card>

## What ZeroPath CLI Detects

The CLI scans for a comprehensive range of security vulnerabilities:

* **Authentication and authorization vulnerabilities**
* **Application logic flaws**
* **Dependency issues**
* **Security misconfigurations**
* **Command injection vulnerabilities**
* **File inclusion and path traversal attacks**
* **Secrets and hardcoded credentials**

## Quick Start

```bash theme={null}
# Install CLI (see installation guide)
# Authenticate with your API credentials
zeropath auth <clientId> <clientSecret>

# Scan current directory
zeropath scan . output.sarif

# Scan by repository ID
zeropath scan --repository-id <repositoryId>

# Scan by repository URL
zeropath scan --repository-url https://github.com/owner/repo --vcs github
```

`--vcs` accepts `github`, `gitlab`, `bitbucket`, `gerrit`, `generic`, and `cvs`.

## Core Commands

### Authentication

```bash theme={null}
# Authenticate with API credentials
zeropath auth <clientId> <clientSecret>
```

### Local Directory Scanning

```bash theme={null}
# Basic scan
zeropath scan <directory> <outputFile.sarif>

# Example
zeropath scan ./my-project results.sarif
```

### Repository Scanning

```bash theme={null}
# Scan by repository ID
zeropath scan --repository-id <repositoryId>

# Scan by repository URL
zeropath scan --repository-url https://github.com/owner/repo --vcs github
```

### On-Demand Code Scans Beta

Use `scan-code` to submit a diff, file, file set, or snippet for asynchronous
security review without starting a full repository scan.

```bash theme={null}
# Scan the current Git working-tree diff
zeropath scan-code --diff

# Scan staged changes
zeropath scan-code --staged

# Scan one file
zeropath scan-code --file src/api.ts

# Force standalone mode when you do not want linked repository context
zeropath scan-code --diff --standalone
```

By default, `scan-code` uses your Git remote URL to automatically use linked
repository context when exactly one accessible ZeroPath repository matches. If
there is no match, it runs as a standalone scan.

<Warning>
  On-Demand Code Scans are currently in beta. Behavior, limits, and response
  fields may change before general availability.
</Warning>

See [On-Demand Code Scans Beta](/docs/developer-tools/async-code-scans) for request
formats, target modes, limits, and API examples.

### Container Scanning

Use the `container` commands to scan built container images for OS-package and
bundled-dependency vulnerabilities. Images can be pulled by registry reference —
including from private registries with credentials — or uploaded as a local
`docker save` archive. Findings are surfaced under the Supply Chain section with
per-layer attribution and base-image upgrade recommendations.

```bash theme={null}
# One-shot scan of a built image
zeropath container test <image>

# Example
zeropath container test registry.example.com/app:1.4.2
```

To scan an image in a private registry, pass registry credentials. ZeroPath
authenticates with them when pulling the image; tokens are transmitted over TLS
and stored encrypted.

```bash theme={null}
# Scan an image from a private registry
zeropath container test registry.example.com/app:1.4.2 \
  --registry-username <username> \
  --registry-token <token>
```

If your organization has a [registry connection](/docs/scanning/container-scanning#connect-a-registry)
configured for the image's registry (Settings → Integrations), reference it by ID instead of
passing credentials inline. `--registry-connection-id` is mutually exclusive with
`--registry-username`/`--registry-token`, and the image's host must match the connection's
registry host. Both `container test` and `container monitor` accept it.

```bash theme={null}
# Scan using a saved registry connection instead of inline credentials
zeropath container test registry.example.com/app:1.4.2 \
  --registry-connection-id <connection-id>
```

For air-gapped images that cannot be pulled, export the image to a tarball with
`docker save` and scan that archive directly with `--file`. Give it a label with
`--name` so it is identifiable in results.

```bash theme={null}
# Export the built image, then scan the archive
docker save -o image.tar registry.example.com/app:1.4.2
zeropath container test --file image.tar --name app-1.4.2
```

<Note>
  Uploaded archives are scanned once and cannot be monitored: there is no registry
  reference to re-pull on a schedule, so `container monitor` rejects `--file`. Use a
  registry image reference for recurring re-scans.
</Note>

By default, `container test` waits for the scan to finish and prints a
human-readable report. The following flags control that behavior:

* `--json` — print the raw response payload as JSON instead of the formatted report.
* `--wait` / `--no-wait` — wait for the scan to complete (the default). Pass
  `--no-wait` to submit the scan and return immediately with the container image ID.
* `--timeout <seconds>` — maximum seconds to wait for completion before exiting
  with an error. Must be a positive number.

```bash theme={null}
# Submit without waiting, emitting JSON for scripting
zeropath container test registry.example.com/app:1.4.2 --no-wait --json

# Wait up to 10 minutes for completion
zeropath container test registry.example.com/app:1.4.2 --timeout 600
```

To keep watching an image after it ships, register it for recurring re-scans.
Monitoring surfaces newly disclosed CVEs against an already-built image without
a manual re-run. `container monitor` also accepts `--json` to print the raw
response payload.

```bash theme={null}
# Monitor an image on the default schedule
zeropath container monitor <image>

# Monitor an image on a custom schedule (crontab expression)
zeropath container monitor <image> --schedule "0 6 * * *"

# Example, emitting JSON
zeropath container monitor registry.example.com/app:1.4.2 --schedule "0 6 * * *" --json
```

#### Repository Linking

Container images can be linked to an onboarded repository so findings appear
alongside that repository's code-scan results. By default, container commands
auto-detect the repository from the current checkout's git remote. You can
control this with:

* `--repository-id <id>` — explicitly link the image to a specific repository,
  overriding auto-detection.
* `--no-auto-repository` — disable auto-detection entirely; the image will not
  be linked to any repository unless `--repository-id` is also provided.

Auto-linking works for `container test`, `container monitor`, and
`container link`.

```bash theme={null}
# Explicitly link the scanned image to a repository
zeropath container test registry.example.com/app:1.4.2 --repository-id <repositoryId>

# Disable auto-linking from the local git remote
zeropath container test registry.example.com/app:1.4.2 --no-auto-repository
```

#### Linking an Existing Image

Use `container link` to link (or re-link) a previously scanned container image
to a repository. This is useful when the image was scanned without a repository
context, or when you need to move it to a different repository.

```bash theme={null}
# Link an image to the repository matching the current checkout
zeropath container link <containerImageId>

# Link an image to a specific repository
zeropath container link <containerImageId> --repository-id <repositoryId>

# Emit JSON output
zeropath container link <containerImageId> --json
```

See [Container Scanning](/docs/scanning/container-scanning) for the end-to-end flow,
per-layer findings, private-registry and local-archive scanning, and base-image
upgrade recommendations.

## CI/CD Integration

The CLI is designed for seamless CI/CD integration — it exits with code 1 when security issues are found or when an error occurs during scanning:

```bash theme={null}
# Scan a repository (exits 1 if issues found)
zeropath scan --repository-id <repositoryId>

# Generate SARIF output (local scan only)
zeropath scan . results.sarif
```

### Scan Timeout

Local directory scans have a maximum polling timeout of approximately 50 minutes. If the scan does not complete within this window, the CLI exits with an error. This prevents CI/CD pipelines from hanging indefinitely on long-running scans.

## Output Formats

ZeroPath CLI supports multiple output formats for different use cases:

* **SARIF**: Standard format for static analysis results (local scans)
* **Console**: Human-readable formatted output for terminal viewing

## Getting API Credentials

To use the CLI, you'll need API credentials from your ZeroPath account:

1. Sign in to [ZeroPath Dashboard](https://zeropath.com/app)
2. Navigate to API Settings
3. Generate new API credentials (Client ID and Client Secret)
4. Use these credentials with `zeropath auth`

CLI requests are automatically identified as originating from the CLI in your
organization's audit logs, so you can distinguish CLI-triggered actions from
browser and other API-token activity without any additional configuration.

## Next Steps

* [Installation Guide](/docs/cli/installation) - Set up the CLI on your system
* [GitHub Repository](https://github.com/ZeroPathAI/zeropath-cli) - Source code and releases
* [API Reference](/docs/api-reference/introduction) - Build custom integrations