CLI Reference

terraform show -json PLANFILE | tf-snag [flags]
tf-snag -plan plan.json [flags]

Input and checks

Flag	Default
-plan	stdin	terraform show -json output
-plan-log		terraform plan -json NDJSON log. Required by -check deprecations
-plan-log-dir		directory terraform plan ran in, relative to the repo root. Prepended to deprecation file locations so their links resolve, e.g. terraform for -chdir=terraform
-check	drift	drift, deprecations, retirements, a comma list, or all. all is drift + deprecations; retirements are opt-in by name
-source		Terraform source directory. Findings carry the .tf file and line declaring each resource, and inline ignore comments are read
-ignore	.tf-snag-ignore.yml in the working directory or -source	ignore rules file. See Ignoring Findings
-retirements	built-in catalogue	retirement catalogue YAML to use instead of the one in the binary. See Retirements
-retirements-fail-within		only let retirements within this many days trip -exit-code, e.g. 90d. Everything is still reported

With -check all, drift reads -plan and deprecations read -plan-log. Only one of them can come from stdin. -check retirements reads -plan as well, and needs no other input: the catalogue ships inside the binary.

Output

Flag	Default
-format	text	text, json, markdown, junit, sarif or teams. See Output Formats
-color	auto	colour text output: auto, always or never. auto colours when stdout is a terminal and NO_COLOR is unset
-baseline		the previous run's tf-snag.sarif. See Baselines and Provenance
-run-url		this CI run's URL. Recorded against findings first seen in this run, and used for the Teams card's View run button
-exit-code	true	exit 2 when an un-suppressed drift, deprecation or retirement is found
-version		print the version and exit

Microsoft Teams

Flag	Default
-teams-webhook	$TF_SNAG_TEAMS_WEBHOOK	Power Automate Workflows URL to post the card to. A secret
-teams-notify	findings	findings, new or always
-teams-context		a line under the card headline, e.g. pipeline, branch and run number

See Microsoft Teams.

Azure DevOps

Flag	Default
-ado-url		project URL, https://dev.azure.com/org/project
-ado-token	$TF_SNAG_ADO_TOKEN	a PAT or System.AccessToken. A secret
-ado-work-items	true	raise work items when -ado-url is set. Turn off to use -ado-url only for -wiki-page
-ado-type	Task	work item type, e.g. Task, Bug or Issue
-ado-area	project root	area path for new work items
-ado-raise	new	new (absent from -baseline) or findings (anything un-suppressed)
-ado-close	false	close work items whose finding has gone
-ado-closed-state	the type's completed state	state to close into
-ado-dry-run	false	report what would be raised or closed, change nothing
-wiki-page		wiki path to publish the exceptions register to, e.g. /tf-snag/Exceptions. Needs -ado-url
-wiki	<project>.wiki	the wiki's repository, by name or id
-wiki-dry-run	false	print the page and report what would be written, change nothing

See Work Items and Exceptions Register. Work item and wiki output goes to stderr, so it never mixes into a report on stdout.

Exit codes

Code	Meaning
0	no un-suppressed findings
2	an un-suppressed drift or deprecation was found, or an error occurred

Pass -exit-code=false when a step only writes a report and should never fail on findings.

Environment variables

Variable	Used for
TF_SNAG_TEAMS_WEBHOOK	-teams-webhook when the flag is not set
TF_SNAG_ADO_TOKEN	-ado-token when the flag is not set
NO_COLOR	disables -color=auto

Prefer the variables to the flags for secrets: a command line ends up in process listings and CI logs.

Version

tf-snag -version prints one line on stdout, e.g. tf-snag 1.2.0 (a1b2c3d4e5f6) linux/amd64 go1.27.1. Releases stamp the tag as the version. -version and -help also draw the tf-snag wordmark, on stderr so stdout stays parseable.