One tool, two ecosystems.

Quick start (npm)

In a project with a package.json:

phi install

phi resolves the full transitive tree and scans every package before extraction. SAFE packages install first. REVIEW packages install after approval (or automatically with --yes), and accepted REVIEW packages recorded in phi.lock are not re-prompted on later installs. BLOCKED packages are skipped by default and only materialized with --force. Unresolvable packages are listed under skipped in phi-report.json while the rest of the install continues.

To add a new dep:

phi install chalk@^5.0.0

Updates the dependencies field, scans, installs.

To audit without installing:

phi audit

Commands

Auto-fixing with phi audit fix

New in v0.2.3. Propose actionable fixes for direct dependencies. Three sources, in order of confidence:

1. Typosquats → swap to the popular package name (loadsh → lodash). Always safe — different package, same intent.
2. Advisory bumps → upgrade to the OSV-documented fixed in version. Same-major bumps are safe; cross-major bumps are flagged as breaking.
3. Deprecated packages → swap to the curated successor (vm2 → isolated-vm, request → undici, node-uuid → uuid, …). Always breaking — public API differs.

Three modes:

phi audit fix              # preview only — no filesystem changes
phi audit fix --apply      # write SAFE fixes to package.json
phi audit fix --force      # write EVERY fix, including breaking changes

After applying, run phi install to materialize the new versions.

One-shot binaries with phi x (npx-equivalent)

New in v0.3.0. phi x (the alias for phi exec) is now a drop-in replacement for npx: if the bin isn't already in node_modules/.bin, phi resolves the providing package, runs every detector + the OSV layer over the transitive tree, then runs the bin from a per-version cache. Repeat invocations of the same resolved version skip the scan and run instantly. The user's node_modules is never touched.

phi x cowsay "hello phi"           # fetch + scan + run, like npx
phi x prettier --write src/        # args after the pkg go to the bin verbatim
phi x cowsay@1.5.0                 # pin a version (always fetches)
phi x -p typescript tsc --version  # bin name (tsc) ≠ package name (typescript)
phi x -y create-react-app my-app   # auto-approve review verdicts (CI / scaffold)
phi x --no-install eslint .        # strict-local: fail if not already installed
phi x --rescan cowsay              # invalidate the cached scan, redo it

Cache layout:

$UserCacheDir/phi/run/<name>@<version>/
  node_modules/<name>/…           # extracted package + transitive deps
  node_modules/.bin/<bin-name>     # shim, on PATH for the bin's lifetime
  .phi-scan-passed                 # marker; presence means "trusted, run"

Production installs with phi ci

New in v0.4.1. Non-interactive environments (Docker builds, GitHub Actions) have no stdin for phi's REVIEW prompt — without help, an install hangs forever. phi ci solves this without losing the audit:

phi ci                          # production: --frozen-lockfile + --yes preset
phi ci --omit=dev               # also skip devDependencies (npm parity)
phi ci --force                  # explicit override for blocked verdicts
phi ci --no-advisories          # offline / air-gapped builds

phi ci is sugar for phi install --frozen-lockfile --yes. The frozen lockfile is the audit record — any package in phi.lock was already reviewed and approved by a human during their local phi install. Prod can therefore auto-approve REVIEW verdicts without a prompt. BLOCKED verdicts still abort unless --force is explicit. A missing or drifted lockfile errors clearly (phi.lock not found / phi.lock is out of sync with package.json) — there's no silent fallback to a fresh resolve.

Composable primitives

phi ci is built on two new flags that work standalone too:

Docker / GitHub Actions build commands

# Dockerfile
COPY package.json phi.lock ./
RUN phi ci --omit=dev

# GitHub Actions
- run: phi ci --omit=dev

Security inspection with phi view

New in v0.5.0; scan-by-default in v0.5.1. Pointed at any public package, phi view fetches the packument and the tarball, runs phi's detector pipeline, queries OSV for known advisories, and prints the human metadata block alongside a security: section showing score / verdict / detections / advisories. Same engine phi install and phi audit use — so you get the same verdict you'd get if you installed the package, before you add it to package.json.

phi view react                       # latest version, full security scan
phi view react@18.2.0                # version-pinned scan
phi view lodash@4.17.10              # known-vuln older version → BLOCKED + 9 GHSA hits
phi view react --json                # JSON output, including the "scan" object
phi view react --no-scan             # fast metadata-only path (no tarball fetch)
phi view react license               # one field via gjson dotpath (auto-skips scan)
phi view react 'versions[0]'         # array index queries

