watchdep
Sign inSource
Docs / Reference / 02

The CLI

Section
Reference
Page
02 of 16
Source
Generated
Read next
watchdep.yml
Generated from the CLI's own definitions (watchdep reference), the same ones --help prints.

One static binary, watchdep. Every command writes words for people by default and JSON with --json. Install it as the install page says.

watchdep takes the inventory of a project (every package at every depth, runtimes, and the operating system packages of its images) and checks it for known vulnerabilities and compromised releases.

Nothing reads as clean when watchdep did not look: a file it could not read, an ecosystem it does not support, an image it could not pull or a source that did not answer is shown, and makes the run incomplete.

Global flags

FlagDefaultWhat it does
--jsonfalsewrite all output as JSON

watchdep check

Check whether the code uses each open finding's package, and send the verdicts.

watchdep check [path] [flags]

Fetch the part's open findings from the watchdep server, search this folder's code for imports and calls of each affected package (and of the affected functions where the advisory names them), and send back a draft verdict for each: used, not used, or unclear, with a reason and evidence as file paths and line numbers. A verdict is a draft: it never closes a finding; a person decides.

Code leaves the machine only as short snippets around the evidence, and only when the workspace's owner allowed snippets. With --assist, an assistant drafts the verdict from the evidence and the lines around it, called from this machine with your own key; the watchdep server never sees the key. Choose the provider with --provider anthropic|google|openai (else the first key set of ANTHROPIC_API_KEY, GEMINI_API_KEY and OPENAI_API_KEY; with none, Anthropic, which can use your Anthropic login) and the model with --model (defaults claude-opus-5-5 and gemini-4-carbon; OpenAI needs one named, and watchdep models --provider <p> lists them). The assistant may sharpen a verdict but never turns a found use into "not used", and a refusal or an error keeps the search's verdict and says why.

Exit codes: 0 sent; 2 the server did not answer; 3 no token, a refused token, or a rejected result.

FlagDefaultWhat it does
--assistfalsehave a model draft each verdict from the evidence, with your own key
--dry-runfalseprint the verdicts without sending them
--model stringthe model --assist uses (default claude-opus-5-5 or gemini-4-carbon; OpenAI needs one)
--provider stringthe provider --assist uses: anthropic, google or openai (default: the first key set)
--server stringthe watchdep server's address (default: WATCHDEP_SERVER, else the last login)
--token stringthe part's token (default: WATCHDEP_TOKEN, else the last login)

watchdep deployed

Report that a commit was deployed, so production is what was deployed.

watchdep deployed --sha <commit> [flags]

Run in the deploy step after a deployment succeeds. With deployment reports, production is the last deployed commit: a fix merged but not deployed is "fix merged, not yet in production" until then. Run watchdep scan in the same step so the deployed commit has an inventory.

FlagDefaultWhat it does
--environment stringproductionthe environment deployed to
--server stringthe watchdep server's address
--sha stringthe deployed commit (default: GITHUB_SHA)
--token stringthe part's token

watchdep fix

Open a pull request per finding that the workspace wants fixed by pull request.

watchdep fix [path] [flags]

Run in the project's own CI (watchdep-action does this). Fetches from the watchdep server the part's findings whose fix setting is "open a pull request"; for each, makes a branch, upgrades the package with the project's own package manager (an override for a package that comes in through another one), takes the inventory again to check the fix version is reached, commits, pushes, and opens a pull request with the repository's own token, or updates the one already open. Each run also reports the state of the pull requests it opened before. watchdep never merges: a person approves and merges.

Needs GITHUB_TOKEN (contents and pull requests write) and GITHUB_REPOSITORY; GITHUB_API_URL for GitHub Enterprise. --dry-run makes the changes, prints them and puts the files back, with no git and no pull request.

Exit codes: 0 done; 2 the server did not answer, or a fix failed; 3 no token or a refused one.

