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.cjs hook file.
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.
trustPolicy	"no-downgrade" | "off"	Behavior when a package's trust level decreases between installs.
trustPolicyExclude	list<string>	Packages exempt from trust policy checks.
trustPolicyIgnoreAfter	int	Ignore trust policy for packages older than this age (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.
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.
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.
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).
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	bool	Enforce the packageManager field in package.json.
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.
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.
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.
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.
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
• Environment: npm_config_overrides, NPM_CONFIG_OVERRIDES
• .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
• Environment: npm_config_package_extensions, NPM_CONFIG_PACKAGE_EXTENSIONS
• .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
• Environment: npm_config_allowed_deprecated_versions, NPM_CONFIG_ALLOWED_DEPRECATED_VERSIONS
• .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: AUBE_DEPRECATION_WARNINGS, npm_config_deprecation_warnings, NPM_CONFIG_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
• .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
• Environment: npm_config_supported_architectures, NPM_CONFIG_SUPPORTED_ARCHITECTURES
• .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
• .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.cjs hook file.

• Type: string
• Default: undefined
• Environment: npm_config_pnpmfile_path, NPM_CONFIG_PNPMFILE_PATH
• Workspace YAML keys: pnpmfilePath

Workspace-scoped override for the .pnpmfile.cjs discovery path. Defaults to <project>/.pnpmfile.cjs. Relative paths resolve against the workspace 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.

minimumReleaseAge

Delay installation of newly published versions (minutes).

• Type: int
• Default: 1440
• Environment: npm_config_minimum_release_age, NPM_CONFIG_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
• .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
• .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.

trustPolicy

Behavior when a package's trust level decreases between installs.

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

When set to no-downgrade, aube accepts and preserves the policy in the resolver configuration. Registry trust metadata is not exposed through aube's packument path yet, so no downgrade failure can fire until that metadata source lands.

trustPolicyExclude

Packages exempt from trust policy checks.

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

Whitelist for trustPolicy. Entries skip the downgrade check.

trustPolicyIgnoreAfter

Ignore trust policy for packages older than this age (minutes).

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

Useful for pinning very old versions that predate signing infrastructure.

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
• .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/" }
• Environment: npm_config_registries, NPM_CONFIG_REGISTRIES
• .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
• .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
• .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.

hoistPattern

Packages to hoist to the hidden modules directory.

• Type: list<string>
• Default: ["*"]
• Environment: npm_config_hoist_pattern, NPM_CONFIG_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
• .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
• .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
• .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
• .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
• .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
• .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
• .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
• .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
• .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
• .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 the fastest strategy: reflink (clonefile/btrfs CoW) → hardlink → copy. Explicit values force a single strategy: hardlink hard-links from the store (with a copy fallback on cross-filesystem errors), copy always writes a full copy, clone uses reflink (and currently falls back to copy when reflink is unsupported — strict enforcement is planned for a future release), and 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
• .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
• .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
• .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
• .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/v1/files/
• Environment: npm_config_store_dir, NPM_CONFIG_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/v1/files/, falling back to ~/.local/share/aube/store/v1/files/). 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 CAS schema suffix (v1/files) to the user-supplied directory, so store-dir=/srv/aube-store stores package content under /srv/aube-store/v1/files.

Only the on-disk CAS moves; the packument and virtual-store caches stay at $XDG_CACHE_HOME/aube.

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
• .npmrc keys: verify-store-integrity, verifyStoreIntegrity
• Workspace YAML keys: verifyStoreIntegrity

aube verifies each package's integrity (SHA-512) 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
• .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
• .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
• .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: HTTPS_PROXY, https_proxy, npm_config_https_proxy, NPM_CONFIG_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: HTTP_PROXY, http_proxy, PROXY, proxy, npm_config_http_proxy, NPM_CONFIG_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: NO_PROXY, no_proxy, npm_config_no_proxy, NPM_CONFIG_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
• .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
• .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
• .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
• .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

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
• .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
• .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
• .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
• .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
• .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.

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
• .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
• .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: 128 (tarballs), 64 (packuments)
• CLI flags: network-concurrency
• Environment: npm_config_network_concurrency, NPM_CONFIG_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 set, both the lockfile-driven and streaming fetch paths use the configured value instead of the built-in defaults (128 for tarballs, 64 for the streaming path). 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
• Environment: npm_config_fetch_retries, NPM_CONFIG_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.

