Commands and parameters

This page describes every command and every parameter of codeguard 0.3.5.

Structure of a call

codeguard [globale Optionen] <kommando> [kommando-optionen]

Global options go before the command. Example:

codeguard --format json --output build/codeguard.json check-diff --base main

Global options

Option	Values	Default	Meaning
--format	text, json, sarif, gitlab-sarif	text	Output format. Not every command supports every format (see below).
--config	File path	–	Specify the project configuration explicitly. Disables the automatic search. A relative path is resolved against the current directory.
--no-project-config	Flag	off	Ignore .codeguard.yml/.codeguard.yaml in the project root and use the defaults.
--project-root	Directory	current directory	Project root. Canonicalized via realpath. A path that cannot be resolved is exit 2.
--output	File path	–	Write the report of a check-* run atomically to this file. stdout stays empty.
--ci	Flag	off	Non-interactive CI profile. Local trust tickets do not apply, builds and tests need an attested environment, trust grant is not allowed.
--color	auto, always, never	auto	Color policy. JSON and SARIF never contain ANSI sequences.
-h, --help	–	–	Show help, also per command (codeguard check-diff --help).

Using --config and --no-project-config together is exit 2:

--config and --no-project-config cannot be used together

Which formats each command supports

Command	text	json	sarif / gitlab-sarif	--output
check-file, check-diff, check-project	yes	yes	yes	yes
version, config validate, doctor, trust …	yes	yes	no	no, output always goes to stdout
schema	always prints the JSON schema			no

An unsupported format aborts the run, for example:

Error: version supports only text or json output

Exit 64 for usage errors

Errors detected while parsing the arguments (unknown option, unsupported format for version, doctor, config validate or trust) end with exit 64. This value is not part of the 0–9 exit contract. In scripts, treat every code other than 0 as an error.

version

Prints the binary and schema versions.

codeguard version
codeguard --format json version

codeguard 0.3.5 (configuration schema 1, report schema 1)

{"configurationSchemaMajor":1,"reportSchemaMajor":1,"version":"0.3.5"}

schema

Prints an embedded JSON schema.

Option	Values	Required
--kind	configuration, report, sarif	yes

codeguard schema --kind configuration > configuration.schema.json
codeguard schema --kind report > report.schema.json
codeguard schema --kind sarif > sarif.schema.json

With the configuration schema, your editor can validate and autocomplete .codeguard.yml. The report schema describes the JSON reports.

config validate

Loads the organization policy and the project configuration, merges them and validates them. Nothing is checked.

codeguard config validate
codeguard --config pfad/zu/codeguard.yml config validate
codeguard --format json config validate

Text output:

configuration valid (schema 1, sha256:8325303d9119ac4ae183fc91b89ae6ebdecd34e52fc14c27d79da8ceeaf72fdb)
policy: /Library/Application Support/CodeGuard/policy.yml (sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80)
metrics: rules.metrics.severity = error (built-in, locked: false)
metrics: rules.metrics.line_length.warning = 120 (project, locked: false)
metrics: rules.metrics.line_length.error = 160 (project, locked: false)

• Line 1: schema version and configuration_hash of the effective configuration.
• policy: source of the organization policy: built-in (no file) or the file path, each with policy_hash.
• metrics: only appears if at least one metric rule has a threshold. Each line shows the value, its source (built-in, organization, project) and whether the value is locked.
• project.platforms = … only appears if project.platforms is set.

JSON output (keys in camelCase, projectSource only with a project configuration):

{"configurationHash":"sha256:d6c09975a10d5760e687a744b97721503cfd86a89d3aadd331b08ccac078f41d","policyHash":"sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80","policySource":{"hash":"sha256:22a9eaedcf877ffbbdcbcaad6d510810c334a29c194ea81404cd2eca324aee80","kind":"file","path":"/Library/Application Support/CodeGuard/policy.yml"},"projectSource":{"mode":"explicit","path":"waiver.yml","sha256":"sha256:60a5b5f47aa112f3521cbdcfb62882a915505396bc8c28052f7ff7bc08edb68d"},"redactionsApplied":true,"schemaVersion":1}

redactionsApplied: true means: redacted fields (e.g. owner/reason of waivers) went into the hash, but not their values.

An invalid configuration ends with exit 2 and names the source, field and reason:

configuration validation failed: project:/checks/tests/required: required checks cannot be disabled by a lower-precedence source

doctor

Read-only diagnosis: which capabilities and tools are available? doctor runs no lint and no build and needs no trust ticket.

codeguard doctor
codeguard --format json doctor

The full sample output and its meaning are described under Getting started. A rendered result ends with exit 0, an invalid configuration with exit 2.

Important capabilities:

Capability	Meaning
swift-format, swiftlint	Tool found and compatible; the version in parentheses, if it can be determined
swiftlint-metrics	Only visible if metric rules are configured
compile, tests	Build tool for the project in the current directory (inactive if there is no package and no Xcode project)
platform-checks	Platform checks active; the API catalog version in parentheses
content-rules	Content rules active; the secret detector catalog in parentheses
unauthorized-network-destination	active only with a non-empty network allowlist
custom-rule:<id>	inactive for custom rules with an unsupported engine
platform.<name>	SDK available locally, the SDK version in parentheses
simctl, simulator.<name>	Simulator tool, runtimes and automatically selected device type
Verwaiste CodeGuard-Geräte	Simulators from aborted runs. doctor only reports them, it never deletes them.