Sample output (truncated) — a vulnerable older lodash:

lodash@4.17.10
A modern JavaScript utility library delivering modularity, performance, & extras.

  license:      MIT
  homepage:     https://lodash.com/
  published:    2018-04-24 (8 years ago)
  versions:     117 total · latest 4.18.1
  tarball:      https://registry.npmjs.org/lodash/-/lodash-4.17.10.tgz

security:
  score:        100/100
  verdict:      BLOCKED
  files scanned: 1047
  advisories (9):
    - [CRITICAL] GHSA-jf85-cpcp-j695 — Prototype Pollution in lodash (fix: 4.17.12)
    - [HIGH] GHSA-35jh-r3h4-6jhm — Command Injection in lodash (fix: 4.17.21)
    - [HIGH] GHSA-4xc9-xhrj-v574 — Prototype Pollution in lodash (fix: 4.17.11)
    - [HIGH] GHSA-p6mc-m468-83gw — Prototype Pollution in lodash (fix: 4.17.19)
    - [HIGH] GHSA-r5fr-rjxr-66jc — Code Injection via _.template (fix: 4.18.0)
    - [MODERATE] GHSA-29mw-wpgm-hmr9 — ReDoS (fix: 4.17.21)
    - [MODERATE] GHSA-f23m-r3pf-42rh — Prototype Pollution via array path (fix: 4.18.0)
    - [MODERATE] GHSA-x5rq-j2xg-h7qm — ReDoS (fix: 4.17.11)
    - [MODERATE] GHSA-xxjr-mmjv-4gpg — Prototype Pollution in _.unset/_.omit (fix: 4.17.23)

Inspecting trees with phi ls

New in v0.5.0. npm-style ASCII dependency tree, sourced from phi.lock (falls back to a fresh resolve when no lockfile exists).

phi ls                    # full tree, all direct deps
phi ls --depth 0          # direct only (no transitives)
phi ls --depth 1          # direct + one level
phi ls --prod             # drop devDependencies
phi ls lodash             # prune to branches that reach lodash
phi ls --json             # stable JSON shape for scripts

Honors NO_COLOR for plain ASCII output (no bold escapes) — useful when piping to less or capturing to a file.

Global linking with phi link

New in v0.5.0. Two-step npm link-style flow, but cross-platform without admin: macOS / Linux get real symbolic links; Windows gets directory junctions (mklink /J) so no developer mode or elevation is required.

# 1. In the package being developed
cd ~/work/my-lib
phi link                  # registers ~/.config/phi/links/my-lib → cwd

# 2. In the consumer
cd ~/work/some-app
phi link my-lib           # creates node_modules/my-lib → ~/work/my-lib

phi link --list           # show registered links and their targets
phi unlink my-lib         # consumer side: drop node_modules/my-lib
cd ~/work/my-lib && phi unlink   # package side: drop the global entry

Storage: ~/.config/phi/links/<name> on Linux/macOS, %APPDATA%\phi\links\<name> on Windows. Scoped names round-trip through one extra directory level (links/@org/utils).

Outdated reports & interactive upgrades

New in v0.5.0; live spinner in v0.5.1. phi outdated queries every direct dep against the registry's latest dist-tag and prints a color-coded table — yellow for minor / patch bumps, red for major. Workspace siblings declared with workspace: are stripped from the table (they don't have a registry version to be "behind").

phi outdated                          # table for root direct deps
phi outdated --filter '@org/*'        # per-workspace tables, filtered
phi outdated --filter './apps/**'     # filter by workspace path

phi upgrade-interactive (alias phi ui) walks each outdated package and asks [y]es / [n]o / [a]ll / [q]uit. The existing range prefix is preserved when rewriting package.json — "^1.2.0" + new latest 1.3.0 becomes "^1.3.0", not a bare exact pin.

phi upgrade-interactive               # walk minor/patch bumps with prompts
phi ui --allow-major                  # also propose major-version bumps
phi ui --yes                          # accept every proposal (CI-safe)
phi ui --allow-major --yes            # upgrade everything to latest

Editing package.json and config

New in v0.5.0. Two scriptable round-trippers replace shell sed/awk:

phi pkg — edit package.json

phi pkg get name                       # → "monorepo"
phi pkg get dependencies.lodash        # → "^4.17.20"
phi pkg set scripts.lint "eslint ."    # add or replace a script
phi pkg set engines.node "20"          # stays the STRING "20", not coerced
phi pkg set private true               # JSON true (boolean)
phi pkg delete scripts.lint
phi pkg fix                            # sort deps, dedupe dev→prod

