CLI & Environment Variables
Codeward can be configured via CLI arguments, environment variables, and configuration files.
CLI Options
| Option | Argument | Description |
|---|---|---|
-c, --config | PATH | Path to main config file (default: .codeward.json / .codeward.yaml) |
--private-config | PATH | Path to private config file |
-m, --mode | MODE | Scan mode: main or diff |
--log-level | LEVEL | Log verbosity: DEBUG, INFO, WARN, ERROR |
--log-format | FORMAT | Log format: text or json |
--intel-mode | MODE | Intel data source: api, download, local, disabled. Default: api with a token, download without |
--intel-required | BOOL | Fail the scan if no vulnerability data was obtained (default true) |
--intel-classification | BOOL | Use Intel's resolved license category/severity instead of the scanner's built-in table (default false) — see License categories |
--export-diff | PATH | Export full diff results to the specified file as JSON |
-v, --version | - | Show version information |
-h, --help | - | Show help message |
Environment Variables
Core Configuration
| Variable | Description |
|---|---|
CODEWARD_CONFIG_PATH | Path to main config file |
CODEWARD_PRIVATE_CONFIG_PATH | Path to private config file |
CODEWARD_MODE | Execution mode (diff or main) |
CODEWARD_CACHE_DIR | Base cache directory (Intel snapshots, licence cache, query cache) |
CODEWARD_MAIN_PATH | Base checkout to scan. Overrides the container default /main — needed when running the binary directly |
CODEWARD_BRANCH_PATH | Head checkout to scan in diff mode. Overrides the container default /branch |
Logging
| Variable | Description |
|---|---|
CODEWARD_LOG_LEVEL | Global log level (DEBUG, INFO, WARN, ERROR) |
CODEWARD_LOG_FORMAT | Log output format (text or json) |
CODEWARD_LOG_TIMESTAMP | Include timestamps (true or false) |
CODEWARD_LOG_SUMMARY | Summary verbosity (none, minimal, standard, detailed) |
CODEWARD_LOG_OUTPUT | Log output destination (default: stderr) |
GitHub Integration
Required for git:pr and git:issue outputs.
| Variable | Description |
|---|---|
CODEWARD_GITHUB_TOKEN | GitHub API token (sensitive — env only) |
CODEWARD_GITHUB_REPOSITORY | Repository name (e.g., my-project) |
CODEWARD_GITHUB_OWNER | Repository owner (user or organization) |
CODEWARD_GITHUB_PR_NUMBER | Pull request number (integer) |
CODEWARD_GITHUB_BRANCH | Current branch name |
Codeward Intel
Intel is the scanner's vulnerability data source. See Intel for the full picture.
| Variable | Description |
|---|---|
CODEWARD_INTEL_MODE | api, download, local or disabled. Unset selects api when a token is present, download otherwise |
CODEWARD_INTEL_TOKEN | Intel API key with the query:batch scope (sensitive — env only). Required for api mode |
CODEWARD_INTEL_API | Intel API base URL (default: https://intel.codeward.io) |
CODEWARD_INTEL_CACHE | Override the snapshot cache directory (default: <CODEWARD_CACHE_DIR>/intel-snapshots) |
CODEWARD_INTEL_REQUIRED | Fail the scan when no vulnerability data was obtained (default true) |
CODEWARD_INTEL_CLASSIFICATION | Make Intel's resolved license category/severity authoritative over the scanner's built-in table (default false). Gaps are filled from Intel either way; this gates only overruling a local verdict — see License categories |
CODEWARD_INTEL_MIRRORS | Comma-separated snapshot mirror base URLs, replacing the built-in list |
CODEWARD_INTEL_PUBKEY | Override the built-in Ed25519 key used to verify snapshot manifests. none disables verification |
CODEWARD_INTEL_SEGMENTS | Extra snapshot segments to download, by group: cwes, enrichments, rules, or all. Unset downloads only what the detected ecosystems need |
CODEWARD_INTEL_MAX_AGE_DAYS | Days before a snapshot is treated as stale and the scan marked degraded (default 7; 0 disables the warning) |
Scanner
| Variable | Description |
|---|---|
CODEWARD_TEMPLATES_PATH | Path to a directory of custom output templates. Unset uses the templates embedded in the binary |
SARIF Output
| Variable | Description |
|---|---|
CODEWARD_SARIF_OUTPUT | Write all findings as SARIF 2.1.0 to the specified file path |
CODEWARD_SARIF_UPLOAD | Set true to upload SARIF to GitHub Code Scanning (requires CODEWARD_GITHUB_TOKEN) |
SBOM Export
| Variable | Description |
|---|---|
CODEWARD_SBOM_OUTPUT | Export CycloneDX 1.6 SBOM to the specified file path |
API & Tokens
| Variable | Description |
|---|---|
CODEWARD_API | Codeward API endpoint (default: https://api.codeward.io) |
CODEWARD_TOKEN | Codeward API token (sensitive — env only) |
CODEWARD_AI_TOKEN | AI enrichment token (sensitive — env only) |
Webhook Secrets
| Variable | Description |
|---|---|
CODEWARD_WEBHOOK_SECRETS | Multi-line KEY=VALUE pairs exported before scan. Unset after parsing. |
CODEWARD_EXTRA_ENV | Additional KEY=VALUE pairs exported before scan. |
Container only
CODEWARD_WEBHOOK_SECRETS and CODEWARD_EXTRA_ENV are parsed by the image's entrypoint script,
not by the scanner itself. Running the binary directly (including the action's binary runtime),
export the variables yourself.
Precedence
Configuration is resolved in this order (highest to lowest priority):
- CLI arguments (e.g.,
--mode diff) - Environment variables (e.g.,
CODEWARD_MODE=diff) - Config files (
.codeward.yaml/.codeward.json) - Default values
Sensitive Variables
Tokens (CODEWARD_GITHUB_TOKEN, CODEWARD_TOKEN, CODEWARD_AI_TOKEN) are never loaded from config files — environment only.