Settings

Every setting tracked by settings.toml, grouped the same way as the registry.

Aube generates this page from settings.toml. Edit that registry and rerun cargo run -p aube-settings --bin generate-settings-docs instead of editing this page by hand.

Summary

Setting	Type	Summary
overrides	object	Instruct aube to override any dependency in the dependency graph, including peer dependencies.
packageExtensions	object	Extend existing package definitions with additional information.
allowedDeprecatedVersions	object	Mute deprecation warnings for specific package versions.
deprecationWarnings	"none" | "direct" | "all" | "summary"	Scope of deprecation warnings shown during install.
updateConfig.ignoreDependencies	list<string>	List of packages to ignore during update checks.
supportedArchitectures	object	Specify architectures for optional dependency installation.
ignoredOptionalDependencies	list<string>	Skip optional dependencies by name.
pnpmfilePath	string	Location of the pnpmfile hook file.
globalPnpmfile	string	Path to a second pnpmfile that runs before the project's pnpmfile.
minimumReleaseAge	int	Delay installation of newly published versions (minutes).
minimumReleaseAgeExclude	list<string>	Packages exempt from the minimumReleaseAge requirement.
minimumReleaseAgeStrict	bool	Fail the install when no version satisfies the minimumReleaseAge cutoff.
securityScanner	string	Bun-compatible security scanner module.
advisoryCheck	"on" | "required" | "off"	OSV MAL-* advisory check during aube add and other fresh-resolution installs.
advisoryCheckOnInstall	"on" | "required" | "off"	Local-mirror OSV MAL-* advisory check for plain reinstalls.
advisoryBloomCheck	"on" | "required" | "off"	Bloom-filter prefilter for OSV MAL-* advisories on lockfile-driven installs.
advisoryCheckEveryInstall	bool	Force the live-API OSV MAL-* check on every install (including frozen reinstalls).
lowDownloadThreshold	int	Weekly-download floor for aube add (typosquat prompt).
allowedUnpopularPackages	list<string>	Glob patterns exempted from the lowDownloadThreshold gate.
paranoid	bool	Turn on the strict-security setting bundle in one switch.
trustPolicy	"no-downgrade" | "off"	Fail install when a package's trust evidence weakens between releases.
trustPolicyExclude	list<string>	Packages exempt from trustPolicy checks.
trustPolicyIgnoreAfter	int	Skip the trust check for versions older than this many minutes.
blockExoticSubdeps	bool	Restrict transitive dependencies to trusted sources (registries, not git/tarball URLs).
registries	object	Registry URLs, including scoped registry overrides.
hoist	bool	Hoist all dependencies to the hidden modules directory.
hoistWorkspacePackages	bool	Symlink workspace packages into node_modules.
hoistingLimits	"none" | "workspaces" | "dependencies"	Limit how far dependencies are hoisted in nodeLinker=hoisted installs.
hoistPattern	list<string>	Packages to hoist to the hidden modules directory.
publicHoistPattern	list<string>	Packages to hoist directly to the root node_modules.
shamefullyHoist	bool	Hoist all dependencies to the root node_modules (shortcut for publicHoistPattern=["*"]).
modulesDir	path	Directory to install dependencies into.
nodeLinker	"isolated" | "hoisted" | "pnp"	Strategy for linking Node packages into node_modules.
symlink	bool	Create symlinks in the virtual store directory.
enableModulesDir	bool	Write files to the modules directory.
virtualStoreDir	path	Directory with links to the store.
virtualStoreDirMaxLength	int	Max length for virtual store directory names.
virtualStoreOnly	bool	Populate the virtual store without creating top-level symlinks.
packageImportMethod	"auto" | "hardlink" | "copy" | "clone" | "clone-or-copy"	Method for importing packages from the store into node_modules.
modulesCacheMaxAge	int	Minutes before orphan packages are removed from the virtual store.
dlxCacheMaxAge	int	Minutes before the dlx cache is considered stale.
enableGlobalVirtualStore	bool	Use a per-user virtual store for all projects.
disableGlobalVirtualStoreForPackages	list<string>	Package names whose presence in any importer forces per-project materialization.
storeDir	path	Location where packages are saved on disk (content-addressable store).
verifyStoreIntegrity	bool	Check store file integrity before linking.
strictStoreIntegrity	bool	Fail the install when a packument ships no dist.integrity.
useRunningStoreServer	bool	Only allow installs when the store server is running.
strictStorePkgContentCheck	bool	Validate package names and versions in the store.
httpsProxy	url	Proxy URL for outgoing HTTPS requests.
httpProxy	url	Proxy URL for outgoing HTTP requests.
noProxy	string	Comma-separated list of domains that bypass the proxy.
localAddress	string	Local interface IP address to bind registry connections to.
maxsockets	int	Maximum concurrent connections per origin.
strictSsl	bool	Validate SSL certificates for HTTPS requests.
lockfile	bool	Read and generate aube-lock.yaml.
lockfileDir	path	Directory the lockfile is written to and read from.
preferFrozenLockfile	bool	Perform a headless install if the lockfile already satisfies package.json.
lockfileIncludeTarballUrl	bool	Add the full tarball URL to each lockfile entry.
excludeLinksFromLockfile	bool	Skip local link: dependencies when writing the lockfile.
gitBranchLockfile	bool	Generate branch-specific lockfile names (aube-lock.<branch>.yaml).
mergeGitBranchLockfilesBranchPattern	list<string>	Branch-name glob list for auto-merging branch lockfiles.
sharedWorkspaceLockfile	bool	Write one lockfile per workspace package instead of a single shared root lockfile.
peersSuffixMaxLength	int	Max length of the peer-ID suffix in lockfile dep_paths.
gitShallowHosts	list<string>	Hosts for which aube performs shallow git clones.
networkConcurrency	int	Maximum concurrent HTTP(S) requests.
fetchRetries	int	Number of retry attempts for failed registry fetches.
fetchRetryFactor	int	Exponential backoff factor for fetch retries.
fetchRetryMintimeout	int	Minimum retry timeout in milliseconds.
fetchRetryMaxtimeout	int	Maximum retry timeout in milliseconds.
fetchTimeout	int	Max time (ms) to wait for an HTTP request.
fetchWarnTimeoutMs	int	Warn if a metadata request exceeds this threshold (ms).
fetchMinSpeedKiBps	int	Warn if download speed falls below this threshold (KiB/s).
packumentMaxBytes	int	Hard cap on a packument response body size in bytes.
tarballMaxBytes	int	Hard cap on a tarball response body size in bytes (on-wire, still compressed).
autoInstallPeers	bool	Automatically install missing peer dependencies.
dedupePeerDependents	bool	Deduplicate packages that have peer dependencies.
dedupePeers	bool	Use version-only identifiers for peer suffixes in the lockfile.
strictPeerDependencies	bool	Fail if peer dependencies are missing or invalid.
resolvePeersFromWorkspaceRoot	bool	Use root workspace dependencies for peer resolution.
peerDependencyRules.ignoreMissing	list<string>	Suppress warnings for specific missing peer dependencies.
peerDependencyRules.allowedVersions	object	Override the accepted semver range for specific peer dependencies.
peerDependencyRules.allowAny	list<string>	Allow any peer version to resolve, bypassing semver checks.
color	"auto" | "always" | "never"	Control color output in aube's CLI.
loglevel	"debug" | "info" | "warn" | "error" | "silent"	Minimum log level to display.
useBetaCli	bool	Opt into experimental CLI features.
recursiveInstall	bool	Install on all workspace packages by default.
engineStrict	bool	Fail if a package is incompatible with the current Node version.
npmPath	path	Path to the npm binary aube should shell out to when needed.
packageManagerStrict	"off" | "warn" | "error" | true | false	Enforce the packageManager field in package.json (off | warn | error).
packageManagerStrictVersion	bool	Enforce the exact packageManager version from package.json.
managePackageManagerVersions	bool	Auto-download the specified pnpm version when mismatched.
ignoreScripts	bool	Skip all lifecycle scripts in package.json.
childConcurrency	int	Maximum number of concurrent script-executing child processes.
sideEffectsCache	bool	Cache the results of install hooks.
sideEffectsCacheReadonly	bool	Only read from the side-effects cache; don't write.
jailBuilds	bool	Run approved dependency lifecycle scripts in a restricted build jail.
jailBuildExclusions	list<string>	Exclude specific dependency packages from jailed builds.
jailBuildPermissions	object	Grant package-specific privileges inside jailed builds.
unsafePerm	bool	Drop to a non-root user when running scripts as root.
nodeOptions	string	Options passed to Node.js via NODE_OPTIONS.
verifyDepsBeforeRun	"install" | "warn" | "error" | "prompt" | false	Check dependencies before running scripts.
strictDepBuilds	bool	Exit with an error if dependencies have unreviewed build scripts.
allowBuilds	object	Explicitly allow or disallow script execution per package.
dangerouslyAllowAllBuilds	bool	Allow all dependency build scripts automatically.
nodeVersion	string	Node.js version aube reports when evaluating engines checks.
nodeDownloadMirrors	object	Custom Node.js download mirror URLs.
savePrefix	"^" | "~" | ""	Version prefix used when installing a package.
linkWorkspacePackages	"false" | "true" | "deep"	Resolve aube add &lt;name&gt; against local workspace siblings before falling back to the registry.
saveWorkspaceProtocol	"true" | "false" | "rolling"	Spec form written to package.json when aube add resolves against a workspace sibling.
tag	string	Default dist-tag used by aube add without a version.
globalDir	path	Directory where globally installed packages live.
globalBinDir	path	Directory where global binaries are symlinked.
npmrcAuthFile	path	Path to an additional .npmrc file consulted for registry authentication tokens.
stateDir	path	Directory for aube install-state files.
cacheDir	path	Directory for package metadata and dlx cache.
useStderr	bool	Write all output to stderr instead of stdout.
updateNotifier	bool	Show an update notification when a newer aube is available.
updateRewritesSpecifier	bool	Rewrite caret/tilde manifest specifiers on aube update without --latest.
preferSymlinkedExecutables	bool	Create symlinks instead of shims for .bin entries.
ignoreCompatibilityDb	bool	Disable pnpm's automatic dependency patching database.
resolutionMode	"highest" | "time-based" | "lowest-direct"	Dependency version resolution strategy.
registrySupportsTimeField	bool	Whether the configured registry returns a time field in metadata.
forceMetadataPrimer	bool	Force the bundled metadata primer on for custom registries.
extendNodePath	bool	Set NODE_PATH in command shims.
deployAllFiles	bool	Copy all files when deploying a workspace package.
dedupeDirectDeps	bool	Skip symlinking workspace-root dependencies if identical across packages.
optimisticRepeatInstall	bool	Fast-path check before running a full install.
requiredScripts	list<string>	Scripts that must be present in every workspace project.
enablePrePostScripts	bool	Run pre/post scripts automatically when a named script is invoked.
scriptShell	path	Shell used to invoke package scripts.
shellEmulator	bool	Use a JavaScript bash-like shell to run scripts cross-platform.
catalogMode	"manual" | "strict" | "prefer"	How catalog references in package.json are handled by add.
ci	bool	Explicitly mark the environment as CI.
cleanupUnusedCatalogs	bool	Remove unused catalog entries during install.
linkConcurrency	int	Maximum concurrent package materialization/linking tasks.
aubeNoLock	bool	Disable aube's project-level advisory lock.
aubeNoAutoInstall	bool	Skip the auto-install staleness check in aube run / aube exec.

Dependency Resolution

overrides

Instruct aube to override any dependency in the dependency graph, including peer dependencies.

• Type: object
• Default: undefined
• .npmrc keys: overrides
• Workspace YAML keys: overrides

A root-level map of package specs to the versions aube should force them to, regardless of what any package's dependencies field requests. The $ prefix references a direct dep's declared version; a - value removes the dependency from the graph entirely.

packageExtensions

Extend existing package definitions with additional information.

• Type: object
• Default: undefined
• .npmrc keys: packageExtensions, package-extensions
• Workspace YAML keys: packageExtensions

Patches a package's dependencies, peerDependencies, etc. at resolve time. Used to work around upstream packages that forget to declare their real peer requirements.

allowedDeprecatedVersions

Mute deprecation warnings for specific package versions.

• Type: object
• Default: undefined
• .npmrc keys: allowedDeprecatedVersions, allowed-deprecated-versions
• Workspace YAML keys: allowedDeprecatedVersions

Maps a package name to a semver range for which the deprecation warning should be suppressed. Useful when a deprecated version is still pinned deep in the dep graph and there's no upgrade path yet.

deprecationWarnings

Scope of deprecation warnings shown during install.

• Type: "none" | "direct" | "all" | "summary"
• Default: "direct"
• CLI flags: --deprecation-warnings
• Environment: npm_config_deprecation_warnings, NPM_CONFIG_DEPRECATION_WARNINGS, AUBE_DEPRECATION_WARNINGS
• .npmrc keys: deprecationWarnings, deprecation-warnings
• Workspace YAML keys: deprecationWarnings

Controls how deprecation messages surface at the end of install:

• none: silent.
• direct: print full warnings for direct dependencies only, plus a one-line transitive count (default).
• all: print full warnings for every deprecated package (pnpm/npm parity).
• summary: print a single count line covering direct + transitive.

Run aube deprecations to see the full list any time after install.

Examples:

• AUBE_DEPRECATION_WARNINGS=all aube install
• aube install --deprecation-warnings=summary

updateConfig.ignoreDependencies

List of packages to ignore during update checks.

• Type: list<string>
• Default: undefined
• Environment: npm_config_update_config_ignore_dependencies, NPM_CONFIG_UPDATE_CONFIG_IGNORE_DEPENDENCIES, AUBE_UPDATE_CONFIG_IGNORE_DEPENDENCIES
• .npmrc keys: updateConfig.ignoreDependencies, update-config.ignore-dependencies
• Workspace YAML keys: updateConfig.ignoreDependencies

Packages in this list are never bumped by aube update, even when a newer version matching their range exists.

supportedArchitectures

Specify architectures for optional dependency installation.

• Type: object
• Default: undefined
• .npmrc keys: supportedArchitectures, supported-architectures
• Workspace YAML keys: supportedArchitectures

Override the current platform/arch/libc triple used to filter optional dependencies. Useful when generating a lockfile for a target platform different from the host.

ignoredOptionalDependencies

Skip optional dependencies by name.

• Type: list<string>
• Default: undefined
• Environment: npm_config_ignored_optional_dependencies, NPM_CONFIG_IGNORED_OPTIONAL_DEPENDENCIES, AUBE_IGNORED_OPTIONAL_DEPENDENCIES
• .npmrc keys: ignoredOptionalDependencies, ignored-optional-dependencies
• Workspace YAML keys: ignoredOptionalDependencies

