CLI
skif [OPTIONS] [PATH]skif rules [--format human|json]skif schemaskif 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 mcpskif lspskif [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:
- With
-r/--recursive, every root at or belowPATH(see below). - Otherwise the nearest ancestor workspace that lists the package at
PATHas a member. A package that declares a workspace is its own root. - Otherwise the package itself, linted in single-package mode: no workspace declaration is needed.
- When neither
PATHnor an ancestor holds apackage.jsonor a workspace declaration, every root belowPATH, 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.
Subcommands
Section titled “Subcommands”| 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.
Inspecting the configuration
Section titled “Inspecting the configuration”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.
Explaining usage
Section titled “Explaining usage”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. |
Migrating
Section titled “Migrating”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.
Baseline
Section titled “Baseline”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).
Updating
Section titled “Updating”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.
Listing instances
Section titled “Listing instances”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.
Filtering instances
Section titled “Filtering instances”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.
Formatting package.json
Section titled “Formatting package.json”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.
Exit codes
Section titled “Exit codes”| 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. |
Output formats
Section titled “Output formats”| 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.
Several reports in one run
Section titled “Several reports in one run”--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:
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/../xandxare the same file), aFORMAT=FILEthat names an existing directory, or--outputtogether with several formats or withFORMAT=FILEis a usage error (exit2).--output FILEis the single-format spelling ofFORMAT=FILE. - Every rendering is made before any file is written. When one fails (for example
codeownerswithout a CODEOWNERS file), no file is written or replaced and the run exits2. 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(ortoon) on stdout, an error is anerrordocument there; when no format goes to stdout, the first--formatdecides, so--format json=skif.jsonalone behaves like--format json --output skif.json. - Only the rendering on stdout (or in
--output) is coloured; aFORMAT=FILErendering never is. - The exit code is the same whatever the formats.
Fixing
Section titled “Fixing”--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:
- Lints and builds the fix plan, selecting fixes by
--fixor--fix-unsafe,--fix-type,--allow-remove-filesand--select. - Writes the plan, atomically per file.
- Lints again on the changed tree. The report and exit code come from this second run, so exit
1means problems remain after fixing. - Runs the detected package manager’s
installin the workspace root, unless--no-installwas given, no file changed, or no package manager was detected. If the install fails the fixes stay written and the exit code is2.
--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.
CI behaviour
Section titled “CI behaviour”--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.
Environment variables
Section titled “Environment variables”| 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). |