Phylax CLI

1. Install

   npm

   npm install -g @phyi/cli

   phylax --version

2. Authenticate

   Verification needs a token on a paid plan. The token is written to ~/.config/phylax/config.json with owner-only permissions, and PHYLAX_API_TOKEN overrides it, which is what CI should use.

   phylax auth login
   phylax whoami

3. Common commands

   Command	Description	Example
   verify	Verify an artifact and inspect the result.	phylax verify pkg:npm/express@4.18.2
   attestations	List attestations for an artifact.	phylax attestations pkg:npm/express@4.18.2
   search	Search the registry for artifacts.	phylax search express
   policy evaluate	Evaluate an artifact against a policy.	phylax policy evaluate prod-policy pkg:npm/express@4.18.2
   repo	Verify every dependency the lockfiles in a directory install.	phylax repo .

4. Quick example

   Verify an npm package and read a human-readable summary.

   phylax verify pkg:npm/express@4.18.2

   verdict:

   allow

   risk score:

   low

   provenance:

   verified

   attestations:

   3 available

5. JSON output

   Use --json for machine-readable output. Every command supports it, and the shape is stable across releases.

   phylax verify pkg:npm/express@4.18.2 --json

   {
     "ok": true,
     "verdict": "allow",
     "artifact": "pkg:npm/express@4.18.2",
     "riskScore": "low",
     "provenance": "verified",
     "attestations": { "count": 3, "available": true }
   }

   Pipe it into anything that reads JSON:

   phylax verify pkg:npm/express@4.18.2 --json | jq -r '.verdict'

Exit codes

The CLI is designed to gate a build, so the exit code carries the verdict. Nothing else needs to parse the output to make a pass/fail decision.

Code	Meaning
0	ALLOW. Nothing found that warrants blocking.
1	BLOCK. A policy or a finding failed the artifact.
2	WARN, when run with --strict. Otherwise WARN exits 0.
3	The artifact could not be resolved, or no attestation exists.

WARN is non-blocking on purpose

New findings land against dependencies you did not change, so a pipeline that fails on every warning fails on quiet days and gets switched off. Start with the default and add --strict once your baseline is clean.

Artifact references

Every command that takes an artifact accepts a package URL, bare or fully qualified:

phylax verify npm/express@4.18.2
phylax verify pkg:npm/express@4.18.2
phylax verify pkg:pypi/requests@2.32.3

Global flags

Flag	Effect
--json	Machine-readable output.
--strict	Treat WARN as a failure.
--fail-on <verdict>	Set the verdict that fails the command.
--offline	Use cached data and local attestations only.
--debug	Verbose diagnostics, including the requests made.

Related guides

Wire this into a pipeline with CI/CD Pipelines, or call the same checks over HTTP with the REST API.