Named entries are skipped even if their platform/arch matches. Distinct from --no-optional, which drops all optional deps at install time.

pnpmfilePath

Location of the pnpmfile hook file.

• Type: string
• Default: undefined
• CLI flags: --pnpmfile
• Environment: AUBE_PNPMFILE_PATH
• Workspace YAML keys: pnpmfilePath

Override for the pnpmfile discovery path. Defaults to <project>/.pnpmfile.mjs when present, otherwise <project>/.pnpmfile.cjs. Relative paths resolve against the project root; absolute paths are used as-is. A path that points at a missing file is a hard miss — aube emits a warning and runs with no pnpmfile rather than silently falling back to the default.

--pnpmfile <path> mirrors pnpm's CLI flag and takes precedence over the workspace yaml entry.

Examples:

• aube install --pnpmfile config/hooks.cjs

globalPnpmfile

Path to a second pnpmfile that runs before the project's pnpmfile.

• Type: string
• Default: undefined
• CLI flags: --global-pnpmfile
• Environment: AUBE_GLOBAL_PNPMFILE

Mirrors pnpm's --global-pnpmfile <path>. The global hook runs first and the local pnpmfile (if any) runs second, so per-project hooks can override org-wide rules. Relative paths resolve against the project root; absolute paths are used as-is. A typo (target missing) is a hard miss with a warning rather than a silent skip.

Examples:

• aube install --global-pnpmfile ~/.config/aube/hooks.cjs

minimumReleaseAge

Delay installation of newly published versions (minutes).

• Type: int
• Default: 1440
• Environment: npm_config_minimum_release_age, NPM_CONFIG_MINIMUM_RELEASE_AGE, AUBE_MINIMUM_RELEASE_AGE
• .npmrc keys: minimumReleaseAge, minimum-release-age
• Workspace YAML keys: minimumReleaseAge

Supply-chain attack mitigation: packages published within the last N minutes are skipped by the resolver. By default the resolver falls back to the next-oldest version that satisfies the range; set minimumReleaseAgeStrict=true to fail the install instead. Defaults to 24 hours, matching pnpm v11. Set to 0 to disable.

minimumReleaseAgeExclude

Packages exempt from the minimumReleaseAge requirement.

• Type: list<string>
• Default: undefined
• Environment: npm_config_minimum_release_age_exclude, NPM_CONFIG_MINIMUM_RELEASE_AGE_EXCLUDE, AUBE_MINIMUM_RELEASE_AGE_EXCLUDE
• .npmrc keys: minimumReleaseAgeExclude, minimum-release-age-exclude
• Workspace YAML keys: minimumReleaseAgeExclude

Use for trusted internal packages that need to be rolled out immediately without waiting for the age gate. pnpm audit --fix (when implemented) will append patched versions to this list automatically.

minimumReleaseAgeStrict

Fail the install when no version satisfies the minimumReleaseAge cutoff.

• Type: bool
• Default: false
• Environment: npm_config_minimum_release_age_strict, NPM_CONFIG_MINIMUM_RELEASE_AGE_STRICT, AUBE_MINIMUM_RELEASE_AGE_STRICT
• .npmrc keys: minimumReleaseAgeStrict, minimum-release-age-strict
• Workspace YAML keys: minimumReleaseAgeStrict

By default the resolver falls back to the lowest satisfying version when every candidate is younger than minimumReleaseAge. With this set, the resolver fails the install instead.

securityScanner

Bun-compatible security scanner module.

• Type: string
• Default: ""
• Environment: npm_config_security_scanner, NPM_CONFIG_SECURITY_SCANNER, AUBE_SECURITY_SCANNER
• .npmrc keys: securityScanner, security-scanner
• Workspace YAML keys: securityScanner

Path (or bare npm package name) of a Bun-compatible security scanner module. Aube loads it through a node bridge that adapts Bun's in-process plugin contract to a subprocess.

# aube-workspace.yaml
securityScanner: "@acme/bun-security-scanner"

Empty string (the default) disables the integration. Requires Node 22.6+. Fails closed on any scanner failure.

Full reference, including the Bun-runtime API surface aube shims, authoring instructions, and the post-resolve firing model: /package-manager/security-scanner.

advisoryCheck

OSV MAL-* advisory check during aube add and other fresh-resolution installs.

• Type: "on" | "required" | "off"
• Default: "on"
• Environment: npm_config_advisory_check, NPM_CONFIG_ADVISORY_CHECK, AUBE_ADVISORY_CHECK
• .npmrc keys: advisoryCheck, advisory-check
• Workspace YAML keys: advisoryCheck

Live-API OSV MAL-* advisory check. aube batch-queries OSV at three points, all against api.osv.dev:

1. aube add CLI names, before they land in package.json.
2. The full post-resolve transitive graph during any fresh-resolution install — aube add, aube update, an install with no lockfile, or an install where the resolver picked a (name, version) the lockfile didn't already pin.
3. Every install (including frozen reinstalls), if advisoryCheckEveryInstall is true.

A hit at any step fails the install with ERR_AUBE_MALICIOUS_PACKAGE and a link to the advisory.

Plain reinstalls where the lockfile was authoritative don't hit the network here — they fall through to the local mirror (see advisoryCheckOnInstall) when that's enabled, or no OSV check at all when it isn't.

• on (default): fail closed on a malicious-package hit; fail open (continue with a WARN_AUBE_ADVISORY_CHECK_FAILED) when the API can't be reached, so offline workflows aren't blocked.
• required: same fail-closed behavior on hits, plus fail closed on fetch errors. Use in hardened CI. Included in the paranoid bundle.
• off: skip the check entirely.

advisoryCheckOnInstall

Local-mirror OSV MAL-* advisory check for plain reinstalls.

• Type: "on" | "required" | "off"
• Default: "off"
• Environment: npm_config_advisory_check_on_install, NPM_CONFIG_ADVISORY_CHECK_ON_INSTALL, AUBE_ADVISORY_CHECK_ON_INSTALL
• .npmrc keys: advisoryCheckOnInstall, advisory-check-on-install
• Workspace YAML keys: advisoryCheckOnInstall

Fallback OSV MAL-* check for installs the live-API gate (advisoryCheck) didn't fire for — i.e. plain reinstalls where the lockfile was authoritative (no aube add / aube update, no advisoryCheckEveryInstall, no lockfile drift). Backed by a local mirror of OSV's npm advisory dump so there's no per-install api.osv.dev round-trip.

A hit fails the install with ERR_AUBE_MALICIOUS_PACKAGE — same exit as advisoryCheck. Fresh-resolution installs (aube add, aube update, missing-lockfile, new picked version) always go through the live API regardless of this setting, so the freshest signal lands at the moment a human is changing what's installed.

The mirror lives at $XDG_CACHE_HOME/aube/osv/npm/ and lazily refreshes from https://osv-vulnerabilities.storage.googleapis.com/npm/all.zip (roughly tens of MB) with an If-None-Match revalidation. A miss between refreshes won't catch an advisory published in the last ~day; for live signals on every install, use advisoryCheckEveryInstall = true instead.

• off (default): plain reinstalls skip OSV entirely. Fresh-resolution installs still hit the live API via advisoryCheck.
• on: plain reinstalls check the resolved graph against the mirror. Fail open (continue with WARN_AUBE_OSV_MIRROR_REFRESH_FAILED) when the mirror can't be refreshed.
• required: as on, plus fail closed on mirror refresh failures with ERR_AUBE_ADVISORY_CHECK_FAILED. Use in hardened CI where a stale or unreachable mirror should block the install.

advisoryBloomCheck

Bloom-filter prefilter for OSV MAL-* advisories on lockfile-driven installs.

• Type: "on" | "required" | "off"
• Default: "off"
• Environment: npm_config_advisory_bloom_check, NPM_CONFIG_ADVISORY_BLOOM_CHECK, AUBE_ADVISORY_BLOOM_CHECK
• .npmrc keys: advisoryBloomCheck, advisory-bloom-check
• Workspace YAML keys: advisoryBloomCheck

Fast bloom-filter prefilter that aube downloads (~380 KB) from endevco/osv-bloom. The upstream filter contains one entry per (npm package name, semver major bucket) pair drawn from OSV's malicious-package archive and is regenerated every 10 minutes.

When enabled, aube probes the resolved transitive graph against the filter and escalates only the bloom hits to the live OSV API for exact (name, version) confirmation. Bloom false-positive rate is ~0.1%, so a typical lockfile of ~1000 packages either triggers no escalation at all or one extra live-API round trip per install — much cheaper than advisoryCheckEveryInstall which round-trips the full graph.

Designed to coexist with advisoryCheck and advisoryCheckOnInstall rather than replace them. The bloom check fires on every install path the live-API gate didn't already cover for that install: if advisoryCheckEveryInstall = true or the install is a fresh-resolution path that already hits the live API, the bloom is skipped (the live API strictly dominates a bloom probe).

• off (default): bloom prefilter disabled.
• on: probe the lockfile against the bloom, escalate hits to the live API, fail closed on a confirmed MAL-* hit with ERR_AUBE_MALICIOUS_PACKAGE. Fail open (continue with WARN_AUBE_OSV_BLOOM_REFRESH_FAILED) when the bloom can't be refreshed.
• required: as on, plus fail closed on bloom refresh failures with ERR_AUBE_ADVISORY_CHECK_FAILED. Use in hardened CI where a stale or unreachable bloom should block the install.

advisoryCheckEveryInstall

Force the live-API OSV MAL-* check on every install (including frozen reinstalls).

• Type: bool
• Default: false
• Environment: npm_config_advisory_check_every_install, NPM_CONFIG_ADVISORY_CHECK_EVERY_INSTALL, AUBE_ADVISORY_CHECK_EVERY_INSTALL
• .npmrc keys: advisoryCheckEveryInstall, advisory-check-every-install
• Workspace YAML keys: advisoryCheckEveryInstall

By default, the live-API OSV check (advisoryCheck) fires on fresh-resolution installs only — aube add, aube update, missing-lockfile installs, and installs where the resolver picks a version the lockfile didn't pin. Plain reinstalls fall through to the local mirror (advisoryCheckOnInstall) when that's enabled.

Setting advisoryCheckEveryInstall = true forces the live API on every install entry point, including strict frozen reinstalls and aube ci. Every install round-trips through api.osv.dev for the freshest signal; mirror lookups are skipped because the live API strictly dominates.

Useful in hardened CI where every job must observe the latest advisories regardless of whether the lockfile changed. The trade-off is per-install latency — for a large transitive graph, batch queries chunk at 500 names per request, so an aube install against a graph of 2000 packages incurs four sequential OSV requests.

• false (default): live-API check on fresh-resolution installs only.
• true: live-API check on every install. Honors advisoryCheck's fail-open / fail-closed policy on fetch errors.

lowDownloadThreshold

Weekly-download floor for aube add (typosquat prompt).

• Type: int
• Default: 1000
• Environment: npm_config_low_download_threshold, NPM_CONFIG_LOW_DOWNLOAD_THRESHOLD, AUBE_LOW_DOWNLOAD_THRESHOLD
• .npmrc keys: lowDownloadThreshold, low-download-threshold
• Workspace YAML keys: lowDownloadThreshold

aube add looks up each candidate's weekly download count via api.npmjs.org/downloads/point/last-week/<pkg> and prompts for confirmation when the count falls below this threshold — the floor catches typosquats and impersonations, which have near-zero downloads on day one regardless of how cleverly they're named.

Interactive sessions get a [y/N] prompt showing the weekly download count. Non-interactive contexts fail with ERR_AUBE_LOW_DOWNLOAD_PACKAGE unless --allow-low-downloads is passed.

Packages that route through a non-registry.npmjs.org registry are skipped automatically: a scoped override like @myorg:registry=https://npm.internal.example/ or a swapped-out default registry both mean npmjs has no signal on the package, so neither the downloads gate nor the OSV MAL-* check fires. Workspace deps and git/local specs are also skipped. To exempt specific names that do resolve through npmjs (e.g. you publish a low-download but trusted package internally), see allowedUnpopularPackages.

Set to 0 to disable.

allowedUnpopularPackages

Glob patterns exempted from the lowDownloadThreshold gate.

• Type: list<string>
• Default: undefined
• Environment: npm_config_allowed_unpopular_packages, NPM_CONFIG_ALLOWED_UNPOPULAR_PACKAGES, AUBE_ALLOWED_UNPOPULAR_PACKAGES
• .npmrc keys: allowedUnpopularPackages, allowed-unpopular-packages
• Workspace YAML keys: allowedUnpopularPackages

Each pattern is matched against the registry name (@scope/foo or bar) of every candidate the lowDownloadThreshold gate would otherwise probe. Matches skip the weekly-downloads lookup entirely, so internal/low-traffic packages don't trip the prompt in CI or the y/N prompt locally.

