The CLI
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
| Flag | Default | What it does |
|---|---|---|
| --json | false | write 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.
| Flag | Default | What it does |
|---|---|---|
| --assist | false | have a model draft each verdict from the evidence, with your own key |
| --dry-run | false | print the verdicts without sending them |
| --model string | the model --assist uses (default claude-opus-5-5 or gemini-4-carbon; OpenAI needs one) | |
| --provider string | the provider --assist uses: anthropic, google or openai (default: the first key set) | |
| --server string | the watchdep server's address (default: WATCHDEP_SERVER, else the last login) | |
| --token string | the 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.
| Flag | Default | What it does |
|---|---|---|
| --environment string | production | the environment deployed to |
| --server string | the watchdep server's address | |
| --sha string | the deployed commit (default: GITHUB_SHA) | |
| --token string | the 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.
| Flag | Default | What it does |
|---|---|---|
| --base string | the branch pull requests target (default: the part's production branch) | |
| --dry-run | false | make the changes, print them and put the files back; no git, no pull request |
| --server string | the watchdep server's address (default: WATCHDEP_SERVER, else the last login) | |
| --token string | the 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
| Flag | Default | What it does |
|---|---|---|
| --allow-incomplete | false | exit 0 instead of 2 when the check is incomplete and nothing meets the threshold |
| --epss-threshold float64 | 0.1 | EPSS 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 stringArray | read a container image: a local tarball (docker save, OCI archive) or a registry reference; repeatable | |
| --mirror string | match 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 stringArray | read 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.
| Flag | Default | What it does |
|---|---|---|
| --image stringArray | read a container image: a local tarball (docker save, OCI archive) or a registry reference; repeatable | |
| --pull-images | false | pull the base images named in Dockerfiles and watchdep.yml (makes network calls) |
| --rootfs stringArray | read 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.
| Flag | Default | What it does |
|---|---|---|
| --server string | the watchdep server's address | |
| --token string | the 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.
| Flag | Default | What it does |
|---|---|---|
| --inventory string | an inventory file | |
| --mirror string | the mirror folder |
watchdep mirror
Keep a local copy of OSV for matching with no network.
watchdep mirrorwatchdep 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.
| Flag | Default | What it does |
|---|---|---|
| --dir string | the mirror folder |
watchdep mirror status
Show what the mirror holds and when each ecosystem last synced.
watchdep mirror status --dir <dir> [flags]| Flag | Default | What it does |
|---|---|---|
| --dir string | the 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.
| Flag | Default | What it does |
|---|---|---|
| --archive string | install this downloaded export (all.zip) instead of downloading | |
| --dir string | the mirror folder | |
| --ecosystem stringArray | an 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.
| Flag | Default | What it does |
|---|---|---|
| --provider string | anthropic, 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.
| Flag | Default | What it does |
|---|---|---|
| --image stringArray | read a container image: a local tarball (docker save, OCI archive) or a registry reference; repeatable | |
| --rootfs stringArray | read the package databases in a folder laid out like a root filesystem; repeatable | |
| --server string | the watchdep server's address (default: WATCHDEP_SERVER, else the last login) | |
| --token string | the part's token (default: WATCHDEP_TOKEN, else the last login) |
watchdep version
Print the version, commit and build date.
watchdep versionwatchdep 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.
| Flag | Default | What it does |
|---|---|---|
| --config string | a watchdep.yml whose ignore list applies |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Nothing meets the threshold, and everything was looked at. |
| 1 | A finding meets the threshold (gate), or the server answered with findings that fail. |
| 2 | Incomplete: 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). |
| 3 | The 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
| Variable | Read by | What it does |
|---|---|---|
| WATCHDEP_SERVER | scan, check, fix, deployed | The watchdep server's address, instead of --server or a login. |
| WATCHDEP_TOKEN | scan, check, fix, deployed | The part's project token, instead of --token or a login. |
| WATCHDEP_CREDENTIALS | login and every command that talks to a server | Where login stores tokens; by default the user's config folder. |
| GITHUB_TOKEN | fix | The repository's token, to open and update pull requests. |
| GITHUB_REPOSITORY | fix | The repository as owner/name (set by GitHub Actions). |
| GITHUB_API_URL | fix | GitHub's API address; https://api.github.com by default (set by GitHub Actions). |
| GITHUB_SHA | deployed | The commit, when --sha is not given (set by GitHub Actions). |
| ANTHROPIC_API_KEY | check --assist | Your own Anthropic key for the assisted code check, used from this machine only. |
| NO_COLOR | every command | Any value turns colour off. |
| TERM | every command | dumb turns colour off. |