The CLI

The CLI gathers the news; it does no project analysis. The skill runs it for you, but it works on its own too. The help below is printed by the CLI itself when this page is built.

`stackalarm news`

stackalarm news --help

Gather security announcements, releases, advisories and CERT alerts.

With --tag, only the sources of those technologies are read, plus the general
sources (CERTs, CVE databases, exploit feeds, security press) whose entries
mention one of the tags or --keyword values. The CVE databases (NVD, EUVD) are
searched for each tag and keyword, and only when there is one: without a key,
the NVD allows one request every 6 seconds (set NVD_API_KEY to go faster).
Run "stackalarm sources" to see the available tags.

For a scheduled watch, --profile reads the tags, keywords and packages from a
file the agent wrote, --state shows only the items no earlier run reported, and
--fail-on exits with code 2 when a new item has one of the given stages.

Usage:
  stackalarm news [flags]

Examples:
  stackalarm news --tag php --tag symfony --since 7d
  stackalarm news --tag node --tag npm --package express,dompurify --format json
  stackalarm news --profile .stackalarm.yaml --state .stackalarm-state --fail-on heads-up,alert,release --since 48h --format markdown

Flags:
      --fail-on strings   exit with code 2 when a new item has one of these stages (heads-up, alert, release…)
      --format string     output format: text, summary (one line per item, for agents), json or markdown (an issue body) (default "text")
  -h, --help              help for news
  -k, --keyword strings   extra word to look for in general sources, repeatable (frankenphp, express…)
      --no-cache          always fetch the sources (responses are otherwise reused for an hour)
  -p, --package strings   package names from the lockfile, repeatable: GitHub Advisory Database sources then return only their advisories
      --profile string    project profile written by the agent (.stackalarm.yaml): tags, keywords and packages to watch
      --since string      how far back to look: 24h, 7d, 2w… (default "7d")
      --state string      file remembering the items already reported: only new ones are shown
  -t, --tag strings       technology to watch, repeatable (php, node, gitlab…)

Tags and keywords

A tag selects the sources of a technology (php, gitlab…) and the general sources (CERTs, CVE databases, exploit feeds, press) whose entries mention it. A keyword only searches the general sources: use it for what has no tag (frankenphp). An unknown tag is searched as a keyword, with a warning that lists the known tags. Each tag and keyword costs one search per CVE database.

Stages

Stage	Meaning
heads-up	A security release is announced ahead. When the same feed announces the release itself, the item becomes a release.
release	The fix is out.
advisory	The details of a vulnerability: affected and fixed versions, score, conditions.
alert	A CERT alert, a public exploit, or exploitation in the wild.
news	Security press and research: context, never enough on its own to call a project affected.

Output formats

Format	For
`text`	Reading in a terminal. The default.
`summary`	Agents: one line per item (date, stage, source, score, title, link, other databases listing the same CVE), then the failed and truncated sources.
`json`	Scripts: the items with their summaries, plus `failures`, `truncated` and `warnings`.
`markdown`	An issue body, used by the scheduled watch.

Limits, failures and cache

Each source shows at most 30 entries. For the CVE databases, the most severe come first, so the cap drops the minor ones. The output lists the sources that had more.
A source that cannot be read is always listed: a silent watch tool is worse than a noisy one.
Responses are reused for an hour, from stackalarm in your user cache folder. --no-cache fetches everything again.
Without NVD_API_KEY, the NVD allows one request every 6 seconds; with it, about one every 0.7 seconds.

Exit codes

Code	Meaning
`0`	Done, and nothing matched `--fail-on`.
`1`	An error: a bad option, an unreadable profile or state file.
`2`	New items with one of the `--fail-on` stages were found.

For a scheduled watch

--profile reads the tags, keywords and packages from .stackalarm.yaml. --state keeps a file of the items already reported, so only new ones are shown; items are forgotten after 90 days, and the file is replaced atomically, so an interrupted run keeps the previous state. --fail-on turns new items into exit code 2. See Scheduled watch.

stackalarm news --profile .stackalarm.yaml --state .stackalarm-state --fail-on heads-up,alert,release --since 48h --format markdown

`stackalarm sources`

stackalarm sources --help

List the watched sources and their tags

Usage:
  stackalarm sources [flags]

Flags:
      --format string   output format: text or json (default "text")
  -h, --help            help for sources

Lists every source with its id, stage and tags. The same list is on the Sources page.

Next: Scheduled watch