Patterns are full-name globs (the glob crate's syntax — *, ?, […]). Match-everything (*) is allowed but defeats the gate; prefer to set lowDownloadThreshold = 0 if that is what you want.

The OSV MAL-* advisory check (advisoryCheck) is not affected — a hit there is confirmed-malicious and not the kind of judgement call this list is meant to suppress.

# aube-workspace.yaml
allowedUnpopularPackages:
  - "@mycompany/*"
  - "internal-*"

paranoid

Turn on the strict-security setting bundle in one switch.

• Type: bool
• Default: false
• Environment: npm_config_paranoid, NPM_CONFIG_PARANOID, AUBE_PARANOID
• .npmrc keys: paranoid
• Workspace YAML keys: paranoid

When true, aube forces every individual setting in the strict-security bundle on, regardless of how each is configured individually:

• trustPolicy = no-downgrade (overrides explicit off)
• jailBuilds = true
• minimumReleaseAgeStrict = true (makes the age gate hard, not advisory)
• strictStoreIntegrity = true (fail on missing dist.integrity)
• strictDepBuilds = true (fail when deps have unreviewed build scripts)
• advisoryCheck = required (fail closed on OSV fetch errors instead of falling through with a warning)

Set to false (the default) to honor the underlying settings as-is.

trustPolicy

Fail install when a package's trust evidence weakens between releases.

• Type: "no-downgrade" | "off"
• Default: "no-downgrade"
• Environment: npm_config_trust_policy, NPM_CONFIG_TRUST_POLICY, AUBE_TRUST_POLICY
• .npmrc keys: trustPolicy, trust-policy
• Workspace YAML keys: trustPolicy

When no-downgrade (the default), aube rejects a version that carries weaker trust evidence than any earlier-published version of the same package. Recognized evidence: npm staged-publish approval metadata (approver) outranks structured npm trusted-publisher metadata (_npmUser.trustedPublisher.id), which outranks structured SLSA provenance metadata (dist.attestations.provenance.predicateType). Set to off to disable, or use trustPolicyExclude to whitelist specific packages or versions. This policy validates registry metadata shape; it does not cryptographically verify the attached attestation bundle.

trustPolicyExclude

Packages exempt from trustPolicy checks.

• Type: list<string>
• Default: []
• Environment: npm_config_trust_policy_exclude, NPM_CONFIG_TRUST_POLICY_EXCLUDE, AUBE_TRUST_POLICY_EXCLUDE
• .npmrc keys: trustPolicyExclude, trust-policy-exclude
• Workspace YAML keys: trustPolicyExclude

Patterns: name, [email protected], [email protected] || 1.0.1 (exact versions only — no ^/~/>=), is-* (name glob, no version), @scope/[email protected]. Empty list disables user-provided exclusions; aube still applies its built-in exclusions for known registry provenance metadata churn.

trustPolicyIgnoreAfter

Skip the trust check for versions older than this many minutes.

• Type: int
• Default: undefined
• Environment: npm_config_trust_policy_ignore_after, NPM_CONFIG_TRUST_POLICY_IGNORE_AFTER, AUBE_TRUST_POLICY_IGNORE_AFTER
• .npmrc keys: trustPolicyIgnoreAfter, trust-policy-ignore-after
• Workspace YAML keys: trustPolicyIgnoreAfter

Versions whose publish time is older than the cutoff are exempted from trustPolicy. Leave unset to apply the check to every version.

blockExoticSubdeps

Restrict transitive dependencies to trusted sources (registries, not git/tarball URLs).

• Type: bool
• Default: true
• Environment: npm_config_block_exotic_subdeps, NPM_CONFIG_BLOCK_EXOTIC_SUBDEPS, AUBE_BLOCK_EXOTIC_SUBDEPS
• .npmrc keys: blockExoticSubdeps, block-exotic-subdeps
• Workspace YAML keys: blockExoticSubdeps

When true, transitive deps referenced via git+, file:, or direct tarball URLs are rejected. Helps prevent supply-chain attacks via unexpected download sources.

registries

Registry URLs, including scoped registry overrides.

• Type: object
• Default: { default = "https://registry.npmjs.org/" }
• .npmrc keys: registry, @scope:registry, //host/:_authToken, //host/:_auth

Maps default and @scope keys to registry URLs. aube reads these from .npmrc via aube_registry::config::NpmConfig (see crates/aube-registry/src/config.rs). Bearer tokens and basic auth per registry are also parsed from .npmrc.

Examples:

• registry=https://registry.npmmirror.com/
• @mycorp:registry=https://npm.mycorp.internal/

Dependency Hoisting

hoist

Hoist all dependencies to the hidden modules directory.

• Type: bool
• Default: true
• Environment: npm_config_hoist, NPM_CONFIG_HOIST, AUBE_HOIST
• .npmrc keys: hoist
• Workspace YAML keys: hoist

Controls whether aube populates node_modules/.aube/node_modules/ — the hidden hoist tree that lives inside the private virtual store. When enabled (the default), every non-local package whose name matches hoistPattern gets a symlink into that directory so Node's parent-directory walk can satisfy undeclared deps from inside the virtual store (e.g. react-dom reaching scheduler without declaring it).

The hidden tree is distinct from publicHoistPattern / shamefullyHoist, which add symlinks at the visible root node_modules/<name>. Hidden-hoist links are only reachable during Node's resolution of a dependency that itself lives under .aube/<dep_path>/. Setting hoist=false skips the pass entirely and sweeps any previously-populated directory so stale entries don't keep resolving.

Examples:

• echo 'hoist=false' >> .npmrc && aube install

hoistWorkspacePackages

Symlink workspace packages into node_modules.

• Type: bool
• Default: true
• Environment: npm_config_hoist_workspace_packages, NPM_CONFIG_HOIST_WORKSPACE_PACKAGES, AUBE_HOIST_WORKSPACE_PACKAGES
• .npmrc keys: hoist-workspace-packages, hoistWorkspacePackages
• Workspace YAML keys: hoistWorkspacePackages

Controls whether workspace packages get their own symlinks in each importer's node_modules/. When true (the default), every importer gets a node_modules/<ws-pkg> symlink to every workspace package it depends on, matching pnpm. When false, those symlinks are omitted — cross-importer workspace: dependencies still resolve through the lockfile, but a top-level require('<ws-pkg>') from a package that doesn't declare the workspace dep stops working.

hoistingLimits

Limit how far dependencies are hoisted in nodeLinker=hoisted installs.

• Type: "none" | "workspaces" | "dependencies"
• Default: "none"
• Environment: npm_config_hoisting_limits, NPM_CONFIG_HOISTING_LIMITS, AUBE_HOISTING_LIMITS
• .npmrc keys: hoistingLimits, hoisting-limits
• Workspace YAML keys: hoistingLimits

Controls how far packages can be promoted when nodeLinker=hoisted is active, mirroring Yarn's nmHoistingLimits and pnpm's hoistingLimits setting:

• none: hoist as far as possible (default).
• workspaces: hoist only as far as each workspace package. Aube plans hoisted installs per physical importer, so this currently matches none.
• dependencies: hoist only up to each workspace package's direct dependencies. Transitive packages stay under the direct dependency that introduced them instead of being promoted to the importer root.

Ignored by the default isolated linker.

Examples:

• echo 'node-linker=hoisted' >> .npmrc
• echo 'hoisting-limits=dependencies' >> .npmrc

hoistPattern

Packages to hoist to the hidden modules directory.

• Type: list<string>
• Default: ["*"]
• Environment: npm_config_hoist_pattern, NPM_CONFIG_HOIST_PATTERN, AUBE_HOIST_PATTERN
• .npmrc keys: hoist-pattern, hoistPattern
• Workspace YAML keys: hoistPattern

Glob list matched against package names. Any non-local package whose name matches at least one positive pattern (and no !-prefixed negation) gets a symlink at node_modules/.aube/node_modules/<name>. The default * matches everything, which mirrors pnpm's default of hoisting every transitive dep into the hidden tree. Only consulted when hoist=true.

Matching is case-insensitive; first-writer-wins on name clashes across versions, using BTree iteration order for determinism. Set to [] or a list of only ! negations to hoist nothing while leaving hoist=true (equivalent to setting hoist=false).

publicHoistPattern

Packages to hoist directly to the root node_modules.

• Type: list<string>
• Default: []
• CLI flags: public-hoist-pattern
• Environment: npm_config_public_hoist_pattern, NPM_CONFIG_PUBLIC_HOIST_PATTERN, AUBE_PUBLIC_HOIST_PATTERN
• .npmrc keys: public-hoist-pattern, publicHoistPattern
• Workspace YAML keys: publicHoistPattern

Glob list matched against package names. Any non-local package in the resolved graph whose name matches at least one positive pattern (and no !-prefixed negation) gets a top-level node_modules/<name> symlink in addition to the usual direct-dep entries, so frameworks like Next.js, Storybook, and Jest can resolve transitive deps from the project root without adding them to package.json.

Matching is case-insensitive; direct deps always win on name clashes, and the pattern pass runs before shamefullyHoist. Use sparingly -- anything hoisted becomes a phantom dep at the root.

shamefullyHoist

Hoist all dependencies to the root node_modules (shortcut for publicHoistPattern=["*"]).

• Type: bool
• Default: false
• CLI flags: shamefully-hoist
• Environment: npm_config_shamefully_hoist, NPM_CONFIG_SHAMEFULLY_HOIST, AUBE_SHAMEFULLY_HOIST
• .npmrc keys: shamefully-hoist, shamefullyHoist
• Workspace YAML keys: shamefullyHoist

Emulates npm's flat node_modules layout. Enables phantom dep bugs by design — only use as a last-resort compatibility knob.

node_modules

modulesDir

Directory to install dependencies into.

• Type: path
• Default: "node_modules"
• Environment: npm_config_modules_dir, NPM_CONFIG_MODULES_DIR, AUBE_MODULES_DIR
• .npmrc keys: modulesDir, modules-dir
• Workspace YAML keys: modulesDir

The project-level directory that holds the top-level <name> entries the user sees under the project root. Defaults to "node_modules". The linker, bin handler, scripts runner, and every command that touches the project-level directory (bin, root, prune, clean, ci, link, unlink, run, exec, patch, licenses, inject, …) all honor this setting.

The inner virtual-store paths -- <modulesDir>/.aube/<dep>/node_modules/ -- keep the literal node_modules name regardless of this setting. Node.js's own module resolver walks up from <pkg>/src/file.js looking for a literal node_modules/ directory, so a renamed outer directory only works when Node can still find its deps: set NODE_PATH=<project>/<modulesDir> (or use a custom loader) before running node. The inner dir name is what the walk actually hits, so it stays fixed.

nodeLinker

Strategy for linking Node packages into node_modules.

• Type: "isolated" | "hoisted" | "pnp"
• Default: "isolated"
• CLI flags: node-linker
• Environment: npm_config_node_linker, NPM_CONFIG_NODE_LINKER, AUBE_NODE_LINKER
• .npmrc keys: nodeLinker, node-linker
• Workspace YAML keys: nodeLinker

aube defaults to isolated, a strict symlink layout under node_modules/.aube/. hoisted is also supported for projects that need an npm-style flatter node_modules tree with conflicting versions nested under the requiring package. pnp is accepted as a known value but rejected with a clear error because Yarn Plug'n'Play is not supported.

symlink

Create symlinks in the virtual store directory.

• Type: bool
• Default: true
• Environment: npm_config_symlink, NPM_CONFIG_SYMLINK, AUBE_SYMLINK
• .npmrc keys: symlink

Accepted for pnpm parity. aube's isolated layout is structurally defined by the symlink graph under node_modules/.aube/ — each .aube/<dep_path>/node_modules/ contains the real package alongside sibling symlinks that Node's directory walk follows to reach declared deps. Removing those symlinks in favor of hard copies would defeat the isolation guarantee and blow up disk usage by every duplicated transitive.

symlink=true (the default) is a silent no-op — it is what aube already does. symlink=false is accepted so a .npmrc ported from a hard-copy-only pnpm setup keeps loading, but aube emits a single warning at install start and keeps building the symlink graph. Materialized files inside the store are still imported via reflink → hardlink → copy (controlled by packageImportMethod), unaffected by this setting.

Examples:

• echo 'symlink=false' >> .npmrc

enableModulesDir

Write files to the modules directory.

• Type: bool
• Default: true
• Environment: npm_config_enable_modules_dir, NPM_CONFIG_ENABLE_MODULES_DIR, AUBE_ENABLE_MODULES_DIR
• .npmrc keys: enableModulesDir, enable-modules-dir

When false, aube resolves the dependency graph and writes aube-lock.yaml but skips every node_modules/ side effect: no virtual store is populated, no top-level symlinks are created, and the per-project install-state file is not written. Functionally equivalent to --lockfile-only as a persistent .npmrc / aube-workspace.yaml setting, which is how pnpm exposes it.

virtualStoreDir

Directory with links to the store.

• Type: path
• Default: "node_modules/.aube"
• Environment: npm_config_virtual_store_dir, NPM_CONFIG_VIRTUAL_STORE_DIR, AUBE_VIRTUAL_STORE_DIR
• .npmrc keys: virtualStoreDir, virtual-store-dir
• Workspace YAML keys: virtualStoreDir

Relocates the per-project .aube/<dep>/node_modules/ tree that the isolated linker writes into. Relative paths resolve against the project root (~ expands to $HOME).

The generated accessor's declared default is the literal "node_modules/.aube" — but callers should resolve through aube_cli::commands::resolve_virtual_store_dir, which additionally substitutes <modulesDir>/.aube when modulesDir itself has been overridden. That's the "real" effective default and matches pnpm's documented <modulesDir>/.pnpm behavior: a project that renames node_modules/ alone still gets a coherent layout without having to set both.

The linker, engines check, fetch-phase "already linked" fast path, orphan sweep, apply_injected (dependenciesMeta.injected), aube patch (extract source), aube rebuild (dep lifecycle scripts), aube unlink (classify internal symlinks), aube prune (orphan cleanup), and aube licenses (virtual-store manifest read) all consult the setting through that helper.

virtualStoreDirMaxLength

Max length for virtual store directory names.

• Type: int
• Default: 120 (Linux/macOS), 60 (Windows)
• Environment: npm_config_virtual_store_dir_max_length, NPM_CONFIG_VIRTUAL_STORE_DIR_MAX_LENGTH, AUBE_VIRTUAL_STORE_DIR_MAX_LENGTH
• .npmrc keys: virtualStoreDirMaxLength, virtual-store-dir-max-length

Caps the number of characters in a single node_modules/.aube/<dep> directory name. dep_path_to_filename already truncates-and-hashes dep_paths that would otherwise overflow the cap, so lowering this value lets peer-heavy graphs (e.g. ESLint + TypeScript plugin matrices) stay under filesystem NAME_MAX limits on unusual setups (ecryptfs, some CI filesystems). The default is 120 on Linux/macOS and 60 on Windows; aube currently uses the POSIX default on every platform (the Windows tightening lands with native Windows support).

virtualStoreOnly

Populate the virtual store without creating top-level symlinks.

• Type: bool
• Default: false
• Environment: npm_config_virtual_store_only, NPM_CONFIG_VIRTUAL_STORE_ONLY, AUBE_VIRTUAL_STORE_ONLY
• .npmrc keys: virtualStoreOnly, virtual-store-only

When true, aube still materializes every package into node_modules/.aube/<dep>/node_modules/<name> (and, in global-store mode, into the shared virtual store), but skips the final pass that creates the top-level node_modules/<name> symlinks. Useful in CI pipelines that warm the store for downstream jobs and in aube fetch-style flows that want the dep graph on disk without exposing it to Node's resolver. shamefullyHoist and publicHoistPattern hoisting passes are also skipped, since both target the same top-level directory.

packageImportMethod

Method for importing packages from the store into node_modules.

• Type: "auto" | "hardlink" | "copy" | "clone" | "clone-or-copy"
• Default: "auto"
• CLI flags: package-import-method
• Environment: npm_config_package_import_method, NPM_CONFIG_PACKAGE_IMPORT_METHOD, AUBE_PACKAGE_IMPORT_METHOD
• .npmrc keys: packageImportMethod, package-import-method
• Workspace YAML keys: packageImportMethod

Controls how aube materializes files from the global content-addressable store into the virtual store.

• auto (default) probes the destination filesystem and picks hardlink with a copy fallback on cross-filesystem boundaries. Hardlink benchmarks faster than reflink across every target reflink supports (APFS clonefile, btrfs/xfs FICLONE), so auto skips the reflink probe.
• hardlink hard-links from the store, with a copy fallback on cross-filesystem errors.
• copy always writes a full copy.
• clone uses reflink. Currently falls back to copy when reflink is unsupported; strict enforcement is planned for a future release (WARN_AUBE_CLONE_STRATEGY_FALLBACK).
• clone-or-copy tries reflink first and falls back to a plain copy instead of hardlinking.

Overridable per-invocation with --package-import-method.

modulesCacheMaxAge

Minutes before orphan packages are removed from the virtual store.

• Type: int
• Default: 10080
• Environment: npm_config_modules_cache_max_age, NPM_CONFIG_MODULES_CACHE_MAX_AGE, AUBE_MODULES_CACHE_MAX_AGE
• .npmrc keys: modulesCacheMaxAge, modules-cache-max-age

After each successful install, aube sweeps the per-project node_modules/.aube/ virtual store and removes entries whose directory mtime is older than this threshold AND that the just-run install did not touch. The mtime is refreshed every time the linker visits an entry (including the cached-fast-path branches), so entries still in use are effectively immortal. Default is 7 days (10 080 minutes). Set to 0 to disable the sweep entirely. The sweep only touches per-project entries; the shared global virtual store under ~/.cache/aube/virtual-store/ is managed separately by aube store prune.

dlxCacheMaxAge

Minutes before the dlx cache is considered stale.

• Type: int
• Default: 1440
• Environment: npm_config_dlx_cache_max_age, NPM_CONFIG_DLX_CACHE_MAX_AGE, AUBE_DLX_CACHE_MAX_AGE
• .npmrc keys: dlx-cache-max-age, dlxCacheMaxAge

Accepted for pnpm parity. aube dlx currently installs into a fresh tempfile::TempDir per invocation and removes it on exit, so there is no persistent dlx cache to expire — the configured value is read and validated, but no eviction runs against it. If aube grows a persistent dlx cache later, this setting will gate its TTL without any further config-surface change.

enableGlobalVirtualStore

Use a per-user virtual store for all projects.

• Type: bool
• Default: undefined
• CLI flags: enable-global-virtual-store, disable-global-virtual-store
• Environment: npm_config_enable_global_virtual_store, NPM_CONFIG_ENABLE_GLOBAL_VIRTUAL_STORE, AUBE_ENABLE_GLOBAL_VIRTUAL_STORE
• .npmrc keys: enableGlobalVirtualStore, enable-global-virtual-store
• Workspace YAML keys: enableGlobalVirtualStore

aube ships its own global virtual store under ~/.cache/aube/virtual-store/. It's enabled by default outside CI and disabled under CI (see aube-linker, which checks the CI env var). Set enableGlobalVirtualStore=false in .npmrc or pnpm-workspace.yaml to force per-project materialization for a project.

aube dlx defaults this setting to false for its scratch installs so CLIs with undeclared runtime imports can still use the hidden-hoist fallback inside the temporary project. Pass aube dlx --enable-gvs <pkg> when you want to force the shared virtual store on for a dlx invocation.

The global flags are one-shot CLI sources for the same setting: --disable-global-virtual-store resolves this setting to false, and --enable-global-virtual-store resolves it to true. The enable flag can force the shared virtual store on even in CI or when package compatibility heuristics would normally disable it.

Examples:

• echo 'enableGlobalVirtualStore=false' >> .npmrc
• aube --disable-global-virtual-store install
• aube dlx --enable-gvs create-vite

disableGlobalVirtualStoreForPackages

Package names whose presence in any importer forces per-project materialization.

• Type: list<string>
• Default: ["next", "nuxt", "vite", "vitepress", "parcel"]
• Environment: npm_config_disable_global_virtual_store_for_packages, NPM_CONFIG_DISABLE_GLOBAL_VIRTUAL_STORE_FOR_PACKAGES, AUBE_DISABLE_GLOBAL_VIRTUAL_STORE_FOR_PACKAGES
• .npmrc keys: disableGlobalVirtualStoreForPackages, disable-global-virtual-store-for-packages
• Workspace YAML keys: disableGlobalVirtualStoreForPackages

aube's global virtual store makes node_modules/.aube/<pkg> an absolute symlink into ~/.cache/aube/virtual-store/. Tools whose module resolvers follow symlinks to real paths and then walk up the directory tree can't reach the project's node_modules/ from inside the global store and produce errors like Symlink ... is invalid, it points out of the filesystem root.

When aube install finds one of these names in any importer's dependencies, devDependencies, or optionalDependencies, it forces per-project materialization for that install and prints a one-line warning naming the trigger.

The default list — next, nuxt, vite, vitepress, parcel — covers the tools with concrete walk-up failures: Next.js's Turbopack canonicalizes through symlinks and walks up for app-router/monorepo detection, Vite/VitePress/Nuxt plugins walk up for config discovery (see jdx/mise#9261 for the VitePress case), and Parcel's resolver walks up for .parcelrc. Webpack and Rollup are not on the default list: plain Webpack resolves via the sibling symlinks aube already places inside .aube/<pkg>/node_modules/, and Rollup is rarely a direct dep (it's typically transitive of Vite). Add them back here if a specific plugin needs the fallback, or set the list to [] to disable the heuristic entirely. CI=1 already forces per-project mode, so the warning suppresses itself in that case.

Store

storeDir

Location where packages are saved on disk (content-addressable store).

• Type: path
• Default: $XDG_DATA_HOME/aube/store/
• Environment: npm_config_store_dir, NPM_CONFIG_STORE_DIR, AUBE_STORE_DIR
• .npmrc keys: store-dir, storeDir
• Workspace YAML keys: storeDir

Defaults to aube's own XDG-compliant store path ($XDG_DATA_HOME/aube/store/, falling back to ~/.local/share/aube/store/). aube does not read from or write to pnpm's ~/.pnpm-store/. Set in .npmrc or aube-workspace.yaml to point at a different directory, which is useful for isolating CI runners, putting the store on a faster disk, or sharing one store across multiple users on the same host.

Path interpretation matches pnpm: ~ expands to the user's home directory and a relative path is resolved against the project root, not the current working directory. aube appends its own schema suffix (v1) to the user-supplied directory, so store-dir=/srv/aube-store stores package content under /srv/aube-store/v1/. Run aube store path to print the resolved store location.

Examples:

• echo 'store-dir=/srv/aube-store' >> .npmrc && aube install

verifyStoreIntegrity

Check store file integrity before linking.

• Type: bool
• Default: true
• CLI flags: verify-store-integrity
• Environment: npm_config_verify_store_integrity, NPM_CONFIG_VERIFY_STORE_INTEGRITY, AUBE_VERIFY_STORE_INTEGRITY
• .npmrc keys: verify-store-integrity, verifyStoreIntegrity
• Workspace YAML keys: verifyStoreIntegrity

aube verifies each package's SRI integrity (sha512, or legacy sha1/sha256/sha384) against the tarball bytes at import time in aube_store::verify_integrity, before extraction. Set to false via .npmrc, env, or --no-verify-store-integrity to skip the check — useful in trusted CI environments where the registry is already known-good and the tarball bytes have been vetted upstream.

Examples:

• aube install --no-verify-store-integrity
• echo 'verify-store-integrity=false' >> .npmrc

strictStoreIntegrity

Fail the install when a packument ships no dist.integrity.

• Type: bool
• Default: false
• CLI flags: strict-store-integrity
• Environment: npm_config_strict_store_integrity, NPM_CONFIG_STRICT_STORE_INTEGRITY, AUBE_STRICT_STORE_INTEGRITY
• .npmrc keys: strict-store-integrity, strictStoreIntegrity
• Workspace YAML keys: strictStoreIntegrity

Companion to verifyStoreIntegrity. When both are true and a packument comes back without a dist.integrity field, aube refuses to import the tarball rather than warning and continuing. Matches the behavior a security-conscious operator wants when a registry proxy or MITM has stripped the integrity field from an in-flight packument. Defaults to false for ecosystem parity with pnpm (which only warns), but is the recommended setting on production CI.

Examples:

• echo 'strict-store-integrity=true' >> .npmrc

useRunningStoreServer

Only allow installs when the store server is running.

• Type: bool
• Default: false
• Environment: npm_config_use_running_store_server, NPM_CONFIG_USE_RUNNING_STORE_SERVER, AUBE_USE_RUNNING_STORE_SERVER
• .npmrc keys: use-running-store-server, useRunningStoreServer

Accepted for pnpm parity. aube has no long-running store-daemon component — every install talks directly to the on-disk CAS at storeDir. Setting this to true does not fail the install; aube emits a single warning at install start so a .npmrc ported from a pnpm store-server setup keeps working unchanged. Setting it to false (the default) is silently a no-op.

strictStorePkgContentCheck

Validate package names and versions in the store.

• Type: bool
• Default: true
• Environment: npm_config_strict_store_pkg_content_check, NPM_CONFIG_STRICT_STORE_PKG_CONTENT_CHECK, AUBE_STRICT_STORE_PKG_CONTENT_CHECK
• .npmrc keys: strict-store-pkg-content-check, strictStorePkgContentCheck

After each registry tarball is imported, aube reads the freshly stored package.json and confirms its name and version match what the resolver asked for. A mismatch fails the install before the package can be linked into node_modules, defending against registry-substitution attacks where a tarball is served under one (name, version) but contains a different package on disk. Set to false via .npmrc to skip the check (e.g. when intentionally installing a republished tarball whose manifest lists the upstream name). Local sources (file:, link:, git deps) are not checked since they have no registry-asserted (name, version) to compare against.

Examples:

• echo 'strict-store-pkg-content-check=false' >> .npmrc

Network

httpsProxy

Proxy URL for outgoing HTTPS requests.

• Type: url
• Default: null
• Environment: npm_config_proxy, NPM_CONFIG_PROXY, npm_config_https_proxy, NPM_CONFIG_HTTPS_PROXY, AUBE_HTTPS_PROXY, https_proxy, HTTPS_PROXY
• .npmrc keys: https-proxy, httpsProxy, proxy

Forwards every HTTPS registry fetch through the given proxy URL. Honored by the aube-registry reqwest client. Resolution mirrors pnpm: .npmrc https-proxy ?? .npmrc proxy ?? HTTPS_PROXY / https_proxy env var.

httpProxy

Proxy URL for outgoing HTTP requests.

• Type: url
• Default: null
• Environment: PROXY, proxy, npm_config_http_proxy, NPM_CONFIG_HTTP_PROXY, AUBE_HTTP_PROXY, http_proxy, HTTP_PROXY
• .npmrc keys: http-proxy, httpProxy

HTTP counterpart to httpsProxy. Resolution mirrors pnpm: .npmrc http-proxy ?? resolved httpsProxy ?? HTTP_PROXY / http_proxy env var ?? PROXY / proxy env var. The inheritance from httpsProxy means a single https-proxy=... line in .npmrc configures both schemes.

noProxy

Comma-separated list of domains that bypass the proxy.

• Type: string
• Default: null
• Environment: npm_config_noproxy, NPM_CONFIG_NOPROXY, npm_config_no_proxy, NPM_CONFIG_NO_PROXY, AUBE_NO_PROXY, no_proxy, NO_PROXY
• .npmrc keys: noproxy, noProxy, no-proxy

Passed through to reqwest::NoProxy::from_string verbatim, so wildcard and port-qualified hosts behave the same as curl / node. Applies to both httpsProxy and httpProxy. Falls back to the standard NO_PROXY / no_proxy environment variables.

localAddress

Local interface IP address to bind registry connections to.

• Type: string
• Default: undefined
• Environment: npm_config_local_address, NPM_CONFIG_LOCAL_ADDRESS, AUBE_LOCAL_ADDRESS
• .npmrc keys: local-address, localAddress

Used on multi-homed hosts where outbound traffic must leave a specific interface. Parsed as IpAddr; unparseable values are dropped at load time with a warning.

maxsockets

Maximum concurrent connections per origin.

• Type: int
• Default: networkConcurrency x 3
• Environment: npm_config_maxsockets, NPM_CONFIG_MAXSOCKETS, AUBE_MAXSOCKETS
• .npmrc keys: maxsockets

Plumbed into reqwest's pool_max_idle_per_host. This is the closest analogue to pnpm's per-origin socket cap — reqwest doesn't expose a hard maximum, but capping the idle pool keeps the steady state bounded.

strictSsl

Validate SSL certificates for HTTPS requests.

• Type: bool
• Default: true
• Environment: npm_config_strict_ssl, NPM_CONFIG_STRICT_SSL, AUBE_STRICT_SSL
• .npmrc keys: strict-ssl, strictSsl

Defaults to true. Setting strict-ssl=false disables TLS certificate verification entirely via danger_accept_invalid_certs — required to get through corporate MITM proxies that present a self-signed CA until aube grows a proper per-registry cafile setting.

Lockfile

lockfile

Read and generate aube-lock.yaml.

• Type: bool
• Default: true
• Environment: npm_config_lockfile, NPM_CONFIG_LOCKFILE, AUBE_LOCKFILE
• .npmrc keys: lockfile
• Workspace YAML keys: lockfile

Controls whether aube reads and writes a lockfile during install. When false (npm's --no-package-lock equivalent), every aube install runs a fresh resolve, drift checks against an on-disk lockfile are skipped, and the writer is a no-op — useful in lockfile-free workflows and one-off aube install invocations inside isolated throwaway environments.

Setting lockfile=false overrides the frozen-lockfile modes: the install never errors on missing lockfiles and never preserves a format-compatible file alongside aube-lock.yaml. --lockfile-only combined with lockfile=false is rejected as a contradiction.

Examples:

• echo 'lockfile=false' >> .npmrc && aube install

lockfileDir

Directory the lockfile is written to and read from.

• Type: path
• Default: null
• CLI flags: lockfile-dir
• Environment: npm_config_lockfile_dir, NPM_CONFIG_LOCKFILE_DIR, AUBE_LOCKFILE_DIR
• .npmrc keys: lockfile-dir, lockfileDir
• Workspace YAML keys: lockfileDir

By default the lockfile lives at <project_root>/aube-lock.yaml. Set this to relocate it. When the resolved path differs from the project root, the project becomes an importer keyed by its relative path (e.g. project if the lockfile is one directory above).

Single-project relocation only — multi-project shared lockfiles require a pnpm-workspace.yaml workspace. Pointing two unrelated projects at the same lockfileDir is rejected at install time.

Mirrors pnpm's --lockfile-dir / lockfile-dir. A relative path is resolved against the project root, not the current working directory.

Examples:

• aube install --lockfile-dir ..

preferFrozenLockfile

Perform a headless install if the lockfile already satisfies package.json.

• Type: bool
• Default: true
• CLI flags: prefer-frozen-lockfile
• Environment: npm_config_prefer_frozen_lockfile, NPM_CONFIG_PREFER_FROZEN_LOCKFILE, AUBE_PREFER_FROZEN_LOCKFILE
• .npmrc keys: prefer-frozen-lockfile, preferFrozenLockfile
• Workspace YAML keys: preferFrozenLockfile

aube's default outside CI. Maps to FrozenMode::Prefer in crates/aube/src/commands/install.rs. Inside CI the default flips to FrozenMode::Frozen (see default_for_env).

Examples:

• aube install --prefer-frozen-lockfile

lockfileIncludeTarballUrl

Add the full tarball URL to each lockfile entry.

• Type: bool
• Default: false
• Environment: npm_config_lockfile_include_tarball_url, NPM_CONFIG_LOCKFILE_INCLUDE_TARBALL_URL, AUBE_LOCKFILE_INCLUDE_TARBALL_URL
• .npmrc keys: lockfileIncludeTarballUrl, lockfile-include-tarball-url
• Workspace YAML keys: lockfileIncludeTarballUrl

When true, aube's lockfile writer records the registry tarball URL in each package's resolution: block alongside the integrity: hash. This bloats the lockfile (every entry gets the full download URL) but makes the file self-contained — installs no longer need the configured registry to derive the tarball path, which is handy in air-gapped environments or when the .npmrc registry differs from the one the lockfile was generated against.

Only registry packages are affected; file:, link:, git+ and remote-tarball entries already store their source URL unconditionally.

The setting round-trips through the lockfile's settings: header, so once enabled subsequent installs preserve the tarball field without re-reading .npmrc.

Examples:

• echo 'lockfile-include-tarball-url=true' >> .npmrc && aube install

excludeLinksFromLockfile

Skip local link: dependencies when writing the lockfile.

• Type: bool
• Default: false
• Environment: npm_config_exclude_links_from_lockfile, NPM_CONFIG_EXCLUDE_LINKS_FROM_LOCKFILE, AUBE_EXCLUDE_LINKS_FROM_LOCKFILE
• .npmrc keys: exclude-links-from-lockfile, excludeLinksFromLockfile
• Workspace YAML keys: excludeLinksFromLockfile

When true, link: dependencies are omitted from the lockfile's importers.*.dependencies: (and devDependencies: / optionalDependencies:) maps on write, so adding or removing a purely local symlink dep doesn't churn the lockfile. The setting round-trips through the lockfile's settings: header — once enabled, subsequent installs preserve it even without re-reading .npmrc.

Aube already omits link: packages from the packages: / snapshots: sections unconditionally (pnpm parity). This flag controls the importer-level visibility. file: directory deps and git deps are unaffected; only link: entries are filtered.

gitBranchLockfile

Generate branch-specific lockfile names (aube-lock.<branch>.yaml).

• Type: bool
• Default: false
• Environment: npm_config_git_branch_lockfile, NPM_CONFIG_GIT_BRANCH_LOCKFILE, AUBE_GIT_BRANCH_LOCKFILE
• .npmrc keys: gitBranchLockfile, git-branch-lockfile
• Workspace YAML keys: gitBranchLockfile

When enabled, aube writes the lockfile to aube-lock.<branch>.yaml instead of aube-lock.yaml, where <branch> is the current git branch with / replaced by ! (matching pnpm). This reduces merge conflicts on lockfiles for long-lived branches.

Reads fall back to aube-lock.yaml if no branch-specific file exists, so the setting can be turned on mid-project without re-resolving. Detached HEAD or a missing/failing git falls back to the plain name.

Set in aube-workspace.yaml:

gitBranchLockfile: true

See mergeGitBranchLockfilesBranchPattern and the --merge-git-branch-lockfiles install flag for folding branch lockfiles back into aube-lock.yaml automatically or on demand.

mergeGitBranchLockfilesBranchPattern

Branch-name glob list for auto-merging branch lockfiles.

• Type: list<string>
• Default: null
• Environment: npm_config_merge_git_branch_lockfiles_branch_pattern, NPM_CONFIG_MERGE_GIT_BRANCH_LOCKFILES_BRANCH_PATTERN, AUBE_MERGE_GIT_BRANCH_LOCKFILES_BRANCH_PATTERN
• .npmrc keys: mergeGitBranchLockfilesBranchPattern, merge-git-branch-lockfiles-branch-pattern
• Workspace YAML keys: mergeGitBranchLockfilesBranchPattern

Complements gitBranchLockfile. Accepts a list of glob patterns. When aube install runs on a branch whose name matches any pattern, aube discovers every aube-lock.*.yaml file in the project directory, merges their package graphs into aube-lock.yaml, and deletes the branch-specific files. Typical usage:

mergeGitBranchLockfilesBranchPattern:
  - main
  - release/*
  - "!release/legacy-*"

!-prefixed patterns are negations — a branch that matches any positive pattern AND does NOT match any negative pattern triggers the merge. The --merge-git-branch-lockfiles install flag forces the same merge regardless of the pattern list.

Conflict rule: when two branch lockfiles record the same dep_path with different version or integrity, the higher semver version wins and a warning is logged.

sharedWorkspaceLockfile

Write one lockfile per workspace package instead of a single shared root lockfile.

• Type: bool
• Default: true
• Environment: npm_config_shared_workspace_lockfile, NPM_CONFIG_SHARED_WORKSPACE_LOCKFILE, AUBE_SHARED_WORKSPACE_LOCKFILE
• .npmrc keys: sharedWorkspaceLockfile, shared-workspace-lockfile
• Workspace YAML keys: sharedWorkspaceLockfile

Default true matches pnpm: a workspace records every importer's resolved graph in a single root lockfile (aube-lock.yaml or pnpm-lock.yaml), so aube install from anywhere in the workspace sees every package's locked versions.

Flip to false for the per-project layout: each workspace member gets its own lockfile next to its package.json containing only that member's importer (remapped to .) plus the transitive packages reachable from it. The workspace-root lockfile is not written.

Set in aube-workspace.yaml / pnpm-workspace.yaml:

sharedWorkspaceLockfile: false

Trade-offs to know about before flipping the default:

• Auto-install freshness state (node_modules/.aube-state) and the frozen-lockfile fast path are anchored at the workspace root, so a false install re-resolves more aggressively than a shared install would.
• Workspace deps (workspace:*) still resolve correctly because the resolver runs once over the whole workspace before lockfile writes are split.

peersSuffixMaxLength

Max length of the peer-ID suffix in lockfile dep_paths.

• Type: int
• Default: 1000
• Environment: npm_config_peers_suffix_max_length, NPM_CONFIG_PEERS_SUFFIX_MAX_LENGTH, AUBE_PEERS_SUFFIX_MAX_LENGTH
• .npmrc keys: peersSuffixMaxLength, peers-suffix-max-length
• Workspace YAML keys: peersSuffixMaxLength

Caps the length of the peer-ID suffix appended to a dep_path in the lockfile (e.g. [email protected]([email protected])). When the suffix would exceed this many bytes, aube replaces it with _<hex> where <hex> is a short SHA-256 digest of the full suffix — matching pnpm's format so lockfiles stay portable.

Mutual-peer cycles in large graphs can otherwise grow suffixes unboundedly across fixed-point iterations of the resolver. The default of 1000 bytes is pnpm's default and rarely fires in practice.

Request

gitShallowHosts

Hosts for which aube performs shallow git clones.

• Type: list<string>
• Default: ["github.com", "gist.github.com", "gitlab.com", "bitbucket.com", "bitbucket.org"]
• Environment: npm_config_git_shallow_hosts, NPM_CONFIG_GIT_SHALLOW_HOSTS, AUBE_GIT_SHALLOW_HOSTS
• .npmrc keys: git-shallow-hosts, gitShallowHosts

Consulted by aube-store::git_shallow_clone when cloning a git dependency. When the URL's hostname matches an entry in this list (exact match, same as pnpm — github.com does not match api.github.com), aube fetches only the commit it needs with git fetch --depth 1 origin <sha>, falling back to a full fetch if the server refuses by-SHA shallow fetches. When the hostname is not in the list, aube does a plain git fetch origin before checkout, since many self-hosted servers disable uploadpack.allowReachableSHA1InWant and a shallow fetch would either fail or silently waste a round-trip.

The cache key for the resolved checkout is still (url, commit), so two deps that resolve to the same commit share a clone regardless of which strategy produced it.

networkConcurrency

Maximum concurrent HTTP(S) requests.

• Type: int
• Default: auto (workers x3 clamped to 16-64)
• CLI flags: network-concurrency
• Environment: npm_config_network_concurrency, NPM_CONFIG_NETWORK_CONCURRENCY, AUBE_NETWORK_CONCURRENCY
• .npmrc keys: network-concurrency, networkConcurrency
• Workspace YAML keys: networkConcurrency

Caps the tokio semaphores that gate concurrent tarball downloads inside crates/aube/src/commands/install.rs. When unset, aube matches pnpm's dynamic default: worker count x3, clamped to 16-64. Set this value explicitly to override the automatic scaling. The resolver's packument fetcher still uses its own internal cap for now; plumbing that cap through is tracked as a follow-up.

Examples:

• aube install --network-concurrency 8
• echo 'network-concurrency=8' >> .npmrc

fetchRetries

Number of retry attempts for failed registry fetches.

• Type: int
• Default: 2
• CLI flags: fetch-retries
• Environment: npm_config_fetch_retries, NPM_CONFIG_FETCH_RETRIES, AUBE_FETCH_RETRIES
• .npmrc keys: fetch-retries, fetchRetries

Number of additional attempts the registry client makes after a transient failure (5xx / 429 / connection error). 2 means up to 3 total attempts. Applied to every idempotent GET — packument reads, tarball downloads, dist-tag reads. Writes (put_packument, put_dist_tag, delete_dist_tag, audit POST) are not retried because a second attempt could double-apply or race.

Backoff is governed by fetchRetryFactor, fetchRetryMintimeout, fetchRetryMaxtimeout.

Examples:

• aube install --fetch-retries=5

fetchRetryFactor

Exponential backoff factor for fetch retries.

• Type: int
• Default: 10
• CLI flags: fetch-retry-factor
• Environment: npm_config_fetch_retry_factor, NPM_CONFIG_FETCH_RETRY_FACTOR, AUBE_FETCH_RETRY_FACTOR
• .npmrc keys: fetch-retry-factor, fetchRetryFactor

Multiplier used between retry attempts. Attempt n waits min(fetchRetryMintimeout * fetchRetryFactor ^ (n-1), fetchRetryMaxtimeout) milliseconds before retrying. With the defaults (factor=10, min=10000ms, max=60000ms), the sequence is 10s → 60s → 60s.

fetchRetryMintimeout

Minimum retry timeout in milliseconds.

• Type: int
• Default: 10000
• CLI flags: fetch-retry-mintimeout
• Environment: npm_config_fetch_retry_mintimeout, NPM_CONFIG_FETCH_RETRY_MINTIMEOUT, AUBE_FETCH_RETRY_MINTIMEOUT
• .npmrc keys: fetch-retry-mintimeout, fetchRetryMintimeout

Lower bound on the computed retry backoff. See fetchRetryFactor.

fetchRetryMaxtimeout

Maximum retry timeout in milliseconds.

• Type: int
• Default: 60000
• CLI flags: fetch-retry-maxtimeout
• Environment: npm_config_fetch_retry_maxtimeout, NPM_CONFIG_FETCH_RETRY_MAXTIMEOUT, AUBE_FETCH_RETRY_MAXTIMEOUT
• .npmrc keys: fetch-retry-maxtimeout, fetchRetryMaxtimeout

Upper bound on the computed retry backoff. See fetchRetryFactor.

fetchTimeout

Max time (ms) to wait for an HTTP request.

• Type: int
• Default: 300000
• CLI flags: fetch-timeout
• Environment: npm_config_fetch_timeout, NPM_CONFIG_FETCH_TIMEOUT, AUBE_FETCH_TIMEOUT
• .npmrc keys: fetch-timeout, fetchTimeout

Per-request HTTP timeout, applied via reqwest's single-knob .timeout() so it covers headers + body together. A request that exceeds this limit fails with a transport error, which is then retriable (see fetchRetries). Default matches npm's 5 minutes.

Examples:

• aube add lodash --fetch-timeout=60000

fetchWarnTimeoutMs

Warn if a metadata request exceeds this threshold (ms).

• Type: int
• Default: 10000
• Environment: npm_config_fetch_warn_timeout_ms, NPM_CONFIG_FETCH_WARN_TIMEOUT_MS, AUBE_FETCH_WARN_TIMEOUT_MS
• .npmrc keys: fetchWarnTimeoutMs, fetch-warn-timeout-ms

Observability threshold for registry metadata requests (packument, dist-tags). When a successful response takes longer than fetchWarnTimeoutMs milliseconds of wall-clock time — including any retry backoff — aube emits a tracing::warn! line naming the resource and the elapsed time. The request itself is never aborted by this setting; the hard cut-off is still fetchTimeout.

Set to 0 to disable the warning entirely, matching pnpm's convention for "observability knob off". Tarball downloads are intentionally out of scope: fetchMinSpeedKiBps is the tarball-side analogue.

fetchMinSpeedKiBps

Warn if download speed falls below this threshold (KiB/s).

• Type: int
• Default: 50
• Environment: npm_config_fetch_min_speed_ki_bps, NPM_CONFIG_FETCH_MIN_SPEED_KI_BPS, AUBE_FETCH_MIN_SPEED_KI_BPS
• .npmrc keys: fetchMinSpeedKiBps, fetch-min-speed-ki-bps

Warn when a tarball's end-to-end average throughput falls below this many KiB/s. Set to 0 to disable.

packumentMaxBytes

Hard cap on a packument response body size in bytes.

• Type: int
• Default: 209715200
• Environment: npm_config_packument_max_bytes, NPM_CONFIG_PACKUMENT_MAX_BYTES, AUBE_PACKUMENT_MAX_BYTES
• .npmrc keys: packumentMaxBytes, packument-max-bytes

Refuses any packument response whose Content-Length exceeds this many bytes. A hostile or misconfigured registry (including a MITM on a compromised mirror) could otherwise stream gigabytes of JSON into the resolver and OOM the install; the cap makes that fail loudly.

Default: 200 MiB. Raise if you hit the cap, or set to 0 to disable it entirely (only reasonable against a registry you fully trust).

Applies to every packument fetch: corgi and non-corgi variants, the cached-resolve path, and the fresh-read path used by deprecate / undeprecate. Tarball downloads are capped separately via tarballMaxBytes.

tarballMaxBytes

Hard cap on a tarball response body size in bytes (on-wire, still compressed).

• Type: int
• Default: 1073741824
• Environment: npm_config_tarball_max_bytes, NPM_CONFIG_TARBALL_MAX_BYTES, AUBE_TARBALL_MAX_BYTES
• .npmrc keys: tarballMaxBytes, tarball-max-bytes

Refuses any tarball response whose Content-Length exceeds this many bytes before any decompression runs. Without a wire-level cap a hostile mirror could stream a multi-GiB compressed payload into memory before the gzip reader ever sees a byte; the separate decompressed ceiling in aube-store would only fire after that.

Default: 1 GiB. Raise if a legitimate tarball exceeds it, or set to 0 to disable the cap entirely (only reasonable against a registry you fully trust).

Peer Dependencies

autoInstallPeers

Automatically install missing peer dependencies.

• Type: bool
• Default: true
• CLI flags: auto-install-peers
• Environment: npm_config_auto_install_peers, NPM_CONFIG_AUTO_INSTALL_PEERS, AUBE_AUTO_INSTALL_PEERS
• .npmrc keys: auto-install-peers, autoInstallPeers
• Workspace YAML keys: autoInstallPeers

When true (the default), missing peer dependencies are auto-installed during resolution and hoisted into the importer. Set to false to match pnpm's opt-out behavior: peers are left alone and unmet peers are silent (set strict-peer-dependencies=true for diagnostics).

dedupePeerDependents

Deduplicate packages that have peer dependencies.

• Type: bool
• Default: true
• Environment: npm_config_dedupe_peer_dependents, NPM_CONFIG_DEDUPE_PEER_DEPENDENTS, AUBE_DEDUPE_PEER_DEPENDENTS
• .npmrc keys: dedupePeerDependents, dedupe-peer-dependents
• Workspace YAML keys: dedupePeerDependents

When true (the default), aube collapses packages that landed at different peer-suffixed dep_paths but resolved every declared peer to the same version into a single canonical variant. Ancestor dedupe happens inside the per-package DFS; this flag additionally controls the cross-subtree intersection pass that runs inside the fixed-point loop. Set to false to keep every distinct peer-suffixed variant (matching pnpm's opt-out).

dedupePeers

Use version-only identifiers for peer suffixes in the lockfile.

• Type: bool
• Default: false
• Environment: npm_config_dedupe_peers, NPM_CONFIG_DEDUPE_PEERS, AUBE_DEDUPE_PEERS
• .npmrc keys: dedupePeers, dedupe-peers
• Workspace YAML keys: dedupePeers

When true, lockfile peer suffixes emit (18.2.0) instead of the default ([email protected]). Applied as a post-pass over the resolved graph — the resolver's cycle detection still runs against the full name@version form, so mutual-peer cycles converge the same way either form.

strictPeerDependencies

Fail if peer dependencies are missing or invalid.

• Type: bool
• Default: false
• Environment: npm_config_strict_peer_dependencies, NPM_CONFIG_STRICT_PEER_DEPENDENCIES, AUBE_STRICT_PEER_DEPENDENCIES
• .npmrc keys: strict-peer-dependencies, strictPeerDependencies
• Workspace YAML keys: strictPeerDependencies

When true, any unmet peer dependency (missing, or resolved to a version outside the declared range) fails the install with a miette diagnostic listing every mismatch. This is also the only way aube surfaces peer mismatches — by default aube is silent, matching bun/npm/yarn. Set this to false (the default) to disable.

resolvePeersFromWorkspaceRoot

Use root workspace dependencies for peer resolution.

• Type: bool
• Default: true
• Environment: npm_config_resolve_peers_from_workspace_root, NPM_CONFIG_RESOLVE_PEERS_FROM_WORKSPACE_ROOT, AUBE_RESOLVE_PEERS_FROM_WORKSPACE_ROOT
• .npmrc keys: resolvePeersFromWorkspaceRoot, resolve-peers-from-workspace-root
• Workspace YAML keys: resolvePeersFromWorkspaceRoot

When true (the default), an unresolved peer falls back to the root workspace importer's direct deps before the graph-wide scan tier. Common monorepo pattern where the root pins shared peers (e.g. react) that leaf packages peer on without declaring them in their own subtree. Set to false to skip the root tier and go straight to graph-wide scanning.

peerDependencyRules.ignoreMissing

Suppress warnings for specific missing peer dependencies.

• Type: list<string>
• Default: undefined
• Environment: npm_config_peer_dependency_rules_ignore_missing, NPM_CONFIG_PEER_DEPENDENCY_RULES_IGNORE_MISSING, AUBE_PEER_DEPENDENCY_RULES_IGNORE_MISSING
• .npmrc keys: peerDependencyRules.ignoreMissing, peer-dependency-rules.ignore-missing
• Workspace YAML keys: peerDependencyRules.ignoreMissing

Glob list of peer dependency names to exclude from the strict-peer-dependencies check when they're missing entirely. A peer present at the wrong version is still reported (use allowedVersions or allowAny for that). Has no effect on the default install — aube is silent about peer mismatches unless strict mode is on. Read from the root package.json (pnpm.peerDependencyRules.ignoreMissing), pnpm-workspace.yaml, and .npmrc; later sources fully replace the previous source's list.

peerDependencyRules.allowedVersions

Override the accepted semver range for specific peer dependencies.

• Type: object
• Default: undefined
• .npmrc keys: peerDependencyRules.allowedVersions, peer-dependency-rules.allowed-versions
• Workspace YAML keys: peerDependencyRules.allowedVersions

Map of peer selector to an additional semver range. Keys are either a bare peer name (e.g. react) which applies regardless of parent, or parent>peer (e.g. styled-components>react) which scopes the override to peers declared by that specific parent. A peer resolving inside either the declared range or this override is treated as satisfied — widens the accepted range rather than replacing it. Merged across pnpm.peerDependencyRules.allowedVersions in package.json, pnpm-workspace.yaml, and .npmrc (later sources win per key).

peerDependencyRules.allowAny

Allow any peer version to resolve, bypassing semver checks.

• Type: list<string>
• Default: undefined
• Environment: npm_config_peer_dependency_rules_allow_any, NPM_CONFIG_PEER_DEPENDENCY_RULES_ALLOW_ANY, AUBE_PEER_DEPENDENCY_RULES_ALLOW_ANY
• .npmrc keys: peerDependencyRules.allowAny, peer-dependency-rules.allow-any
• Workspace YAML keys: peerDependencyRules.allowAny

Glob list of peer dependency names whose semver check should be bypassed entirely — any resolved version counts as satisfying the declared range. Also excludes missing peers for matching names. Escape hatch for packages with incompatible peer declarations. Has no effect on the default install — aube is silent about peer mismatches unless strict-peer-dependencies is on. Read from the root package.json, pnpm-workspace.yaml, and .npmrc; later sources fully replace the previous source's list.

CLI

color

Control color output in aube's CLI.

• Type: "auto" | "always" | "never"
• Default: "auto"
• CLI flags: color, no-color
• Environment: npm_config_color, NPM_CONFIG_COLOR, AUBE_COLOR
• .npmrc keys: color

--color / --no-color, color=always|never|auto in .npmrc, and NPM_CONFIG_COLOR all resolve before output initializes. The resolved choice is translated into FORCE_COLOR / CLICOLOR_FORCE / NO_COLOR so aube, diagnostics, progress rendering, and child processes agree.

loglevel

Minimum log level to display.

• Type: "debug" | "info" | "warn" | "error" | "silent"
• Default: "warn"
• CLI flags: loglevel, verbose, v, silent
• Environment: npm_config_loglevel, NPM_CONFIG_LOGLEVEL, AUBE_LOGLEVEL
• .npmrc keys: loglevel

Controls aube's tracing filter. -v / --verbose is a shortcut for debug; --silent, --reporter=silent, and loglevel=silent suppress aube's own non-error stderr output. Also readable from .npmrc loglevel. CLI flags override .npmrc.

useBetaCli

Opt into experimental CLI features.

• Type: bool
• Default: false
• Environment: npm_config_use_beta_cli, NPM_CONFIG_USE_BETA_CLI, AUBE_USE_BETA_CLI
• .npmrc keys: useBetaCli, use-beta-cli

Accepted from env and .npmrc for pnpm parity. aube currently has no beta-gated commands, so the setting is a no-op after validation.

recursiveInstall

Install on all workspace packages by default.

• Type: bool
• Default: true
• Environment: npm_config_recursive_install, NPM_CONFIG_RECURSIVE_INSTALL, AUBE_RECURSIVE_INSTALL
• .npmrc keys: recursiveInstall, recursive-install

When true, workspace installs resolve and link all importers by default. Set to false to opt out of implicit workspace-wide install behavior; explicit --filter / --recursive still wins.

engineStrict

Fail if a package is incompatible with the current Node version.

• Type: bool
• Default: false
• Environment: npm_config_engine_strict, NPM_CONFIG_ENGINE_STRICT, AUBE_ENGINE_STRICT
• .npmrc keys: engine-strict, engineStrict

When on, an engines.node mismatch on the root project or any dependency fails the install. When off, mismatches are warnings only.

npmPath

Path to the npm binary aube should shell out to when needed.

• Type: path
• Default: undefined
• Environment: npm_config_npm_path, NPM_CONFIG_NPM_PATH, AUBE_NPM_PATH
• .npmrc keys: npmPath, npm-path

Used for npm-only compatibility commands (owner, pkg, search, set-script, token, whoami) when configured. Without it, aube keeps the explicit use npm error.

packageManagerStrict

Enforce the packageManager field in package.json (off | warn | error).

• Type: "off" | "warn" | "error" | true | false
• Default: "warn"
• Environment: npm_config_package_manager_strict, NPM_CONFIG_PACKAGE_MANAGER_STRICT, AUBE_PACKAGE_MANAGER_STRICT
• .npmrc keys: package-manager-strict, packageManagerStrict

Controls how aube reacts when a project's packageManager field names something other than aube or pnpm (npm, yarn, bun, …). warn (the default) prints a warning and continues; install-class commands also disable the implicit auto-install probe so aube does not silently install on top of another package manager's layout. error fails install-class commands hard (run-class commands still warn). off skips the check entirely. The bool spellings are accepted for back-compat: true maps to error, false to off.

packageManagerStrictVersion

Enforce the exact packageManager version from package.json.

• Type: bool
• Default: false
• Environment: npm_config_package_manager_strict_version, NPM_CONFIG_PACKAGE_MANAGER_STRICT_VERSION, AUBE_PACKAGE_MANAGER_STRICT_VERSION
• .npmrc keys: package-manager-strict-version, packageManagerStrictVersion

When enabled, packageManager: "aube@<version>" must match the running aube version exactly. pnpm@... cannot be exact-version satisfied by aube and fails with a clear diagnostic.

managePackageManagerVersions

Auto-download the specified pnpm version when mismatched.

• Type: bool
• Default: true
• Environment: npm_config_manage_package_manager_versions, NPM_CONFIG_MANAGE_PACKAGE_MANAGER_VERSIONS, AUBE_MANAGE_PACKAGE_MANAGER_VERSIONS
• .npmrc keys: managePackageManagerVersions, manage-package-manager-versions

Accepted for pnpm parity. aube does not download or re-exec other package-manager versions; when exact version enforcement is enabled, mismatches are reported instead.

Build

ignoreScripts

Skip all lifecycle scripts in package.json.

• Type: bool
• Default: false
• CLI flags: ignore-scripts
• Environment: npm_config_ignore_scripts, NPM_CONFIG_IGNORE_SCRIPTS, AUBE_IGNORE_SCRIPTS
• .npmrc keys: ignore-scripts, ignoreScripts
• Workspace YAML keys: ignoreScripts

aube already skips dependency install scripts by default (security-first). The --ignore-scripts flag additionally skips root lifecycle hooks (preinstall, install, postinstall, prepare) and flows through install, ci, and add.

Examples:

• aube install --ignore-scripts
• aube ci --ignore-scripts

childConcurrency

Maximum number of concurrent script-executing child processes.

• Type: int
• Default: 5
• Environment: npm_config_child_concurrency, NPM_CONFIG_CHILD_CONCURRENCY, AUBE_CHILD_CONCURRENCY
• .npmrc keys: child-concurrency, childConcurrency
• Workspace YAML keys: childConcurrency

Caps how many dependency lifecycle scripts run in parallel during the post-link allowBuilds phase. Inside a single package the preinstall / install / postinstall hooks still run sequentially — pnpm's execution model is "at most N packages building in parallel," not "at most N scripts running." Defaults to 5, matching pnpm. Zero and negative values are clamped up to 1.

Examples:

• child-concurrency=10

sideEffectsCache

Cache the results of install hooks.

• Type: bool
• Default: true
• CLI flags: side-effects-cache
• Environment: npm_config_side_effects_cache, NPM_CONFIG_SIDE_EFFECTS_CACHE, AUBE_SIDE_EFFECTS_CACHE
• .npmrc keys: side-effects-cache, sideEffectsCache
• Workspace YAML keys: sideEffectsCache

When an allowlisted dependency runs lifecycle scripts, aube snapshots the post-build package directory under the cache dir keyed by (name, version, input hash). Future installs with the same inputs hardlink that cached tree back into the materialized package and skip the build. Packages still have to pass the active allowBuilds / onlyBuiltDependencies policy before scripts can run or populate the cache.

Examples:

• aube install --no-side-effects-cache
• echo 'side-effects-cache=false' >> .npmrc

sideEffectsCacheReadonly

Only read from the side-effects cache; don't write.

• Type: bool
• Default: false
• Environment: npm_config_side_effects_cache_readonly, NPM_CONFIG_SIDE_EFFECTS_CACHE_READONLY, AUBE_SIDE_EFFECTS_CACHE_READONLY
• .npmrc keys: sideEffectsCacheReadonly, side-effects-cache-readonly

When true, aube may restore allowlisted dependency build output from the side-effects cache but will not write new cache entries after scripts run.

jailBuilds

Run approved dependency lifecycle scripts in a restricted build jail.

• Type: bool
• Default: false
• Environment: npm_config_jail_builds, NPM_CONFIG_JAIL_BUILDS, AUBE_JAIL_BUILDS
• .npmrc keys: jail-builds, jailBuilds
• Workspace YAML keys: jailBuilds

When enabled, dependency lifecycle scripts that pass the active allowBuilds / onlyBuiltDependencies policy run with a scrubbed environment and temporary HOME. On macOS, aube wraps the script with a native Seatbelt profile. On Linux, aube applies Landlock and seccomp in the child before exec. Both deny network access and limit filesystem writes to the package directory and temporary directories. Root lifecycle scripts are not jailed.

This defaults to false today and is planned to default to true in the next major version.

Examples:

• jail-builds=true

jailBuildExclusions

Exclude specific dependency packages from jailed builds.

• Type: list<string>
• Default: []
• Environment: npm_config_jail_build_exclusions, NPM_CONFIG_JAIL_BUILD_EXCLUSIONS, AUBE_JAIL_BUILD_EXCLUSIONS
• .npmrc keys: jailBuildExclusions, jail-build-exclusions
• Workspace YAML keys: jailBuildExclusions

Package patterns in this list still follow the active allowBuilds / onlyBuiltDependencies policy, but run outside the build jail when jailBuilds is enabled. Use this for reviewed native packages whose install scripts need network access, shared caches, or filesystem writes outside the restricted jail profile.

Patterns use the same forms as neverBuiltDependencies: bare package names, exact name@version pins, exact version unions, and * wildcards such as @scope/*. Explicit jail exclusions win over the global jailBuilds=true setting.

Examples:

• jailBuildExclusions: ["sharp", "@vendor/*"]

jailBuildPermissions

Grant package-specific privileges inside jailed builds.

• Type: object
• Default: undefined
• Workspace YAML keys: jailBuildPermissions

Package-pattern map of extra privileges for approved dependency scripts that still run inside the build jail. Keys use the same package glob forms as allowBuilds (sharp, @scope/*, *-native, [email protected] || 1.2.4). Values may grant specific environment variables, extra readable paths, extra writable paths, or network access.

env entries are exact variable names inherited from the parent process. Use this sparingly: explicit env grants can expose secrets. write entries are added to the native write allowlist on macOS and Linux. read entries are accepted now and reserved for the stricter read-deny profile; reads are currently unrestricted.

Examples:

• jailBuildPermissions: { sharp: { env: ["SHARP_DIST_BASE_URL"], write: ["~/.cache/sharp"] } }

unsafePerm

Drop to a non-root user when running scripts as root.

• Type: bool
• Default: false (as root), true (otherwise)
• Environment: npm_config_unsafe_perm, NPM_CONFIG_UNSAFE_PERM, AUBE_UNSAFE_PERM
• .npmrc keys: unsafePerm, unsafe-perm

aube exports the resolved value to lifecycle and run scripts as npm_config_unsafe_perm, matching the environment surface npm-style script tooling expects. aube does not currently switch users itself.

nodeOptions

Options passed to Node.js via NODE_OPTIONS.

• Type: string
• Default: null
• Environment: npm_config_node_options, NPM_CONFIG_NODE_OPTIONS, AUBE_NODE_OPTIONS, NODE_OPTIONS
• .npmrc keys: nodeOptions, node-options

When set in .npmrc, aube exports the value as NODE_OPTIONS for lifecycle scripts and aube run scripts. An existing NODE_OPTIONS environment variable is also honored through the same setting path.

verifyDepsBeforeRun

Check dependencies before running scripts.

• Type: "install" | "warn" | "error" | "prompt" | false
• Default: "install"
• Environment: npm_config_verify_deps_before_run, NPM_CONFIG_VERIFY_DEPS_BEFORE_RUN, AUBE_VERIFY_DEPS_BEFORE_RUN
• .npmrc keys: verifyDepsBeforeRun, verify-deps-before-run

Controls run, lifecycle shortcuts, exec, and implicit script commands. install preserves aube's auto-install behavior, warn reports stale dependencies without installing, error fails, false skips the check, and prompt currently behaves like install in non-interactive aube.

strictDepBuilds

Exit with an error if dependencies have unreviewed build scripts.

• Type: bool
• Default: false
• Environment: npm_config_strict_dep_builds, NPM_CONFIG_STRICT_DEP_BUILDS, AUBE_STRICT_DEP_BUILDS
• .npmrc keys: strictDepBuilds, strict-dep-builds

aube never runs dependency lifecycle scripts unless the package is listed in allowBuilds or --dangerously-allow-all-builds is set. With strictDepBuilds = true, an install that sees unreviewed build scripts fails after linking and before any dependency build scripts run. Add reviewed packages to allowBuilds with true, keep intentionally skipped packages as false, or leave the default strictDepBuilds=false behavior to skip unreviewed builds.

allowBuilds

Explicitly allow or disallow script execution per package.

• Type: object
• Default: undefined
• .npmrc keys: allowBuilds, allow-builds
• Workspace YAML keys: allowBuilds

Per-package review map for dependency lifecycle scripts. Read from package.json's pnpm.allowBuilds field and workspace yaml's allowBuilds. Keys are package name patterns (esbuild, @scope/*, [email protected] || 2.0.0); values are true to allow preinstall / install / postinstall scripts for that package or false to record an intentional skip. Packages not listed are skipped by default, and install adds unreviewed build packages to workspace allowBuilds as false for later review.

Examples:

• pnpm.allowBuilds: { esbuild: true, "@some/pkg": false }

dangerouslyAllowAllBuilds

Allow all dependency build scripts automatically.

• Type: bool
• Default: false
• CLI flags: dangerously-allow-all-builds
• Environment: npm_config_dangerously_allow_all_builds, NPM_CONFIG_DANGEROUSLY_ALLOW_ALL_BUILDS, AUBE_DANGEROUSLY_ALLOW_ALL_BUILDS
• .npmrc keys: dangerouslyAllowAllBuilds, dangerously-allow-all-builds

Opt-out escape hatch for the allowBuilds allowlist: when set, every dependency's preinstall / install / postinstall / prepare scripts run regardless of the allowlist. Equivalent to pnpm's --dangerously-allow-all-builds. Useful for ad-hoc debugging; do not use in CI.

Examples:

• aube install --dangerously-allow-all-builds

Node.js

nodeVersion

Node.js version aube reports when evaluating engines checks.

• Type: string
• Default: output of `node -v` with the leading `v` stripped
• Environment: npm_config_node_version, NPM_CONFIG_NODE_VERSION, AUBE_NODE_VERSION
• .npmrc keys: node-version, nodeVersion

Paired with engineStrict. Set this in .npmrc to pin the Node version engines checks validate against, rather than probing node --version at install time.

nodeDownloadMirrors

Custom Node.js download mirror URLs.

• Type: object
• Default: undefined
• .npmrc keys: nodeDownloadMirrors, node-download-mirrors

Accepted for pnpm config parity. aube does not download Node.js itself, so the parsed mirror map is preserved for config introspection but has no install-time effect.

Other

savePrefix

Version prefix used when installing a package.

• Type: "^" | "~" | ""
• Default: "^"
• Environment: npm_config_save_prefix, NPM_CONFIG_SAVE_PREFIX, AUBE_SAVE_PREFIX
• .npmrc keys: save-prefix, savePrefix

Resolved from .npmrc. --save-exact overrides to empty prefix.

linkWorkspacePackages

Resolve aube add <name> against local workspace siblings before falling back to the registry.

• Type: "false" | "true" | "deep"
• Default: "false"
• Environment: npm_config_link_workspace_packages, NPM_CONFIG_LINK_WORKSPACE_PACKAGES, AUBE_LINK_WORKSPACE_PACKAGES
• .npmrc keys: link-workspace-packages, linkWorkspacePackages
• Workspace YAML keys: linkWorkspacePackages

When true or "deep", aube add <name> checks the workspace for a package whose name matches the spec before falling back to the registry. A match wires the dep up as a workspace link; the manifest specifier written to package.json is controlled by saveWorkspaceProtocol.

If the user typed an explicit range (aube add pkg@^1.2.0), the sibling's version must satisfy it — otherwise the spec falls through to the registry path so an incompatible local copy isn't silently linked.

Off by default to match pnpm 8+ — opt in via pnpm-workspace.yaml when you want every aube add to prefer the local copy of a sibling. Aube's resolver already prefers workspace siblings on bare semver ranges at install time, including transitives, so pnpm's "deep" mode is accepted as an alias for the add-time manifest behavior.

saveWorkspaceProtocol

Spec form written to package.json when aube add resolves against a workspace sibling.

• Type: "true" | "false" | "rolling"

• Default: "rolling"

• Environment: npm_config_save_workspace_protocol, NPM_CONFIG_SAVE_WORKSPACE_PROTOCOL, AUBE_SAVE_WORKSPACE_PROTOCOL

• .npmrc keys: save-workspace-protocol, saveWorkspaceProtocol

• Workspace YAML keys: saveWorkspaceProtocol

• "true" writes a version-pinned workspace spec (workspace:^1.0.0, honoring savePrefix). The exact lockfile entry never moves without an explicit aube update.

• "rolling" (default) writes the rolling form workspace:^ (or workspace:~ / workspace:* per savePrefix). Sibling version bumps flow into dependents on the next install without re-running aube add.

• "false" writes a plain registry-style spec (^1.0.0). The dep is still linked locally on install (controlled by linkWorkspacePackages), but the manifest looks identical to a registry dep.

The --save-workspace-protocol / --no-save-workspace-protocol CLI flags on aube add override this setting per-invocation.

tag

Default dist-tag used by aube add without a version.

• Type: string
• Default: "latest"
• Environment: npm_config_tag, NPM_CONFIG_TAG, AUBE_TAG
• .npmrc keys: tag

Resolved from .npmrc. Used by aube add when no version or dist-tag is specified.

globalDir

Directory where globally installed packages live.

• Type: path
• Default: platform-specific
• Environment: npm_config_global_dir, NPM_CONFIG_GLOBAL_DIR, AUBE_GLOBAL_DIR
• .npmrc keys: globalDir, global-dir

Overrides the directory where globally installed packages live. Falls back to AUBE_HOME / PNPM_HOME / platform default.

globalBinDir

Directory where global binaries are symlinked.

• Type: path
• Default: platform-specific
• Environment: npm_config_global_bin_dir, NPM_CONFIG_GLOBAL_BIN_DIR, AUBE_GLOBAL_BIN_DIR
• .npmrc keys: globalBinDir, global-bin-dir

Overrides the directory where global binaries are symlinked. Independent of globalDir; falls back to AUBE_HOME / PNPM_HOME / platform default.

npmrcAuthFile

Path to an additional .npmrc file consulted for registry authentication tokens.

• Type: path
• Default: undefined
• Environment: npm_config_npmrc_auth_file, NPM_CONFIG_NPMRC_AUTH_FILE, AUBE_NPMRC_AUTH_FILE
• .npmrc keys: npmrc-auth-file, npmrcAuthFile

Points at an extra .npmrc-formatted file that aube reads after the user and project .npmrc files when resolving registry auth. Anything declared in this file wins, so it's the right home for CI secrets mounted at a fixed path (e.g. /run/secrets/npm) or for a per-user token override that you don't want to put in ~/.npmrc.

The setting itself can be declared in either ~/.npmrc or the project .npmrc. Path interpretation matches pnpm's other path settings: ~ expands to the user's home directory and a relative path resolves against the project root.

Implementation: parsed values are appended to the merged entry list returned by aube_registry::config::load_npmrc_entries, so the auth-token lookup picks them up automatically — no separate loader.

Examples:

• echo 'npmrc-auth-file=/run/secrets/npm' >> .npmrc && aube install

stateDir

Directory for aube install-state files.

• Type: path
• Default: node_modules
• Environment: npm_config_state_dir, NPM_CONFIG_STATE_DIR, AUBE_STATE_DIR
• .npmrc keys: stateDir, state-dir

Overrides the directory that holds the .aube-state install-state file. Defaults to the resolved modulesDir (usually node_modules), so the state file lives at <modulesDir>/.aube-state and rm -rf <modulesDir> naturally invalidates it.

cacheDir

Directory for package metadata and dlx cache.

• Type: path
• Default: ~/.cache/aube
• Environment: npm_config_cache_dir, NPM_CONFIG_CACHE_DIR, AUBE_CACHE_DIR
• .npmrc keys: cache-dir, cacheDir

Overrides the cache directory. XDG_CACHE_HOME is honored by the platform default (aube_store::dirs::cache_dir) which appends /aube; this setting takes a complete path.

useStderr

Write all output to stderr instead of stdout.

• Type: bool
• Default: false
• Environment: npm_config_use_stderr, NPM_CONFIG_USE_STDERR, AUBE_USE_STDERR
• .npmrc keys: useStderr, use-stderr

Redirects stdout to stderr for the process lifetime. Resolved from .npmrc or the --use-stderr CLI flag.

updateNotifier

Show an update notification when a newer aube is available.

• Type: bool
• Default: true
• Environment: npm_config_update_notifier, NPM_CONFIG_UPDATE_NOTIFIER, AUBE_UPDATE_NOTIFIER
• .npmrc keys: updateNotifier, update-notifier

After a successful install, add, or update, aube fetches https://aube.en.dev/VERSION and prints a one-line notice if the advertised version is newer than the running binary. The result is cached under <cacheDir>/update-check.json so only the first run in any 24h window touches the network. Failures (DNS, timeout, non-200, unparseable response) are swallowed silently so a network hiccup never disturbs the install summary. The check is also skipped when CI or AUBE_NO_UPDATE_CHECK is set, or when --offline / --prefer-offline was requested for the install itself. Set to false to opt out permanently.

updateRewritesSpecifier

Rewrite caret/tilde manifest specifiers on aube update without --latest.

• Type: bool
• Default: true
• Environment: npm_config_update_rewrites_specifier, NPM_CONFIG_UPDATE_REWRITES_SPECIFIER, AUBE_UPDATE_REWRITES_SPECIFIER
• .npmrc keys: updateRewritesSpecifier, update-rewrites-specifier

When aube update <pkg> (no --latest) bumps the lockfile to a newer in-range version, the matching ^X.Y.Z / ~X.Y.Z entry in package.json is rewritten to track the new version. Set to false to keep the manifest specifier frozen and only update the lockfile. Other range shapes (>=, 1.x, exact pins, dist-tags, git, workspace) are never rewritten by the no---latest path regardless of this setting.

preferSymlinkedExecutables

Create symlinks instead of shims for .bin entries.

• Type: bool
• Default: true under `nodeLinker=hoisted`, false otherwise
• Environment: npm_config_prefer_symlinked_executables, NPM_CONFIG_PREFER_SYMLINKED_EXECUTABLES, AUBE_PREFER_SYMLINKED_EXECUTABLES
• .npmrc keys: preferSymlinkedExecutables, prefer-symlinked-executables

POSIX only. When unset, defaults to false for the standard isolated layout (.bin/<name> is a shell-script shim that exports NODE_PATH covering the project's top-level node_modules/ and the hidden .aube/node_modules/, so transitives like an auto-installed typescript peer resolve when the bin asks Node for them) and to true under nodeLinker=hoisted (every dep is already on the top-level node_modules/ walk-up path, so the symlink is enough). Setting it explicitly overrides that logic. A bare symlink can't export env vars, so preferSymlinkedExecutables=true makes extendNodePath a no-op. Ignored on Windows — .bin/<name>.{cmd,ps1,} wrappers are always written there since real symlinks require Developer Mode / admin rights.

ignoreCompatibilityDb

Disable pnpm's automatic dependency patching database.

• Type: bool
• Default: false
• Environment: npm_config_ignore_compatibility_db, NPM_CONFIG_IGNORE_COMPATIBILITY_DB, AUBE_IGNORE_COMPATIBILITY_DB
• .npmrc keys: ignoreCompatibilityDb, ignore-compatibility-db

Accepted for pnpm config parity. pnpm ships a built-in compatibility database of auto-patches for known-broken packages; aube has no such database, so this setting has nothing to toggle. Parsed without warning so shared .npmrc files that set it remain portable.

resolutionMode

Dependency version resolution strategy.

• Type: "highest" | "time-based" | "lowest-direct"
• Default: "highest"
• CLI flags: resolution-mode
• Environment: npm_config_resolution_mode, NPM_CONFIG_RESOLUTION_MODE, AUBE_RESOLUTION_MODE
• .npmrc keys: resolution-mode, resolutionMode

Controls how aube chooses versions during resolution. highest picks the newest satisfying version. time-based filters candidates through the lockfile / packument publish-time cutoff before picking. lowest-direct is accepted for pnpm parity and currently maps to the same time-aware resolver mode.

registrySupportsTimeField

Whether the configured registry returns a time field in metadata.

• Type: bool
• Default: false
• Environment: npm_config_registry_supports_time_field, NPM_CONFIG_REGISTRY_SUPPORTS_TIME_FIELD, AUBE_REGISTRY_SUPPORTS_TIME_FIELD
• .npmrc keys: registry-supports-time-field, registrySupportsTimeField

When false (the default, matching pnpm and npmjs.org's behavior), aube fetches the full (non-corgi) packument to read the time: map whenever it's needed — that is, under resolutionMode = time-based or when minimumReleaseAge is in play. When true, aube trusts the abbreviated (corgi) packument to carry time: itself and skips the extra full-packument fetch, cutting one request per distinct package on those resolution paths. Safe to enable against registries known to include time in their abbreviated responses — Verdaccio 5.15.1+, JSR, and most in-house mirrors derived from those — and leave at the default for npmjs.org. The flag has no effect when neither time-based resolution nor minimumReleaseAge is active, since nothing asks for time on the hot path then.

Examples:

• echo 'registry-supports-time-field=true' >> .npmrc

forceMetadataPrimer

Force the bundled metadata primer on for custom registries.

• Type: bool
• Default: false
• Environment: npm_config_force_metadata_primer, NPM_CONFIG_FORCE_METADATA_PRIMER, AUBE_FORCE_METADATA_PRIMER
• .npmrc keys: force-metadata-primer, forceMetadataPrimer

By default aube only uses its bundled npm metadata primer when the effective registry is npmjs.org, because the primer is generated from npmjs metadata. Enable this for trusted npm-compatible mirrors and controlled benchmarks where the mirror serves the same packages but uses a different registry URL. When forced, aube rewrites primer tarball URLs to the configured registry before seeding the cache, so tarball bytes still come from the mirror rather than npmjs.org.

Examples:

• echo 'force-metadata-primer=true' >> .npmrc

extendNodePath

Set NODE_PATH in command shims.

• Type: bool
• Default: true
• Environment: npm_config_extend_node_path, NPM_CONFIG_EXTEND_NODE_PATH, AUBE_EXTEND_NODE_PATH
• .npmrc keys: extendNodePath, extend-node-path

When true (default), aube-generated .bin shims export a NODE_PATH covering the project's top-level node_modules/ and the hidden .aube/node_modules/ (when using the isolated linker) so the shimmed binary can resolve hoisted transitives — e.g. an auto-installed typescript peer — even when invoked from an unusual working directory. Has no effect on POSIX with preferSymlinkedExecutables=true — only shim scripts can export env vars. Windows shims always honor this setting.

deployAllFiles

Copy all files when deploying a workspace package.

• Type: bool
• Default: false
• Environment: npm_config_deploy_all_files, NPM_CONFIG_DEPLOY_ALL_FILES, AUBE_DEPLOY_ALL_FILES
• .npmrc keys: deploy-all-files, deployAllFiles
• Workspace YAML keys: deployAllFiles

When true, aube deploy copies every file in the source workspace package into the target directory instead of running pack's selection (the files field + .npmignore / .gitignore). Skips only filesystem-level cruft that could never be part of a package payload (node_modules/, .git/) and the target directory itself when it sits inside the source. Useful when runtime-needed files (config fixtures, local scripts, non-published assets) live outside the set that npm publish would ship. Default false keeps pack parity so the deployed tree matches what would be published.

dedupeDirectDeps

Skip symlinking workspace-root dependencies if identical across packages.

• Type: bool
• Default: false
• Environment: npm_config_dedupe_direct_deps, NPM_CONFIG_DEDUPE_DIRECT_DEPS, AUBE_DEDUPE_DIRECT_DEPS
• .npmrc keys: dedupe-direct-deps, dedupeDirectDeps
• Workspace YAML keys: dedupeDirectDeps

When true, the linker skips creating a node_modules/<name> symlink in a workspace package whose root importer already declares the same workspace package as a direct dep with the identical version. Reduces symlink churn in monorepos that ship a single shared version of an internal library. Only affects the per-importer top-level symlink — cross-importer workspace: resolution keeps working because those still resolve through the lockfile + root-level tree. No-op under node-linker=hoisted (each importer gets its own flat tree) and under virtualStoreOnly=true (no per-importer symlink pass runs at all).

optimisticRepeatInstall

Fast-path check before running a full install.

• Type: bool
• Default: true
• Environment: npm_config_optimistic_repeat_install, NPM_CONFIG_OPTIMISTIC_REPEAT_INSTALL, AUBE_OPTIMISTIC_REPEAT_INSTALL
• .npmrc keys: optimisticRepeatInstall, optimistic-repeat-install

When true (default), aube run / aube exec / aube start / aube test / aube restart consult node_modules/.aube-state and skip the auto-install if the recorded lockfile + root package.json hashes match the current files. Set false to force every auto-install check to run the full install pipeline — useful when the state file is out of sync with reality (e.g. manual edits under node_modules/) and you want every command to reconcile. aube install itself always runs its pipeline regardless of this setting.

requiredScripts

Scripts that must be present in every workspace project.

• Type: list<string>
• Default: undefined
• Environment: npm_config_required_scripts, NPM_CONFIG_REQUIRED_SCRIPTS, AUBE_REQUIRED_SCRIPTS
• .npmrc keys: requiredScripts, required-scripts

During install, aube verifies that the root package and every discovered workspace package define each required script in package.json.

enablePrePostScripts

Run pre/post scripts automatically when a named script is invoked.

• Type: bool
• Default: true
• Environment: npm_config_enable_pre_post_scripts, NPM_CONFIG_ENABLE_PRE_POST_SCRIPTS, AUBE_ENABLE_PRE_POST_SCRIPTS
• .npmrc keys: enablePrePostScripts, enable-pre-post-scripts

Controls whether aube run build also runs prebuild before build and postbuild after it when those scripts exist.

scriptShell

Shell used to invoke package scripts.

• Type: path
• Default: null (uses /bin/sh on Unix, cmd on Windows)
• Environment: npm_config_script_shell, NPM_CONFIG_SCRIPT_SHELL, AUBE_SCRIPT_SHELL
• .npmrc keys: scriptShell, script-shell

Overrides the shell executable used for lifecycle and aube run scripts. On Unix, aube invokes the configured shell with -c.

shellEmulator

Use a JavaScript bash-like shell to run scripts cross-platform.

• Type: bool
• Default: false
• Environment: npm_config_shell_emulator, NPM_CONFIG_SHELL_EMULATOR, AUBE_SHELL_EMULATOR
• .npmrc keys: shellEmulator, shell-emulator

Accepted for pnpm config parity. aube does not embed pnpm's JavaScript shell emulator, but it exports npm_config_shell_emulator=true for scripts when the setting is enabled.

catalogMode

How catalog references in package.json are handled by add.

• Type: "manual" | "strict" | "prefer"
• Default: "manual"
• Environment: npm_config_catalog_mode, NPM_CONFIG_CATALOG_MODE, AUBE_CATALOG_MODE
• .npmrc keys: catalogMode, catalog-mode

manual (the default) writes whatever range aube add resolved, even when the package is declared in the default catalog. prefer rewrites the saved specifier to catalog: whenever the added package appears in the default catalog and the user's range is compatible with the catalog entry (i.e. they didn't ask for something different). strict goes further: if the package is in the default catalog the manifest always gets catalog: written, and an explicit aube add pkg@range whose range disagrees with the catalog fails fast instead of silently drifting from the catalog.

Named catalogs (catalog:<name>) are never auto-picked — users still have to opt in by naming the catalog. Specs written as npm: aliases are also left alone since aliasing and catalog rewrites can't both apply cleanly.

ci

Explicitly mark the environment as CI.

• Type: bool
• Default: auto-detected
• Environment: npm_config_ci, NPM_CONFIG_CI, AUBE_CI, CI
• .npmrc keys: ci

aube detects CI via env::var("CI").is_ok() in two places: aube-linker (disables the global virtual store) and install::FrozenMode::default_for_env (flips the default to Frozen).

Examples:

• CI=1 aube install

cleanupUnusedCatalogs

Remove unused catalog entries during install.

• Type: bool
• Default: false
• Environment: npm_config_cleanup_unused_catalogs, NPM_CONFIG_CLEANUP_UNUSED_CATALOGS, AUBE_CLEANUP_UNUSED_CATALOGS
• .npmrc keys: cleanupUnusedCatalogs, cleanup-unused-catalogs
• Workspace YAML keys: cleanupUnusedCatalogs

When enabled, aube install rewrites aube-workspace.yaml (or pnpm-workspace.yaml, whichever is present) after resolution to drop entries no importer references. A catalog that ends up empty is removed entirely. The rewrite is comment- and format-preserving: yaml comments around surviving entries (and on the rest of the file) stay intact. yamlpatch's Remove op only deletes the line carrying the entry's key: value, so a # annotation line above a pruned entry is left in place rather than guessed-at; clean those up by hand if you don't want orphaned annotations.

aube-specific

linkConcurrency

Maximum concurrent package materialization/linking tasks.

• Type: int
• Default: platform-specific
• Environment: npm_config_link_concurrency, NPM_CONFIG_LINK_CONCURRENCY, AUBE_LINK_CONCURRENCY
• .npmrc keys: link-concurrency, linkConcurrency
• Workspace YAML keys: linkConcurrency

Caps the dedicated linker worker pool used for filesystem-heavy materialization in aube-linker: creating package directories, reflinking / hardlinking files, and writing dependency symlinks. Defaults are platform-aware because APFS reflink metadata work and Linux hardlink work saturate at different points (currently 4 on macOS, 16 elsewhere, bounded by available parallelism). Set this when you know your filesystem prefers a different amount of link-phase parallelism.

Examples:

• link-concurrency=8
• AUBE_LINK_CONCURRENCY=8 aube install

aubeNoLock

Disable aube's project-level advisory lock.

• Type: bool
• Default: false
• Environment: npm_config_aube_no_lock, NPM_CONFIG_AUBE_NO_LOCK, AUBE_NO_LOCK
• .npmrc keys: aubeNoLock, aube-no-lock
• Workspace YAML keys: aubeNoLock

aube takes an advisory lock on node_modules/ at the start of every mutating command (install, add, remove, etc.) so concurrent invocations in the same project serialize cleanly. Set this to a truthy value to bypass the lock — useful in CI matrices where separate jobs share the same HOME, or in deliberately-parallel test rigs.

Canonical name is aubeNoLock so it can be set from aube-workspace.yaml, pnpm-workspace.yaml, or .npmrc (as aubeNoLock / aube-no-lock). The AUBE_NO_LOCK env-var alias is kept as a convenient shell-export form.

Values are parsed as strict booleans via the shared aube_settings::values::parse_bool rule: 1 / true are truthy, 0 / false are explicitly off, and anything else (including unset, empty string, or arbitrary text) leaves the default (false, i.e. locking stays on).

Examples:

• AUBE_NO_LOCK=1 aube install
• echo 'aubeNoLock=true' >> .npmrc

aubeNoAutoInstall

Skip the auto-install staleness check in aube run / aube exec.

• Type: bool
• Default: false
• CLI flags: no-install
• Environment: npm_config_aube_no_auto_install, NPM_CONFIG_AUBE_NO_AUTO_INSTALL, AUBE_NO_AUTO_INSTALL
• .npmrc keys: aubeNoAutoInstall, aube-no-auto-install
• Workspace YAML keys: aubeNoAutoInstall

aube run <script> normally checks node_modules/.aube-state and auto-installs before running if package.json or the lockfile has drifted. Setting this to a truthy value skips that check — the same effect as passing --no-install on every invocation. Useful in long-lived dev shells where you control installs yourself, or in workspace monorepos that want a consistent policy across every importer.

Canonical name is aubeNoAutoInstall so it can be set from aube-workspace.yaml, pnpm-workspace.yaml, or .npmrc (as aubeNoAutoInstall / aube-no-auto-install). The AUBE_NO_AUTO_INSTALL env-var alias is kept as a convenient shell-export form.

Values are parsed as strict booleans via the shared aube_settings::values::parse_bool rule: 1 / true are truthy, 0 / false are explicitly off, and anything else (including unset, empty string, or arbitrary text) leaves the default (false, i.e. auto-install stays on).

Examples:

• AUBE_NO_AUTO_INSTALL=1 aube run dev
• echo 'aubeNoAutoInstall=true' >> .npmrc