# Config and offline mode

You can provide network settings through a JSON config file and optionally combine that with environment variables or CLI flags.

## Config file shape

`--config-file` expects a JSON object. The `network`, `advisories`, and
`performance` fields,
when present, must also be objects.

Example:

```json
{
  "network": {
    "timeout": 20.0,
    "retries": 4,
    "backoff_factor": 0.5,
    "cache_dir": ".trustcheck-cache"
  },
  "advisories": {
    "osv": true,
    "osv_urls": ["https://advisories.example.com"],
    "ecosystems": true,
    "kev": true,
    "kev_url": "https://www.cisa.gov/example/known_exploited.json",
    "epss": true,
    "epss_url": "https://api.first.org/data/v1/epss"
  },
  "performance": {
    "max_workers": 8
  }
}
```

Advisory settings:

- `osv`: enable the public OSV provider
- `osv_urls`: additional OSV-compatible API base URLs
- `ecosystems`: enable the Ecosyste.ms OSV-compatible provider
- `kev`: enable CISA Known Exploited Vulnerabilities enrichment
- `kev_url`: override the KEV JSON feed URL
- `epss`: enable FIRST EPSS enrichment
- `epss_url`: override the EPSS API base URL

CLI provider flags are additive with config-file providers. Duplicate base URLs
are queried once.

## Environment variables

The CLI also recognizes these environment variables:

- `TRUSTCHECK_TIMEOUT`
- `TRUSTCHECK_RETRIES`
- `TRUSTCHECK_BACKOFF`
- `TRUSTCHECK_CACHE_DIR`
- `TRUSTCHECK_OFFLINE`
- `TRUSTCHECK_MAX_WORKERS`

## Precedence

The effective network configuration is resolved from:

1. CLI flags
2. environment variables
3. config file values
4. built-in defaults

## Offline mode

Use `--offline` when you want `trustcheck` to use cached responses only and avoid live network requests.

Example:

```bash
trustcheck inspect sampleproject \
  --version 4.0.0 \
  --cache-dir .trustcheck-cache \
  --offline
```

Offline mode is useful in hermetic CI or for repeated local analysis after an
initial cached run. PyPI responses use a SHA-256 content-addressed persistent
cache with integrity verification.

Use repeatable `--advisory-snapshot PATH` for portable advisory data and
`--write-advisory-snapshot PATH` to create or update a snapshot. KEV and EPSS
data included in normalized snapshot records remains available offline.
Missing package metadata or artifacts still fail closed.

`scan` and `environment` can checkpoint target reports with
`--resume-state PATH`. State is reused only when the source, resolved targets,
policy, providers, indexes, and plugins produce the same fingerprint.

See [Performance and extensibility](../reference/performance-extensibility.md)
for cache layout, batching, resume semantics, and plugin entry points.