trust status, trust grant, trust revoke

Shows or changes the local project trust. For background, see Trust and security.

codeguard trust status
codeguard trust grant --duration 24h
codeguard trust revoke

Command	Option	Values	Default
trust grant	--duration	positive number plus m or h, at most 24h (e.g. 30m, 8h)	24h

trust grant shows the execution surfaces and asks for confirmation. Only the input yes grants the ticket. It ends with exit 6 if

• --ci is set (project trust cannot be granted in CI),
• stdin is not a terminal (project trust requires an interactive terminal),
• anything other than yes is entered (project trust was not granted).

Output of trust status:

trust: not-trusted
surfaces: manifest:Package.swift

Possible states: trusted, not-trusted, expired, invalid. surfaces lists the files the ticket is bound to, with their kind (manifest, plugin, build-script, xcode-project, scheme).

check-file

Checks one or more files.

codeguard check-file Sources/App/Login.swift Sources/App/Session.swift

• Paths are project-relative and canonical: no absolute path, no .., no ./. Otherwise exit 2 (check-file paths must be canonical and project-relative).
• Without a path: exit 2 (check-file requires at least one project-relative path).
• A path outside paths.include or inside paths.exclude results in exit 6 with path-outside-allowed-scope.
• check-file never runs compile or tests, regardless of the configuration. Only security, platform, format, swiftlint and swiftlint_metrics run. That is why it needs no trust ticket.

check-diff

Checks Git changes.

Option	Meaning
--base <rev>	Compares revision <rev> with the working tree (git diff <rev>). Allowed are a branch, tag, remote branch or commit SHA.
--staged	Checks only the staging area (git diff --cached). Takes precedence over --base.
--include-untracked	Adds untracked files (git ls-files --others --exclude-standard). Default: off.

Without --base and without --staged, CodeGuard compares the working tree with the index (git diff). Changes that are already staged are then left out.

Rules you should know:

• The project root must be the root of the Git repository. If the project lives in a subfolder of the repository, the run aborts (Git repository root differs from requested project root).
• An unknown reference is exit 2, and so is an ambiguous one. A commit SHA whose object is missing locally (e.g. in a shallow clone) is exit 3.
• Renames and copies are detected and checked at the new path. Deleted files, binary files, symlinks and submodules are not checked for content.
• Without changes, the run ends with exit 0 and termination_reason: no_changes.
• compile and tests run (default configuration) and need a trust ticket, or an attestation in CI.

Example of an unknown reference:

check failed before report creation (cause: CodeGuardTooling.GitDiffError: missingBase("doesnotexist"))

check-project

Checks all configured, readable files of the project, then builds and tests it.

codeguard check-project

Like check-diff, check-project needs a trust ticket for compile/tests. For large projects, it is better suited as a nightly run.

Exit codes

The exit code is the same in all formats.

Code	Symbol	Status in report	Meaning
0	CG_OK	passed	Run completed, no blocking findings
1	CG_VALIDATION_FAILED	failed	Blocking finding (rule, format, lint, compile error, test failure)
2	CG_USAGE_CONFIG	error	Invalid input, reference, path or configuration
3	CG_DEPENDENCY_UNAVAILABLE	error	Tool, SDK, runtime or dependency missing, or a required check stayed incomplete
4	CG_TOOL_FAILURE	error	Tool crash, unexpected exit, unknown or truncated output
5	CG_TIMEOUT	error	Time limit exceeded
6	CG_POLICY_BLOCKED	blocked	Path, protection, trust or tool policy blocked the run
7	CG_ITERATION_LIMIT	failed	Reserved for the inactive fix workflows
8	CG_CANCELLED	cancelled	Run cancelled
9	CG_INTERNAL_ERROR	error	Invariant, cleanup or atomic write failed, incomplete installation

If several failures occur, the first one detected wins. Internal errors (exit 9) always take precedence. The others are listed in the JSON report under secondary_failures. Example from a real run: a diff with content findings in a project without a trust ticket ends with exit 1, primary_failure: validation_failed and secondary_failures: ["policy_blocked"]. Without the content findings, the same run ends with exit 6.

How to react in a script:

codeguard --format json --output codeguard.json check-diff --base main
rc=$?
case $rc in
  0) echo "sauber" ;;
  1) echo "blockierende Funde, Bericht ansehen" ;;
  2) echo "Aufruf oder Konfiguration falsch" ;;
  3) echo "Werkzeug, SDK oder Abhängigkeit fehlt" ;;
  6) echo "Policy hat blockiert (Trust, Pfad, geschützte Datei)" ;;
  *) echo "Lauf unvollständig oder Bedienfehler (Code $rc)" ;;
esac
exit $rc

Output and streams

• A fully generated report goes to stdout or exactly into the --output file, even if the exit code is not 0.
• Machine output (JSON, SARIF) is exactly one document, with no log lines before or after it.
• Messages about usage, configuration and rendering errors go to stderr. In these cases there is no report.
• --output writes via a temporary file in the target directory and renames it atomically. If that fails, the exit code is 9.
• The text output shows at most 20 findings. Any further ones appear as N additional diagnostics omitted. at the end. JSON and SARIF contain all of them.

See also

• Reading reports
• Project configuration
• Frequently asked questions