Skip to content

CLI

skif [OPTIONS] [PATH]
skif rules [--format human|json]
skif schema
skif init [PATH]
skif config [PATH] [-r] (--show | --explain <KEY> [--package <NAME>]) [--config <FILE> | --no-config] [--format human|json]
skif explain-usage <FILE[#EXPORT]> [PATH]
skif explain-usage --dependency <NAME> [--package <NAME|DIR>] [PATH]
skif migrate [PATH] [--from sherif|syncpack|knip|auto,...] [--profile exact|full] [--merge | --force] [--dry-run]
skif baseline write|prune [PATH] [-r | --file <FILE>] [LINT FLAGS] [--format human|json]
skif baseline check [PATH] (--base <REF> | --base-file <FILE>) [-r | --file <FILE>] [--format human|json]
skif update [PATH] [--check | --interactive] [--target latest|minor|patch] [--dependencies <NAME>...] [--no-install] [--format human|json]
skif list [PATH] [-r] [--show instances,statuses,hints,ignored,all,none] [FILTERS]
skif json [PATH] [-r] [FILTERS]
skif format [PATH] [-r] [--check | --unsafe]
skif mcp
skif lsp

skif [PATH] lints the project containing PATH (default .). Under bazel run, PATH and every other relative path resolve against the directory Bazel was run from (Bazel). The root is resolved in this order:

  1. With -r/--recursive, every root at or below PATH (see below).
  2. Otherwise the nearest ancestor workspace that lists the package at PATH as a member. A package that declares a workspace is its own root.
  3. Otherwise the package itself, linted in single-package mode: no workspace declaration is needed.
  4. When neither PATH nor an ancestor holds a package.json or a workspace declaration, every root below PATH, as with -r.

The root is used for configuration, reported paths, fix writes and the install step. In a multi-root run (-r, or the fallback in step 4) skif lints each workspace and each standalone package below PATH in parallel and merges the results into one report with one exit code, the worst over the roots. Reported paths are relative to the invocation directory, human output is grouped by root, and --format json adds a roots array. node_modules, hidden directories, directories excluded by a .gitignore or .ignore and directories matching [workspace] discover-ignore (by default __fixtures__, fixtures, __mocks__ and __snapshots__) are not searched. A root that cannot be loaded is reported in the errors array of the JSON document and does not stop the others; the exit code is then 2. A search stopped by the depth limit lists the directories it did not enter in the truncated array. root-package-manager-field is not reported for a standalone package below another root. --fix plans, writes and installs per root. A root nested in another root of the run is linted after the roots that enclose it, and the files of it that they import are its entries.

-r is --recursive, not sherif’s --ignore-rule. When the PATH given with -r does not exist and is the name of a sherif or skif rule (skif -r multiple-dependency-versions), skif exits 2 with a usage error that names the --ignore-rule and --rule flags for that rule, using the skif rule id.

Command Does
skif rules List every rule with its category, default level and fixability. --format json prints one JSON document.
skif schema Print the JSON Schema of skif.toml.
skif init [PATH] Write a starter skif.toml into PATH (default .). Refuses to overwrite an existing configuration. When configuration files above PATH already apply, prints a note naming the files the new one inherits from.
skif config [PATH] Show how the configuration of the root at PATH was built (see below).
skif explain-usage <FILE[#EXPORT]> [PATH] Explain why the JavaScript analysis counts a file, or one export of it, as used, or with --dependency a dependency (see below).
skif migrate [PATH] Translate the configuration of sherif, syncpack and knip into a skif.toml (see below).
skif baseline write|prune|check [PATH] Record the current findings as [[ignore]] entries in a baseline file the root’s skif.toml extends, remove the entries that match nothing, or fail when the baseline gained entries (see below).
skif update [PATH] Update dependencies to newer published versions from the npm registry, or with --check only report them (see below). The only command that uses the network.
skif list [PATH] List every dependency the version groups and the catalog govern, by version group, with its specifiers and states (see below).
skif json [PATH] Print every dependency instance the version groups and the catalog govern as one JSON object per line (see below).
skif format [PATH] Format every package.json as [format] describes, or check it with --check (see below).
skif mcp Run a Model Context Protocol server on stdin and stdout, with the tools lint, explain_usage, config and list_rules. See editors and agents.
skif lsp Run a Language Server Protocol server on stdin and stdout that publishes diagnostics when a file is opened, changed (unsaved text included) or saved and offers fixes as code actions. See editors and agents.
Flag Meaning
-r, --recursive Lint every workspace and standalone package at or below PATH in one run, instead of only the project containing PATH.
--format <FORMAT[=FILE]> Output format: human, json, toon, sarif, github, codeclimate, compact, markdown, disclosure or codeowners. FORMAT=FILE writes that rendering to FILE. Repeatable, with at most one format on stdout (see Several reports in one run). Default human, or human plus GitHub annotations when GITHUB_ACTIONS=true.
--output <FILE> Write the rendering to FILE instead of stdout. Requires exactly one --format, without =FILE.
--fix Apply safe fixes, lint again, then run the package manager’s install command.
--fix-unsafe Apply safe and unsafe fixes; implies --fix. Fixes that delete files still need --allow-remove-files.
--dependency, --dependency-types, --specifier-types, --source Narrow the version-group and semver-group rules, and only those, to some instances (see Filtering instances).
--dry-run With --fix or --fix-unsafe: plan the fixes and print them as a unified diff; no manifest is written and no install runs, while the reports are still rendered, to stdout, --output and every FORMAT=FILE (see Fixing).
--allow-remove-files Let fixes delete files (unused-files); without it they are skipped and reported as removes-files. Needs --fix or --fix-unsafe.
--fix-type <TYPE> Only apply the fixes of these rules: rule ids or knip issue types (see Fixing). Comma separated or repeatable; needs --fix or --fix-unsafe.
--select <highest|lowest> Which version a version alignment fix targets, overriding [policy] prefer for this run.
--no-install Do not run the package manager after fixing.
--no-prompt Never ask which alternative fix to apply; the diagnostic stays unfixed unless --select decides.
--max-warnings <N> Exit 1 when there are more than N warnings.
--fail-on-warnings Same as --max-warnings 0. Also set by [lint] fail-on-warnings. Conflicts with --max-warnings.
--max-issues <N> Exit 1 only when there are more than N errors (default 0), counted over all roots. Warnings still follow --max-warnings.
--max-show-issues <N> Show at most N findings of each rule, in report order over all roots. The summary still counts every finding and the exit code is unchanged; in human output a note on stderr says how many were left out. Human, json and toon output only: when any --format is another format, or with --fix, it exits 2; with several formats, each human, json and toon rendering is shortened. The annotations human output adds under GitHub Actions still list every finding.
--no-exit-code Exit 0 when problems remain. A run that could not happen still exits 2.
--rule <ID>=<off|info|warn|error> Set a rule’s level. Repeatable.
--ignore-rule <ID> Turn a rule off. Repeatable.
--ignore-package <NAME> Ignore a package by name or glob in every rule. Repeatable. The flags replace [workspace] ignore-packages from the configuration files instead of adding to it.
--ignore-dependency <NAME> Ignore a dependency in every rule. Repeatable. Adds to the [[ignore]] entries of the configuration files. sherif’s -i only silenced its version check; for that scope write an [[ignore]] entry with rules = ["version-mismatch"], as skif migrate does.
--ignore-rule-for-package <RULE:PACKAGE> Ignore one rule for one package. Repeatable. Adds to the [[ignore]] entries of the configuration files.
--require-ignore-reasons Fail with exit code 2 when an [[ignore]] entry, an entry of a [js] ignore list or an entry of a rule’s allow option of a configuration file has no reason, naming the entry. Entries from flags are exempt. [lint] require-ignore-reasons = true does the same from the file.
--config <FILE> Use this configuration file (and the files it extends) for every root instead of discovering skif.toml files. In a multi-root run its [js.workspaces] keys and ignore-workspaces globs are relative to the start directory. Conflicts with --no-config.
--no-config Read no configuration file: the defaults plus the other flags.
--no-js Skip JavaScript analysis. Overrides [js] enabled.
--production Only analyse production code in JavaScript analysis. Overrides [js] production.
--no-gitignore Also analyse the source files that .gitignore files hide; .ignore files and the directories skif always skips (node_modules, dist, …) still apply. Files are then listed by walking the directories, not from the git index. The search for roots of a multi-root run still honours .gitignore.
--tsconfig <FILE>, --tsConfig, -t The TypeScript configuration of the root package, relative to the workspace root, used instead of its tsconfig.json for path aliases and compiler options. Overrides [js] tsconfig. Other packages keep their own tsconfig.json. With -r it applies to the roots that have the file and the others keep their own setting; a file that no root has, or a path that is absolute or leaves the root, exits 2. Roots without JavaScript analysis (--no-js, [js] enabled = false) are skipped.
--use-tsconfig-files Take the project files of each package from its tsconfig.json (files, and include minus exclude) instead of the project globs. Same as [js] use-tsconfig-files = true. A tsconfig that selects no file of its package is reported on stderr.
--include-entry-exports Report unused exports of entry files too. Overrides [js] include-entry-exports, also where a [js.workspaces] table sets it.
--isolate-workspaces Workspace isolation without production mode: each workspace package uses only the dependencies its own package.json lists. An import, a binary or a package a tool config names is no longer satisfied by a containing package or the root, so it is reported as unlisted there, and a root dependency only members use is unused; a private package’s unlisted import of a workspace member is reported, and use-public-hoisting is ignored. Tests, test setup, scripts and tool configs are analysed as in any default run and checked against their own package’s manifest, development dependencies included, so one run covers every file. What counts as listed is otherwise unchanged (type-only imports still need a listing). Same as [js] isolate-workspaces = true.
--strict knip’s strict mode: --production and --isolate-workspaces, and only direct dependencies count. Same as [js] strict = true. Production code (every file but a .d.ts, .d.mts or .d.cts declaration file, whose imports may use any listed package and count as type-only, so a listed @types package stands in) must import from dependencies or peerDependencies: a package listed only in devDependencies or optionalDependencies is reported by unlisted-dependencies, and neither a peer dependency of a listed package nor, for a private package, another workspace member stands in for a listed one. Type-only imports (import type, import { type A } when every name is a type, export type ... from, import("x") in a type, JSDoc imports, /// <reference types>) use no package and need none listed, so a dependency that only they import is unused and a devDependencies package they import is fine. Required peer dependencies (not marked optional in peerDependenciesMeta) count as production dependencies: unused-dependencies reports one that nothing imports. Unlike knip, which accepts an optional peer dependency only for an import inside try, skif accepts any import of one.
--include <TYPE|RULE> Report only these rules. A value is a knip issue type (files, subpaths, dependencies, devDependencies, optionalPeerDependencies, unlisted, binaries, unresolved, exports, types, nsExports, nsTypes, duplicates, enumMembers, namespaceMembers, catalog, catalogReferences, cycles), which stands for the skif rules that report it, or a skif rule id. A rule that is off is turned on, unless --ignore-rule or --rule ID=off turns it off: at its default severity when the configuration turned it off, at error when it is off by default. Comma separated, repeatable. An unknown value exits 2.
--exclude <TYPE|RULE> Do not report these rules; values as for --include. Comma separated, repeatable.
--dependencies, --exports, --files, --cycles knip’s shortcuts for --include: --dependencies is dependencies, unlisted, binaries, unresolved, catalog, catalogReferences and, without --production, devDependencies and optionalPeerDependencies; --exports is exports, types, enumMembers, namespaceMembers and duplicates.
--tags <-TAG> Do not report exports tagged @TAG; adds to the ignore-tags option of unused-exports. Comma separated, repeatable. knip’s +TAG (only tagged exports) has no counterpart and exits 2, as does an ignore-tags in the configuration that is not a list.
--color <auto|always|never> When to colour human output. Default auto (see human under Output formats).
--watch Lint again whenever a file below the root changes, until interrupted. Conflicts with --fix and --fix-unsafe. See editors and agents.
--cache Keep the parse results of source files between runs in modules.bin, so a run parses only the files that changed. Entries are keyed by each file’s name and text, so the cache never changes the report. The store is written after the run, whatever its exit code, and only when its entries changed; it keeps exactly the entries the run used. A store that is damaged or written by another version is ignored and replaced (--debug says why); a store that cannot be written prints a warning on stderr and leaves the exit code alone. See editors and agents.
--cache-location <DIR> The directory of the --cache store, relative to the working directory; created when missing. Default: node_modules/.cache/skif/ below the workspace root, or below the invocation directory of a multi-root run; under bazel test (TEST_TMPDIR set) $TEST_TMPDIR/skif/, so nothing is written into Bazel’s output tree. Requires --cache (exit 2 without it).
--trace-dependency <NAME> Instead of linting, print where the dependency is listed (manifest, section, specifier), every import of it in the module graph with the file and line, and the packages that count it as used, through imports, scripts, tool configuration or its @types twin. --format json prints one document with a traces array, one entry per root. Conflicts with --fix, with the report filters (--workspace, --include, --exclude and their shortcuts) and with --tags, --max-show-issues, --rule and --ignore-rule, which change only the report.
--debug Print to stderr what the run loaded: each root with its configuration files, package manager and packages, and the phase timings.
--performance Print the time each phase took to stderr, as SKIF_TIMINGS=1 does. Work that runs on several threads is summed over them. The lines are written when the run ends; under --watch, after each run. skif lsp and skif mcp take SKIF_TIMINGS=1 instead and write them after each message or request.
--duration Print the wall time of the run to stderr.
--memory Print the peak resident set size of the run to stderr. Linux only; elsewhere a line says it is not measured.
-W, --workspace <NAME|DIR> Report only the findings of these workspace packages, by package name or directory relative to the root (. is the root). Globs and ! exclusions work as in [workspace] ignore-packages. Repeatable. The analysis still covers every package, so the findings are those of a full run; --fix fixes only what is reported. A finding of no package (the root manifest, pnpm-workspace.yaml, a catalog) belongs to the root, so it is reported and fixed only when the root is selected (-W .). No matching package exits 2.

The flags --type-aware and --no-type-aware were removed in 0.9.0 with type-aware analysis: either is a usage error that says so and exits 2.

Flags are the top layer of the configuration precedence: defaults, then the file, then the command line. --ignore-package replaces the file’s [workspace] ignore-packages; --ignore-dependency and --ignore-rule-for-package add [[ignore]] entries to those of the files; --rule and --ignore-rule set the level of each rule they name.

skif config [PATH] [-r] answers which files configure a root and where a value came from. With -r it reports every root at or below PATH. Paths are printed relative to the root (or, with -r, to PATH) with forward slashes.

Flag Meaning
--show Print the configuration files in the order they apply, each as root, ancestor, extended by <file> or explicit, then the effective merged configuration as TOML.
--explain <KEY> Print every assignment of KEY (lint.fail-on-warnings, rules.ID.level, js.ignore-dependencies, version-groups[0]), oldest first, as file:line:column with the operation set, append, prepend or reset, and the final value. A table or list key also lists the keys below it that a file set.
--package <NAME> With --explain, also list the [[overrides]] that apply to the workspace package NAME, with the file and line that declared each.
--config <FILE>, --no-config Report the configuration a lint run with the same flag uses: the explicit file and what it extends, or none. With -r and --config, a root below PATH names the directory its packages are selected by in the file’s [js.workspaces] keys and ignore-workspaces globs (# [js.workspaces] keys name this root "tools/sub", workspace-keys-anchor in JSON).
--format <human|json> json prints one document with the same version and skif members as the other JSON outputs.

An unknown key exits 2 and names the closest keys.

skif explain-usage <FILE[#EXPORT]> [PATH] answers why a file is not reported as unused, or why an export is not reported as unused. FILE is relative to the current directory, or absolute, and must lie inside the workspace found at PATH; a file below a linked directory (Bazel’s bazel-bin) is matched by its path through the link first, as the lint report names it, then by the path the link points to. The report names the entry rule when the file is an entry file, says when it is a build source (a file a plugin names as one a tool builds from, such as a Bazel rule’s srcs or data: used, but no entry, so its exports are judged), lists every import of it with the importing file and line (and which names the import brings in), and shows the shortest chain of imports from an entry file or a build source. With #EXPORT it lists the modules that import that export by name or as a whole, follows re-exports (export { x } from, export *) into the modules that use them, and ends with a verdict (public, used or unused) computed from the same facts as the lines above it. With #Class.member (a member of an exported class) it explains the class export and then the member: the files that read a property of that name on any object, the reason it is not judged when it is not (decorated, inherited from a library base, implementing an interface, public API), and the verdict of unused-class-members. #Enum.member and #Namespace.member explain an enum or namespace member with the verdict of unused-enum-members or unused-namespace-members; instead of files, the report says whether the member is read through an import or in its own file, or the whole enum or namespace is used. In JSON these are the class-member member: class, member, of (enum or namespace; omitted for a class), verdict, exemption, readers (the files, for a class member) and used (true when an enum or namespace member is read through an import or in its own file, or the whole enum or namespace is used; omitted otherwise). An export of a file that may be an unknown entry of its package (a package whose entry files are not fully known, or a file in the narrowed scope of such a package) is not-judged instead of unused, because it is not reported. The command builds the whole JavaScript analysis, so it costs as much as the JavaScript part of a lint run.

Flag Meaning
--production, --config <FILE>, --no-config Analyse as the lint run with the same flag does.
--dependency <NAME> Explain the dependency NAME instead of a file (see below); the one positional argument is then PATH.
--package <NAME|DIR> With --dependency, explain it in this package only: its name, or its directory relative to the current directory. Exits 2 when no package of the workspace has that name or directory.
--format <human|json> json prints one document with version, skif and a report member: file, in-graph, entry (the rule that makes the file an entry: entry-glob, config-file, script (also for the source of a build output a script runs), published, bin-stub for a file an extensionless bin stub loads, incomplete-scope, external-entry-glob for a glob of another package that points outside it, enclosing-entry-glob for a plugin glob of a package that contains the file’s package, enclosing-incomplete-scope for the narrowed incomplete scope of such a package, with its directory in scope-package and its globs in incomplete-scope, or unknown), build-source when the file is one, imported-by (file, line, kind, names, reachable; line is 0 for the use of a registered Vue component in a template, which has no location), chain-from-entry, chain-from-build-source when that chain starts at a build source and, with #EXPORT, export (verdict, users, re-exports, entry-public, tagged-public, in-used-signature, entries-incomplete when it is true and, for a custom element, registered).

A file that is not part of the module graph exits 2 with the reason; in JSON mode the error document carries the same report, whose absence is one of unused-file (reported by unused-files), package-excluded, declaration-file, ignored, outside-project, not-discovered (missing, ignored by Git, not a source file, or owned by no package) and entries-incomplete, which is only given for a source file that discovery, the project globs and the ignores leave in. For entries-incomplete no file of the package is judged unused because its entry files are not fully known and may be anywhere in it, and incomplete lists each cause with its plugin and file: unparsable-config, unknown-config (the config evaluates to a value that cannot be known statically), unknown-spread (it spreads or merges in an unknown value, such as a base config imported from an installed package; a conditional spread of object literals is not one), computed-entries (the keys the tool reads entries from are computed), unmapped-published (package.json publishes build output with no source behind it), unmapped-entry (a tool configuration names an entry in build output with no source behind it; file is the entry), no-entries (the package has no source file, entry or script of its own, so its manifest only lists what code elsewhere installs it for) or unspecified. widened-by (file:line) names the computed import() or require() that made the package unjudged as a whole although its configs narrowed what they hide. When the configs narrow it (see incomplete entries), a file in the narrowed scope is in the graph with the entry incomplete-scope, and an unused file outside it has the absence unused-file with the scope’s globs in incomplete-scope and the causes in incomplete. It also exits 2 when the root cannot be loaded or the file lies outside the workspace.

skif explain-usage --dependency <NAME> [PATH] answers why unused-dependencies (or unused-dev-dependencies) reports a dependency or not. For every package that lists it or that something credits it to (with --package, that package alone) it prints the manifest entry, the verdict and the uses that credit the package’s manifest: an import (also a re-export, a declare module augmentation in a module file or an import of the package an @types package types), a mock, a compiler of the file’s type, the jsx-runtime of a file with JSX, a command a node:child_process call runs, a binary a script, command or plugin runs, a script-or-plugin of the package, a tool config that names it, and ambient-types for a globals-only @types package a tsconfig.json includes. The uses of a package’s manifest can come from the files of packages inside it, such as the root’s. Imports of it by files of the package that credit no manifest (a type-only import in strict mode) are listed as not counted. For a package that does not list it, the tool config files that name it are listed with the line of the reference when the config gives one (a Bazel BUILD label), as unlisted-dependencies reports them. The verdict and the uses come from the same record of uses the rule judges. The command exits 0 whatever the verdict.

--format json member Meaning
report.dependency, report.production, report.strict The dependency, and whether production or strict mode narrowed what counts.
report.packages[] package, dir (. for the root), listed (manifest, section, specifier, or null), verdict, credit, uses, not-counted (each file, line, specifier, kind, type-only, package, reachable) and unlisted-references (each file, and line when known).
verdict used, unused (what the rule reports when it is on), ignored (an ignore-dependencies entry or a plugin covers it), optional-peer, package-excluded, entries-incomplete (not judged) or not-listed.
credit With used, how: {"kind": "uses"} (the uses list it), always-used (a tool used without an import, such as typescript), runtime-types (@types/node), types-of with the typed package, or peer-of with the host that needs it as a peer.
uses[] kind, and file (relative to the root) or binary when the use has one.

skif migrate [PATH] reads the sherif, syncpack and knip configuration of the project at PATH (default .) and writes a skif.toml. It is a one-shot translator: nothing is executed, no file is deleted, and the configuration of the old tools stays where it is. The migration guide lists what is translated and how.

Flag Meaning
--from <TOOL>[,<TOOL>...] sherif, syncpack, knip or auto (default): every tool that has a configuration file, a package.json key or a script in the project.
--source <FILE> Read this configuration file instead of looking for one. Needs exactly one tool in --from.
--profile <exact|full> exact (default) keeps only the checks the old tools ran and turns off, in [rules], the other rules skif enables by default. full leaves skif’s defaults for them.
--output <FILE> Write here instead of PATH/skif.toml. - prints the configuration to stdout. With --merge, the merge of the existing configuration and the migration is written here and the existing file is left as it is; a FILE that exists is refused. A FILE that is not in PATH itself gets the [[overrides]] patterns written from the root, with $ROOT/.
--merge Combine with the existing configuration file (skif.toml or .skif.toml), which is edited in place: its comments and order stay, tables it lacks are appended under a banner, and in a table both define the existing value wins and lists are united. Values the exact profile added (marked with a # skif migrate: not checked by ... comment) do not count as existing values, so migrating tools in several steps ends with the same checks as one --from sherif,syncpack,knip run. The exact profile writes no off value into a file that has content: a rule it does not name keeps running. Migrating knip sets [js] enabled = false to true.
--force Replace the existing configuration file (skif.toml or .skif.toml, whichever exists). Without --merge or --force the command refuses to overwrite one. When the replaced file had an extends (a skif baseline file, a shared preset), a warning names the files, which the new file no longer extends.
--dry-run Print the configuration to stdout and the report to stderr; write nothing.
--format <human|json> json prints one document on stdout with version, skif, profile, tools, translated, default, needs-human, extra-checks, notes, written, kept-existing, left-as-existing (the off values --merge did not write, as rules.<id> paths), replaced-existing (js.enabled when migrating knip turned it on, and each entry or project list whose plain pattern took the migrated ! marker) and, when nothing is written, toml.
--strict Exit 1 when any construct needs a human.
--strict-hints Write knip’s treatConfigHintsAsErrors as stale-js-config = "error"; by default it is written as warn.

Exit 0 when the file was produced (also when notes need a human, unless --strict), 1 with --strict and such notes, 2 when a configuration cannot be read or the output cannot be written.

skif baseline records the findings of a repository that adopts skif with problems it cannot fix at once, as [[ignore]] entries in a file of their own, so the lint run is clean from day one and the list can only shrink. The adoption guide shows the workflow.

Command Does
skif baseline write [PATH] Lint the root at PATH (resolved as for linting, with the lint flags given) without the baseline’s entries, and add an entry for every error and warning that no entry of the baseline matches. Existing entries and their reasons stay. When no configuration file of the root reaches the baseline through extends, its path is added to the extends of the root’s skif.toml (or .skif.toml, created when there is none), keeping the rest of that file as it was. Running it again changes nothing.
skif baseline prune [PATH] Lint the same way and remove the entries that match no finding. The file stays when it is left empty.
skif baseline check [PATH] Exit 1 when the baseline has an entry that its earlier version lacks, and print the added entries. Entries are compared by rules, packages, dependencies and files, not by reason. Lints nothing.

Each entry names the rule, the package (its name, or its directory relative to the root when two packages share the name) and the dependency. A finding of a rule about the specifier itself (version-mismatch, semver-range-mismatch, policy-conflict, unsynced-dependency-family, incompatible-peer-dependencies, catalog-mismatch, catalog-version-divergence) is recorded as name@specifier, so the entry silences only that version: a member moving to a third version, or a new member on another one, fails the run again. Any other rule’s finding is recorded by the dependency’s name alone, so bumping a baselined @types/node in dependencies (types-in-dependencies) does not reopen it. A finding about no dependency that is located in a file other than a package.json (unused-files, unused-exports, circular-imports) is recorded with that file in files, so a new unused file or export elsewhere in the package fails the run; an unnamed root package’s finding of this kind is recorded by the file alone. Glob characters in a name or specifier are written as one-character classes ([*]), and a leading ! as {!} so it is not read as an exclusion, so the entry matches literally. info findings are not recorded, and neither is a finding with neither a package nor a dependency, which an entry could only cover by turning its rule off, nor one in a root package without a name of its own, which no package pattern selects alone; write lists those on stderr with the cause. Entries are sorted, each written once, and the file holds nothing but [[ignore]] entries: the commands rewrite it whole, so a comment written inside it is not kept, while an edited reason is.

Flag Meaning
-r, --recursive Cover every workspace and standalone package at or below PATH, as skif -r does, each with the baseline file skif.baseline.toml in its root. A PATH without a package.json at or above it covers every root below it as well.
--file <FILE> The baseline file. Default skif.baseline.toml in the workspace root. Only for a single root: with several, it is a usage error.
Lint flags write and prune only: --config, --rule, --ignore-rule, --ignore-package, --ignore-dependency, --ignore-rule-for-package, --no-js, --production, --isolate-workspaces, --strict, --no-gitignore, --include-entry-exports, --tsconfig, --use-tsconfig-files, --select, -W, --include, --exclude, --dependencies, --exports, --files, --cycles, --tags and the instance filters (--dependency, --dependency-types, --specifier-types, --source) mean what they mean for a lint run, so the baseline is recorded and pruned against the findings of the run it is for: give write and prune the flags the CI run uses. A filter that narrows the report (-W, --include) makes prune remove the entries of the findings it leaves out.
--reason <TEXT> write only: the reason of the entries it adds. Default baseline.
--base <REF> check only: compare with the baseline file at this git revision (origin/main), read with git show. A file that did not exist at the revision is an empty baseline. A revision that is not a commit is a usage error.
--base-file <FILE> check only: compare with this file instead, for runs without git. One of --base and --base-file is required.
--format <human|json> json prints one document with version, skif, command, file (relative to the root), entries (how many the file holds), added and removed (each entry with rules, packages, dependencies, files when it has any, and reason); write adds extended (the configuration file whose extends gained the baseline, else null) and unrecorded (rule, package, dependency, message, and cause: workspace-wide or unnamed-root), write and prune add written, check adds base.

With several roots, the JSON document holds command and roots, one object per root with root (relative to PATH) and the members above, and errors for roots that could not be loaded; human output names each file relative to PATH.

write and prune check that the configuration of the run applies the baseline: when no configuration file of the run extends it (a file given with --config must extend it itself), or a reset = ["ignore"] in a file applied after it drops its entries, they exit 2 naming the cause, since the lint run would still report every recorded finding. To drop inherited [[ignore]] entries and keep the baseline, put the reset in a file listed before the baseline in extends.

write and prune exit 0 when they finished and 2 when they could not run (a baseline file with other keys, a missing file for prune, an invalid configuration, a baseline the configuration does not apply). check exits 0 when the baseline gained no entry, 1 when it did and 2 when it could not run. check --base is the one place the CLI runs git; it needs the revision fetched (git fetch origin main in a shallow CI checkout).

skif update [PATH] asks the npm registry which newer versions exist for the dependencies of the workspace at PATH (default .) and writes them, keeping each file’s formatting; skif update --check writes nothing and exits 1 when an update is available. It is syncpack’s update: an instance moves when its version group prefers the highest version (the default), it is not a workspace package, no sibling in its group uses catalog:, and it is written as an exact version, a range over one version (^1.2.3, ~1.2.3, >=1.2.3), a bare major or minor, or latest. Catalog entries of pnpm-workspace.yaml, the root package.json (bun) and .yarnrc.yml move the same way. A prerelease only moves to a newer prerelease of the same channel, deprecated versions are skipped, and the range style is kept unless a [[semver-groups]] entry asks for another. Peer and optional dependencies, the override sections and custom types move only when [policy] dependency-types covers them. [update] and [[update-groups]] in the configuration set the minimum release age and what each dependency may move to.

Flag Meaning
--check Write nothing; exit 1 when an update is available. Allowed in CI.
--interactive Choose the updates to write from a list, one line per dependency, current and target specifier with the packages and places it moves (space to choose, enter to write, escape to write nothing). Only the chosen updates are written and reported. Refused with exit 2 when stdin or stdout is not a terminal; cannot be combined with --check.
--target <latest|minor|patch> How far a version may move: the highest version, the highest with the same major, or the highest with the same major and minor. Default latest. An [[update-groups]] entry can only narrow it.
--dependencies <NAME> Only these dependencies, by name or glob. Repeatable. Other dependencies are not looked up.
--no-install Do not run the package manager after writing.
--config <FILE>, --no-config As for linting.
--format <human|json> json prints one document with version, skif, check, target, minimumReleaseAge, queried, updates (each with path, line, column, package, dependency, place, current, target and state, which is syncpack’s DiffersToNpmRegistry), failures (dependency, message), notes (dependency, message: what was left out, such as a version without a publish time) declined with --interactive (how many updates were not chosen) and, after writing, changed and install.

Without --check, skif update writes every update atomically per file and then runs the package manager’s install, as --fix does. It is refused with exit 2 when CI is truthy; --check is the CI form. Exit 0 when there was nothing to update or everything was written, 1 with --check and updates available, and 2 when the registry could not answer for a package (the updates it found are still reported, and written without --check), the install failed, or the run could not start.

Network. Linting, --fix and every other command never open a network connection. skif update requests <registry>/<name> (@scope%2fname for a scoped name; a name npm would not accept, such as one over 214 characters or a yarn resolution path like **/foo read with override-reading = "syncpack", is not requested and is noted in the report without changing the exit code) once per dependency name, with up to [update] max-concurrent-requests (default 12) at a time, a 10 second connect timeout and a 60 second limit per request. The registry is npm_config_registry, else registry in the project’s .npmrc, else in the user’s .npmrc (NPM_CONFIG_USERCONFIG or ~/.npmrc), else https://registry.npmjs.org/; @scope:registry entries choose a registry per scope, and @jsr/* packages go to https://npm.jsr.io/ unless @jsr:registry says otherwise. A //host/path/:_authToken entry (with ${VAR} expanded from the environment) is sent as a bearer token to that registry only, and is never printed. In the project’s .npmrc, which anyone who can change the repository controls, ${VAR} is expanded only in a token, and only for registry.npmjs.org or a host that the user’s .npmrc or npm_config_registry also names, when that file does not set an http:// registry for the host; any other such token, and any registry, @scope:registry or other line of it that contains ${, is ignored with a warning naming the host or key, so a changed .npmrc cannot send a CI secret elsewhere, in a URL or over plain http. The user’s .npmrc expands ${VAR} everywhere. A token sent to an http:// registry draws a warning, and a redirect never carries a token. Credentials, a query or a fragment written in a registry URL are dropped; _auth, usernames and passwords, client certificates and strict-ssl are not read. Certificates are checked against the operating system’s trust store (SSL_CERT_FILE and SSL_CERT_DIR replace it), and HTTPS_PROXY, ALL_PROXY and NO_PROXY are honoured.

skif list [PATH] and skif json [PATH] show every dependency instance the version groups and the catalog govern, valid or not, as syncpack’s list and json do. The root is resolved as for linting, -r covers every root below PATH, and --config and --no-config work as for linting. Instances are ordered by version group (the configured groups in order, then the default group, then the catalog), then dependency name, then where they are declared. Instances outside the default scope ([policy] dependency-types) that no group names are not listed.

The state of an instance is the one a lint run gives it: the syncpack state name of the version and catalog policies, including the valid states (IsHighestOrLowestSemver, IsIdenticalToPin, IsLocalAndValid, IsCatalog, IsIgnored, …). skif’s own names are UnusedGroup, InvalidPin, DiffersToOtherCatalog and IsIdenticalToCatalog (a plain version the catalog rules leave alone). An instance a rule reports carries that rule and its severity; a state whose rule is off, or which an [[ignore]] entry silences, has none. Workspace-protocol and dependency-family findings are left to the lint run.

skif list prints one line per dependency under a heading per version group: the worst severity (ok when every instance is valid, - when a state is not reported), the name and the distinct specifiers. --show takes a comma separated list: instances adds a line per instance, statuses the state names, hints marks dependencies that are workspace packages, ignored lists the dependencies of ignored groups, all and none set everything. The default is hints,statuses.

skif json prints one object per instance with dependency, dependencyType (prod, dev, peer, optional, local, resolutions, overrides, pnpm-overrides or a custom type), property, package (the file, relative to the root), packageName, versionGroup (syncpack’s name: HighestSemver, LowestSemver, Pinned, Banned, Ignored, SameRange, SameMinor, SnappedTo or Catalog), versionGroupIndex, versionGroupLabel, preferredSemverRange, statusCode, statusType (Valid, Fixable, Unfixable, Conflict or Suspect), rule, severity, isLocal, actual and expected (each { "raw", "type" }, expected null when unknown).

Both exit 1 when an instance is reported at error severity, 0 otherwise, and 2 when skif could not run.

skif, skif list and skif json take syncpack’s instance filters. An instance that does not pass is left out before it is assigned to a version group, so it is neither reported nor aligned with: --source packages/app/package.json checks that package’s instances against each other only, as syncpack does.

Flag Keeps
--dependency <NAME> Dependencies whose name matches the name or glob (react, @types/**, !eslint, $LOCAL). Repeatable. syncpack calls it --dependencies; skif keeps that name for knip’s issue-type shortcut.
--dependency-types <TYPES> These dependency types, comma separated (prod,dev, !local, a [[custom-types]] name). The list also replaces [policy] dependency-types as the scope of the default group for the run, so --dependency-types peer checks peer ranges.
--specifier-types <TYPES> These specifier types, comma separated (exact, range, !workspace-protocol; the values of specifier-types selectors).
--source <GLOB> Instances declared in files matching the glob, relative to the root (packages/*/package.json, pnpm-workspace.yaml). Repeatable. Unlike syncpack’s --source, it does not change which packages make up the workspace.

The filters apply only to the version-group and semver-group rules (version-mismatch, banned-dependency, semver-range-mismatch, policy-conflict, invalid-local-version) and to the listing; the catalog, workspace protocol, family and manifest rules see the whole workspace. A configured group that the filters leave without instances is not reported as unused.

skif format [PATH] lints with the package-json-format rule alone, at error, and applies its safe fix to every package.json of the workspace: the key order, the sorted fields, the order of the exports conditions, the bugs and repository shorthands and, with [format] indent, the layout. The [format] table configures it; the defaults are syncpack’s, except that exports conditions only move types first and default last. It never runs the package manager, and like --fix it is refused when CI is truthy.

Flag Meaning
--check Report the manifests that are not formatted and write nothing.
--unsafe Also write an unsafe fix: a sort-exports that reorders conditions other than types and default, which changes how imports resolve. Conflicts with --check.
--format <FORMAT> One of the lint formats, written to stdout; no FORMAT=FILE and not repeatable.
-r, --recursive, --config <FILE>, --no-config, --color As for a lint run.

The exit codes are a lint’s: --check exits 1 when a manifest is not formatted and 0 when every one is; without --check the code comes from the lint after writing. [[ignore]] entries and ignore-packages apply. To check formatting in every lint instead, set package-json-format = "error" in [rules]; --fix then formats too, and --fix-unsafe also applies an unsafe exports reorder.

Code Meaning
0 Clean. Warnings within --max-warnings are allowed, and info never counts.
1 Problems remain; for skif baseline check, the baseline gained entries.
2 skif could not run: invalid or ambiguous configuration, no package.json found at or below PATH, bad flags, a refused --fix or skif update, a failed install step, or a package the registry could not answer for in skif update.
Format Output
human Diagnostics grouped by file, optionally coloured, with a summary. Colour is on only when stdout is a TTY, NO_COLOR is unset and the format is human. A note before the summary names the packages whose unused files and dependencies were not fully checked.
json One versioned document with version, summary and diagnostics; a multi-root run adds a roots array with each root’s path, packages and summary. Each diagnostic has rule, severity, message, location with line and column span, related locations and fix titles. incomplete-packages (omitted when empty) lists the packages whose unused files and dependencies were not fully checked, see below.
toon The json document encoded as TOON (Token-Oriented Object Notation): the same data, error documents included, without JSON’s quotes and braces. json stays the contract.
sarif SARIF 2.1.0 for code scanning.
github GitHub Actions workflow-command annotations.
codeclimate A Code Climate JSON array for GitLab Code Quality: one issue per diagnostic with description, check_name (the rule), fingerprint, severity and location (path, lines.begin). Errors are major, warnings minor and infos info. The fingerprint is a hash of the rule, path, package, dependency, specifier and message text (not the line), so an issue keeps its identity when code above it moves; a release that rewords a message changes the fingerprints of its issues. Paths are relative to the repository top-level.
compact One line per diagnostic, path:line:col rule message (path rule message without a position), and nothing else.
markdown A heading, a summary line and a table per rule (location, severity, message), for pull request comments. Repository text is escaped so it cannot break the table, and @ (as in @types/node), :// and www. are broken with an empty HTML comment so they do not become mentions or links.
disclosure Like markdown, with each rule’s table folded in a <details> section.
codeowners compact lines grouped under each owner from the repository’s CODEOWNERS file (.github/CODEOWNERS, CODEOWNERS or docs/CODEOWNERS, the first that exists at the repository top-level). The last matching pattern wins, and an entry without owners in a GitLab section takes the section’s default owners ([Section] @owner); a diagnostic with several owners is listed under each, and diagnostics no pattern covers are under (unowned). Exit 2 (a config error) when there is no CODEOWNERS file.

When a package’s entry files are not all known (a tool config skif cannot read, or published build output with no source behind it), skif does not report its unused dependencies, and reports its unused files only outside what the unreadable config could make entries (see incomplete entries). The JSON report names each such package in incomplete-packages, sorted by directory: its name, its dir (. for the root package), its reasons, each a cause with the plugin and file when known, using the causes skif explain-usage reports, and its scope: "package" when no file of the package was judged unused, or {"within": [...]} with the globs, relative to dir, of the only files left unjudged (the files the unreadable config can make entries); the human output names those globs after the package. Paths are relative to the run’s base. The lint report, the error document and the explain-usage document carry version 2 since 0.9.0, which removed their type-aware members; added fields do not change it. The other JSON documents (config, rules, update, migrate) stay at 1.

In --format json mode stdout holds exactly one JSON document in every case, including failures. A failure is an error document with a kind (config, workspace, io, usage, ci-refusal or internal, a bug in skif), a message and, when known, path, line and column. --format toon gives the same document in TOON. --output never receives an error document: on failure the file is not written and the error goes to stdout.

--format is repeatable, so one lint can feed several consumers. Each value is FORMAT (written to stdout) or FORMAT=FILE (written to FILE); at most one value may go to stdout, and with none stdout stays empty:

Terminal window
skif --format human --format json=skif.json --format codeclimate=gl-code-quality.json
  • Two formats on stdout, the same file twice (however it is spelled, so a/../x and x are the same file), a FORMAT=FILE that names an existing directory, or --output together with several formats or with FORMAT=FILE is a usage error (exit 2). --output FILE is the single-format spelling of FORMAT=FILE.
  • Every rendering is made before any file is written. When one fails (for example codeowners without a CODEOWNERS file), no file is written or replaced and the run exits 2. Each file is replaced atomically, but a write that fails partway leaves the files written before it in place.
  • The format on stdout decides JSON mode: with json (or toon) on stdout, an error is an error document there; when no format goes to stdout, the first --format decides, so --format json=skif.json alone behaves like --format json --output skif.json.
  • Only the rendering on stdout (or in --output) is coloured; a FORMAT=FILE rendering never is.
  • The exit code is the same whatever the formats.

--fix applies fixes marked safe; --fix-unsafe also applies unsafe ones. A version alignment is safe when it is a later version within semver’s compatibility window, in the same shape: an exact version or ^ range within its major (left-pad 1.0.0 to 1.3.0), ~ within its minor. A move across a major, a downgrade, a prerelease or a change of range needs --fix-unsafe, also when a pin asks for it (see fix safety). A fix run:

  1. Lints and builds the fix plan, selecting fixes by --fix or --fix-unsafe, --fix-type, --allow-remove-files and --select.
  2. Writes the plan, atomically per file.
  3. Lints again on the changed tree. The report and exit code come from this second run, so exit 1 means problems remain after fixing.
  4. Runs the detected package manager’s install in the workspace root, unless --no-install was given, no file changed, or no package manager was detected. If the install fails the fixes stay written and the exit code is 2.

--dry-run stops after step 1, so no manifest is written and no install runs; every report is still rendered, to stdout, the --output file or each FORMAT=FILE, as without --dry-run. Human output shows Would fix ... and a unified diff per file before the report of the unchanged tree, and --format json adds "dry-run": true and a changes array (path, kind modify, create or delete, and diff) to the fix object. The exit code is the one of the unchanged tree. A dry run is allowed in CI.

Deleting a file is never part of --fix-unsafe alone: the fix of unused-files is skipped, with the reason removes-files, unless --allow-remove-files is given as well, as with knip. Every other unsafe fix, such as removing an unused export, enum member, namespace member, dependency or catalog entry, edits a file in place. Some of these findings have no fix because removing them could change behaviour: an enum member followed by a member without an initializer (which would be renumbered), a member another member mentions, and an export default <expression> whose expression may have side effects, such as a call.

A run of a single root does not analyse the code of the other roots below it (a nested standalone package or workspace), so a dependency of the root that only their code uses is reported unused, and its fix removes it. When a fix run of a single root would remove a dependency and other roots lie below it, skif warns on stderr and names them; skif -r lints them together and credits their uses.

--fix-type narrows a fix run to some rules. A value is a rule id (unused-exports) or one of knip’s issue types, which stands for the rules that report the same findings:

--fix-type Rules
dependencies unused-dependencies, unused-dev-dependencies, unused-optional-peer-dependencies
devDependencies unused-dev-dependencies
optionalPeerDependencies unused-optional-peer-dependencies
exports unused-exports, unused-namespace-exports
nsExports unused-namespace-exports
types unused-types, unused-namespace-types
nsTypes unused-namespace-types
enumMembers unused-enum-members
namespaceMembers unused-namespace-members
files unused-files (with --allow-remove-files)
subpaths unused-subpath-imports
catalog unused-catalog-entries

The other knip issue types (unlisted, binaries, unresolved, duplicates, catalogReferences, cycles) are accepted and map to rules that have no fix. An unknown value exits 2 with a usage error before anything is linted. For example, skif --fix-unsafe --fix-type exports,types removes unused exports and types and nothing else.

--fix and --fix-unsafe (without --dry-run), skif format without --check and skif update without --check are refused with exit 2 (error kind ci-refusal) when CI is truthy: set, not empty after trimming, and not one of 0, false, no or off in any case. Linting without --fix is never affected. On GitHub Actions, with no --format, skif prints the human report plus workflow annotations.

Variable Effect
CI Truthy: the refusals above.
GITHUB_ACTIONS true: the default output adds workflow annotations.
GITHUB_WORKSPACE The repository top-level that github, sarif, codeclimate and codeowners paths are relative to, when it contains the root; else the nearest directory with a .git.
NO_COLOR Not empty: no colour under --color auto.
SKIF_TIMINGS Not empty and not 0: phase timings on stderr, as --performance.
BUILD_WORKSPACE_DIRECTORY, BUILD_WORKING_DIRECTORY Set by bazel run: relative paths resolve against the directory Bazel was run from.
TEST_TMPDIR Set by bazel test: the default --cache-location is $TEST_TMPDIR/skif/.
npm_config_registry, NPM_CONFIG_USERCONFIG, SSL_CERT_FILE, SSL_CERT_DIR, HTTPS_PROXY, ALL_PROXY, NO_PROXY skif update only (see Updating).