FlagDefaultWhat it does
--base stringthe branch pull requests target (default: the part's production branch)
--dry-runfalsemake the changes, print them and put the files back; no git, no pull request
--server stringthe watchdep server's address (default: WATCHDEP_SERVER, else the last login)
--token stringthe part's token (default: WATCHDEP_TOKEN, else the last login)

watchdep gate

Check the project against OSV, CISA KEV and EPSS, and fail the build on a finding.

watchdep gate [path] [flags]

Take the inventory, check it against OSV, CISA KEV and EPSS with no watchdep server, rank every finding, and exit non-zero when one meets the threshold, so a CI build can stop on it.

--fail-on takes any of: malicious a malicious release, in any scope (its install scripts already ran) kev listed in CISA KEV (exploited now), in production scope severe at level severe, provisional included high at level high or severe

Exit codes: 0 nothing meets the threshold and the check is complete 1 a finding meets the threshold (wins over incomplete) 2 the check is incomplete: something could not be read or checked, or a source did not answer (0 instead with --allow-incomplete, when nothing meets the threshold) 3 a usage or watchdep.yml error

FlagDefaultWhat it does
--allow-incompletefalseexit 0 instead of 2 when the check is incomplete and nothing meets the threshold
--epss-threshold float640.1EPSS probability at or above which a critical finding is severe
--fail-on stringSlice[malicious,kev]fail on findings that are any of: malicious, kev, severe, high
--image stringArrayread a container image: a local tarball (docker save, OCI archive) or a registry reference; repeatable
--mirror stringmatch against a local OSV mirror (watchdep mirror sync) instead of the OSV API; a mirror whose last sync failed or is over 24 hours old makes the check incomplete
--rootfs stringArrayread the package databases in a folder laid out like a root filesystem; repeatable

watchdep inventory

List everything the project contains, and everything that could not be read.

watchdep inventory [path] [flags]

List every package at every depth with its dependency paths and scope, the runtimes, the operating system packages of any image or root filesystem given, and every file that could not be read, every unsupported ecosystem and every manifest with no lockfile.

Makes no network call (unless --pull-images). Base images named in watchdep.yml or a Dockerfile are listed as not read; watchdep gate pulls them, or pass --image.

Exit codes: 0 complete, 2 incomplete (something could not be read), 3 usage or watchdep.yml error.

FlagDefaultWhat it does
--image stringArrayread a container image: a local tarball (docker save, OCI archive) or a registry reference; repeatable
--pull-imagesfalsepull the base images named in Dockerfiles and watchdep.yml (makes network calls)
--rootfs stringArrayread the package databases in a folder laid out like a root filesystem; repeatable

watchdep login

Store a part's token for a watchdep server.

watchdep login --server <url> --token <token> [flags]

Store the token a watchdep server created for one part, so watchdep scan can send that part's inventory. The token is kept in the user's config folder, readable only by the user. In CI, set WATCHDEP_SERVER and WATCHDEP_TOKEN instead.

FlagDefaultWhat it does
--server stringthe watchdep server's address
--token stringthe part's token, as the server showed it

watchdep match

Answer which advisories affect each package of an inventory, from a local mirror.

watchdep match --mirror <dir> --inventory <file> [flags]

Read an inventory file (as watchdep inventory --json writes it) and answer, from a local OSV mirror and with no network, which advisories affect each package and OS package. The answer holds every advisory's entry and everything that was not checked. It does no ranking. The watchdep server uses this command, so the CLI and the server match versions with the same rules.

Exit codes: 0 complete; 2 incomplete (an ecosystem the mirror does not hold, an unreadable mirror); 3 usage, or an unreadable inventory.

FlagDefaultWhat it does
--inventory stringan inventory file
--mirror stringthe mirror folder

watchdep mirror

Keep a local copy of OSV for matching with no network.

watchdep mirror

Commands: package, status, sync.

watchdep mirror package

List every advisory the mirror holds for one package, whatever versions it affects.

watchdep mirror package --dir <dir> <ecosystem> <name> [flags]

List every advisory the mirror holds for one package, whatever versions it affects, withdrawn ones included, in id order. With --json, each advisory's full OSV entry. The watchdep server reads it to give an advisory's related advisories to its AI review.

Exit codes: 0 answered (an unknown package is an empty list); 1 the mirror does not hold the ecosystem.

FlagDefaultWhat it does
--dir stringthe mirror folder

watchdep mirror status

Show what the mirror holds and when each ecosystem last synced.

watchdep mirror status --dir <dir> [flags]
FlagDefaultWhat it does
--dir stringthe mirror folder

watchdep mirror sync

Download OSV's export for each ecosystem when it changed, and index it.

watchdep mirror sync --dir <dir> --ecosystem <name>... [flags]

Download OSV's export for each named ecosystem (npm, PyPI, RubyGems, Debian and so on; the part before any ":"), keep the archive and index it by package. An unchanged export is not downloaded again. A failed download keeps the previous copy and is reported. With --archive, an export already downloaded (for a copy with no route to OSV) is installed instead, for one ecosystem.

Exit codes: 0 every ecosystem synced; 2 at least one did not.

FlagDefaultWhat it does
--archive stringinstall this downloaded export (all.zip) instead of downloading
--dir stringthe mirror folder
--ecosystem stringArrayan OSV ecosystem to sync; repeatable

watchdep models

List a provider's current models that check --assist can use.

watchdep models --provider anthropic|google|openai [flags]

List the provider's current models that can answer in a schema, as check --assist needs, asked of the provider with your key from the environment (ANTHROPIC_API_KEY or your Anthropic login, GEMINI_API_KEY, OPENAI_API_KEY). Anthropic says which models support structured output; Google's and OpenAI's lists do not, so those are their Gemini models that think and their gpt models.

Exit codes: 0 listed; 2 the provider did not answer; 3 no provider named or no key.

FlagDefaultWhat it does
--provider stringanthropic, google or openai

watchdep scan

Send the project's inventory to a watchdep server.

watchdep scan [path] [flags]

Take the inventory (as watchdep gate does, pulling base images) and send it to a watchdep server with the part's token. Only the inventory leaves the machine; the code never does.

The server and token come from --server and --token, else WATCHDEP_SERVER and WATCHDEP_TOKEN, else the last watchdep login.

Exit codes: 0 sent; 2 the server did not answer, or did not look (the plan's scans for today are used), with its reason; 3 no token, a refused token or a rejected inventory.

FlagDefaultWhat it does
--image stringArrayread a container image: a local tarball (docker save, OCI archive) or a registry reference; repeatable
--rootfs stringArrayread the package databases in a folder laid out like a root filesystem; repeatable
--server stringthe watchdep server's address (default: WATCHDEP_SERVER, else the last login)
--token stringthe part's token (default: WATCHDEP_TOKEN, else the last login)

watchdep version

Print the version, commit and build date.

watchdep version

watchdep wanted

Say which files of a repository listing watchdep would read.

watchdep wanted [--config watchdep.yml] < listing [flags]

Read a repository's file listing on standard input, one file per line as "<path> <size>" (size optional), and answer which of those files watchdep inventory would read: dependency files, the manifests beside lockfiles, version files, Dockerfiles, watchdep.yml and the files of unsupported ecosystems. Never a source file.

The watchdep server uses it to fetch exactly the files the CLI reads, so the GitHub route and the CLI route give the same inventory. With --config, folders the given watchdep.yml ignores are left out.

FlagDefaultWhat it does
--config stringa watchdep.yml whose ignore list applies

Exit codes

CodeMeaning
0Nothing meets the threshold, and everything was looked at.
1A finding meets the threshold (gate), or the server answered with findings that fail.
2Incomplete: a file could not be read, an ecosystem is not supported, an image could not be pulled, or a source or the server did not answer or would not look (the plan's scans for today are used).
3The command line or watchdep.yml is wrong.

Incomplete is not clean. Exit code 2 means watchdep could not look at everything. It says what it could not read or check, and never reports that as "no findings".

Environment

VariableRead byWhat it does
WATCHDEP_SERVERscan, check, fix, deployedThe watchdep server's address, instead of --server or a login.
WATCHDEP_TOKENscan, check, fix, deployedThe part's project token, instead of --token or a login.
WATCHDEP_CREDENTIALSlogin and every command that talks to a serverWhere login stores tokens; by default the user's config folder.
GITHUB_TOKENfixThe repository's token, to open and update pull requests.
GITHUB_REPOSITORYfixThe repository as owner/name (set by GitHub Actions).
GITHUB_API_URLfixGitHub's API address; https://api.github.com by default (set by GitHub Actions).
GITHUB_SHAdeployedThe commit, when --sha is not given (set by GitHub Actions).
ANTHROPIC_API_KEYcheck --assistYour own Anthropic key for the assisted code check, used from this machine only.
NO_COLORevery commandAny value turns colour off.
TERMevery commanddumb turns colour off.