Preserves indent style, leading BOM, trailing newline, and key order on round-trip. Conservative coercion: only true / false / null and literal {} / [] parse as JSON. npm pkg parity for the common flows.

phi config — edit ~/.config/phi/config

phi config set registry "https://registry.npmjs.org/"
phi config set //npm.pkg.github.com/:_authToken "ghp_..."
phi config get registry
phi config list                        # comments preserved; secrets redacted on tty
phi config delete //npm.pkg.github.com/:_authToken

Secret-shaped keys (containing token, password, secret, _authtoken) are auto-redacted in phi config list when stdout is a terminal; piping to another command gets raw values for scripting. Comments and blank lines survive round-trips so hand-edited files stay readable.

Workspace selectors with --filter

New in v0.5.0. pnpm-style filter syntax for running a script in a subset of a monorepo. Accepted by phi do and phi outdated.

phi do build --filter '@org/*'                       # build every @org/* workspace
phi do build --filter '@org/*' --filter '!@org/web'  # everything except @org/web
phi do test --filter './apps/**'                     # only workspaces under apps/

# Each match runs in its own dir with a header:
# === @org/api (1/3) ===
# === @org/billing (2/3) ===
# === @org/queue (3/3) ===

Missing scripts in a filter run are skipped silently (npm parity) — so phi do test --filter '@org/*' works even when only a subset of workspaces have a test script.

Scaffolding with phi create

Bootstrap a new project end-to-end. The scaffolder package itself is fetched and audited through phi's safe pipeline (lifecycle scripts off) before its binary runs in your current directory. The temp install is wiped after one use.

List available frameworks at any time:

phi create

Pass-through flags after -- go straight to the scaffolder. User flags override phi's defaults on flag-name collisions:

phi create react my-app
phi create express my-server
phi create next my-site -- --typescript --app --no-tailwind
phi create nest my-api -- --package-manager npm

Why --skip-install by default for next and nest? Both scaffolders auto-run npm install after writing files, which would bypass phi's safe pipeline for the project's actual dependencies. Phi disables it so the user runs phi install in the new directory instead, getting all transitive deps scanned.

Flags

Environment variables

CI and Dockerfile users often can't thread flags through every call site, so the most useful flags also resolve from environment variables. Flag values still win if both are set.

Lockfile & cache

phi.lock is generated on every install. Format mirrors npm's package-lock.json shape with extra score and verdict fields per entry. When present and it covers package.json, phi reuses it without re-resolving.

Workspaces

If your root package.json declares a workspaces field, phi aggregates dependencies from every workspace package, installs the union into the root node_modules/, and links each workspace into node_modules/<workspace-name> as a junction (Windows) or symlink (Unix).

{
  "workspaces": ["packages/*"]
}

Both array form and {packages: [...]} object form are supported. Sibling references ("@org/utils": "*" from inside @org/app) bypass the registry — they resolve through the link.

The workspace: protocol (v0.5.0)

For unambiguous sibling references that won't accidentally fall through to the registry, phi supports the same workspace: protocol pnpm and yarn-berry use:

A missing sibling for any workspace: spec is an explicit warning — phi does not fall through to npm and fetch a package with a colliding name from the public registry, which would otherwise be a stealth supply-chain risk in a monorepo.

Filtering and scripting

phi do --filter and phi outdated --filter let you scope a command to a subset of workspaces. See § 02.15 for the full selector syntax. phi link works inside or outside a monorepo and is unrelated to workspace: resolution — use it when the package being linked lives outside the repo.

Private registries (.npmrc)

phi reads .npmrc from $HOME and the project root (project wins on conflict). Supported settings:

• registry=https://... — default registry override
• @scope:registry=https://... — scoped registry routing
• //host/path/:_authToken=... — bearer token, sent as Authorization: Bearer <token> to matching URLs
• ${ENV_VAR} substitution — keep secrets out of committed files

//npm.pkg.github.com/:_authToken=${GITHUB_PAT}
@my-org:registry=https://npm.pkg.github.com/

CI integration

# GitHub Actions
- run: phi install --frozen-lockfile
- run: phi audit --json > phi-report.json
- run: jq '.summary.blocked == 0 and .summary.review == 0' phi-report.json

--frozen-lockfile requires phi.lock to exactly cover package.json; non-zero exit on drift. --json emits the full scan report to stdout and exits non-zero on any blocked or review-flagged package.