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

# Dependency Scanning (CLI)

> Build offline dependency inventories, dependency graphs, SBOMs, and policy checks with corgea deps

## Overview

`corgea deps` builds an offline dependency inventory from npm, Python, and Java manifests and lockfiles. It can inspect dependency graphs, explain why a package is present, compare dependency changes, generate a CycloneDX SBOM, and evaluate dependency policy.

`corgea deps` does not require a Corgea account, token, or network access.

## Inventory

Run an offline dependency scan from the project root:

```bash theme={null}
corgea deps scan
```

Common commands:

```bash theme={null}
corgea deps scan --format human
corgea deps scan --format json
corgea deps scan --format quiet --fail-on high
corgea deps scan --out-format sarif --out-file deps.sarif
corgea deps graph --format json
corgea deps explain lodash --format human
corgea deps diff --base origin/main --format json
corgea deps sbom --format cyclonedx --out bom.json
corgea deps policy init --exist-ok
```

Use `--format human`, `agent`, `json`, or `quiet` to control terminal output for `scan`, `graph`, `explain`, `diff`, and `policy init`. In detected agent environments, `corgea deps` defaults to the compact `agent` format; pass `--format human` to force normal terminal output.

For `corgea deps scan`, use `--out-format table`, `json`, or `sarif` with optional `--out-file` when exporting a report. Do not combine `--format` and `--out-format` on the same `deps scan` command.

## Policy

Initialize `.corgea/deps.yml`:

```bash theme={null}
corgea deps policy init
```

The generated policy controls whether lockfiles are required, missing or stale lockfiles fail, and direct dependencies using wildcards, `latest`, or semver ranges are reported.

```yaml theme={null}
dependency_policy:
  require_lockfile: true
  fail_on_missing_lockfile: true
  fail_on_stale_lockfile: true
  direct_dependencies:
    fail_on_wildcard: true
    fail_on_latest: true
    warn_on_semver_range: true
```

<h2 id="ci-integration">
  CI Integration
</h2>

Copy this workflow into `.github/workflows/dependencies.yml`.

```yaml theme={null}
name: Dependency inventory
on:
  pull_request:
  push:
    branches: [main]

jobs:
  corgea-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @corgea/cli
      - name: Check dependency policy
        run: corgea deps scan --format quiet --fail-on high
```

To fail only when a pull request adds new high-severity dependency findings:

```bash theme={null}
corgea deps diff --base origin/main --fail-on-new high --format quiet
```

## Reference

### Commands

| Command                                 | Purpose                                                        | Key flags                                             |
| --------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------- |
| `corgea deps scan [PATH]`               | Scan manifests and lockfiles, build inventory, evaluate policy | `--fail-on`, `--format`, `--out-format`, `--out-file` |
| `corgea deps graph [PATH]`              | Print the dependency graph                                     | `--format`                                            |
| `corgea deps explain <PACKAGE> [PATH]`  | Explain why a package is present                               | `--format`                                            |
| `corgea deps diff --base <BASE> [PATH]` | Compare dependency graph against a git ref                     | `--base`, `--fail-on-new`, `--format`                 |
| `corgea deps sbom [PATH]`               | Generate a CycloneDX SBOM                                      | `--format`, `--out`                                   |
| `corgea deps policy init [PATH]`        | Write a starter `.corgea/deps.yml` policy file                 | `--exist-ok`, `--format`                              |

### Formats

| Flag           | Values                            | Commands                                          |
| -------------- | --------------------------------- | ------------------------------------------------- |
| `--format`     | `human`, `agent`, `json`, `quiet` | `scan`, `graph`, `explain`, `diff`, `policy init` |
| `--out-format` | `table`, `json`, `sarif`          | `scan` only                                       |
| `--format`     | `cyclonedx`                       | `sbom` only                                       |

### Exit Codes

| Exit  | Condition                                                                                                            |
| ----- | -------------------------------------------------------------------------------------------------------------------- |
| **0** | Command completed without a failing policy threshold                                                                 |
| **1** | `deps scan --fail-on` or `deps diff --fail-on-new` found matching findings                                           |
| **2** | Invalid arguments, unsupported formats, bad severity values, missing packages for `explain`, or other command errors |

### Severity Values

`--fail-on` and `--fail-on-new` accept `info`, `low`, `medium`, `high`, or `critical`.

## Troubleshooting

### Format Conflict

`deps scan` rejects commands that combine `--format` with `--out-format`.

```text theme={null}
deps failed: --format cannot be used with --out-format; choose one output selector
```

Use `--format` for terminal rendering and `--out-format` for exported scan reports.

### Package Not Found

`deps explain` exits with code **2** when the package is not present in the scanned dependency graph.

```text theme={null}
deps failed: package not found: package-name
```