fetchRetryFactor

Exponential backoff factor for fetch retries.

• Type: int
• Default: 10
• Environment: npm_config_fetch_retry_factor, NPM_CONFIG_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
• Environment: npm_config_fetch_retry_mintimeout, NPM_CONFIG_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
• Environment: npm_config_fetch_retry_maxtimeout, NPM_CONFIG_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: 60000
• Environment: npm_config_fetch_timeout, NPM_CONFIG_FETCH_TIMEOUT
• .npmrc keys: fetchTimeout, fetch-timeout

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 pnpm / npm's 60s.

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
• .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
• .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.

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
• .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
• .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
• .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
• .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
• .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
• .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
• Environment: npm_config_peer_dependency_rules_allowed_versions, NPM_CONFIG_PEER_DEPENDENCY_RULES_ALLOWED_VERSIONS
• .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
• .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
• .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
• .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
• .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
• .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
• .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
• .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.

• Type: bool
• Default: true
• Environment: npm_config_package_manager_strict, NPM_CONFIG_PACKAGE_MANAGER_STRICT
• .npmrc keys: package-manager-strict, packageManagerStrict

When a project declares packageManager, aube accepts aube and pnpm package-manager names and rejects npm/yarn/bun/etc. Set to false to skip this guard.

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
• .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
• .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
• .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
• .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
• .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
• .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.

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
• .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: NODE_OPTIONS, npm_config_node_options, NPM_CONFIG_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
• .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
• .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 / onlyBuiltDependencies, add intentionally skipped packages to neverBuiltDependencies, or leave the default strictDepBuilds=false behavior to skip unreviewed builds.

allowBuilds

Explicitly allow or disallow script execution per package.

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

Per-package allowlist for dependency lifecycle scripts. Read from package.json's pnpm.allowBuilds field and aube-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 block them. Packages not listed are skipped by default (aube's safe default).

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
• .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
• .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
• Environment: npm_config_node_download_mirrors, NPM_CONFIG_NODE_DOWNLOAD_MIRRORS
• .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
• .npmrc keys: save-prefix, savePrefix

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

tag

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

• Type: string
• Default: "latest"
• Environment: npm_config_tag, NPM_CONFIG_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
• .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
• .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
• .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
• .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
• .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
• .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
• .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.

preferSymlinkedExecutables

Create symlinks instead of shims for .bin entries.

• Type: bool
• Default: true (POSIX hoisted)
• Environment: npm_config_prefer_symlinked_executables, NPM_CONFIG_PREFER_SYMLINKED_EXECUTABLES
• .npmrc keys: preferSymlinkedExecutables, prefer-symlinked-executables

POSIX only. Default (unset or true) creates a plain symlink from node_modules/.bin/<name> straight to the package's executable file — the historical aube layout and matches pnpm's hoisted default. Set false to write a shell-script shim instead; pair this with extendNodePath=true when you need the shim to export NODE_PATH, since a bare symlink can't set env vars. 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
• .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
• .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
• .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

extendNodePath

Set NODE_PATH in command shims.

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

When true (default), aube-generated .bin shims export NODE_PATH="$basedir/.." so the shimmed binary can resolve modules through the top-level node_modules even when invoked with an unusual working directory. Has no effect on POSIX with the default symlink layout — only shim scripts can export env vars, so pair extendNodePath=true with preferSymlinkedExecutables=false on POSIX if the binary really needs NODE_PATH. 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
• .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
• .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
• .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
• .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
• .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
• .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
• .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
• .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: CI, npm_config_ci, NPM_CONFIG_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
• .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 goes through serde_yaml, so comments and custom formatting in the workspace file are not preserved — turn this on only when you're happy to keep the workspace YAML machine-generated.

aube-specific

linkConcurrency

Maximum concurrent package materialization/linking tasks.

• Type: int
• Default: platform-specific
• Environment: AUBE_LINK_CONCURRENCY, npm_config_link_concurrency, NPM_CONFIG_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: AUBE_NO_LOCK, npm_config_aube_no_lock, NPM_CONFIG_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: AUBE_NO_AUTO_INSTALL, npm_config_aube_no_auto_install, NPM_CONFIG_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