aube add

• Usage: aube add [FLAGS] [PACKAGES]…
• Aliases: a
• Effect: modifies state

Add a dependency

Arguments

• [PACKAGES]… — Package(s) to add

Flags

• -D --save-dev — Add as dev dependency.

• -E --save-exact — Pin the exact resolved version (no ^ prefix).

• -g --global — Install the package globally.

  Installs into the aube/pnpm global directory and links its binaries into the global bin directory. Mirrors pnpm add -g.

• -O --save-optional — Add as optional dependency.

• --allow-build=<PKG> — Pre-approve a dependency's lifecycle scripts as part of the add.

  Writes allowBuilds: { <pkg>: true } into the workspace yaml (or package.json#aube.allowBuilds) before the install runs, so the named package's preinstall / install / postinstall scripts execute on this invocation. Repeatable — pass the flag once per package. Mirrors pnpm add --allow-build=<pkg>.

  Conflicts with --no-save, which only snapshots package.json and the lockfile and would leave an orphaned approval in the workspace yaml on restore. Also conflicts with --deny-build for the same package name.

• --allow-low-downloads — Bypass the similar-name, new-name, and lowDownloadThreshold confirm prompts / refusals for this invocation.

  aube add looks up each candidate's weekly download count and prompts (interactive) or fails (CI) when the count is below lowDownloadThreshold, resembles a top-100,000 npm package, or is newer than minimumPackageAge. The flag is intended for cases where you've already verified the package out-of-band. It does not affect the OSV malicious-package check, which remains a hard block.

• --dangerously-allow-all-builds — Allow every dependency's lifecycle scripts to run.

  Bypasses the allowBuilds allowlist for this invocation. Do not use in CI. Mirrors pnpm's --dangerously-allow-all-builds.

• --deny-build=<PKG> — Mark a dependency's lifecycle scripts as reviewed and denied.

  Writes allowBuilds: { <pkg>: false } into the workspace yaml (or package.json#aube.allowBuilds) before the install runs, so the named package's lifecycle scripts stay skipped without tripping strictDepBuilds=true. Repeatable — pass the flag once per package.

  Conflicts with --no-save, which only snapshots package.json and the lockfile and would leave an orphaned denial in the workspace yaml on restore. Also conflicts with --allow-build for the same package name and with --dangerously-allow-all-builds.

• --no-save — Install without persisting the dependency to package.json.

  Snapshots package.json and the lockfile, links the named packages into node_modules, and then restores both files — so the dependency is usable for the current process but the project's committed state is untouched.

  Handy for one-off experiments and for scripts that install a tool transiently. Mirrors pnpm add --no-save. Conflicts with -g/--global, which has to persist the install to its global manifest.

• --no-save-workspace-protocol — Inverse of --save-workspace-protocol.

  Forces the manifest specifier into a registry-style spec (^<version>) for this invocation, even when linkWorkspacePackages matched a local sibling. The install pipeline still prefers the local workspace copy at resolve time — this flag only controls what's written to package.json. Mirrors pnpm add --no-save-workspace-protocol.

• --save-catalog — Save the new dependency into the workspace's default catalog.

  Writes catalog: into package.json and seeds/upserts the resolved range under catalog: in the workspace yaml. Mirrors pnpm add --save-catalog.

  Workspace and aliased specs (workspace:*, npm:, jsr:) are never catalogized — the manifest gets the original spec and the catalog yaml is left alone. If the package is already in the target catalog, the existing entry is preserved (never overwritten); the manifest then gets catalog: only when the existing entry is compatible with the user's range.

  Conflicts with --no-save: catalog mutations write to the workspace yaml, which the --no-save restore path doesn't snapshot — combining the two would silently leave an orphaned catalog entry behind.

• --save-catalog-name <NAME> — Save the new dependency into a named catalog.

  Writes the entry to catalogs.<name> in the workspace yaml and catalog:<name> into package.json. Same workspace/alias exclusions and --no-save conflict as --save-catalog. Mirrors pnpm add --save-catalog-name=<name>.

• --save-peer — Add as a peer dependency (written to peerDependencies in package.json).

  By convention you usually pair this with --save-dev so the peer is also installed for local development; that's what pnpm does.

• --save-workspace-protocol — Force the manifest specifier into workspace: form for this invocation, overriding saveWorkspaceProtocol from the workspace yaml / .npmrc / env.

  Only meaningful when linkWorkspacePackages (or a workspace sibling already exists for the named package). With this flag the entry written to package.json is workspace:^ (rolling) or workspace:^<version> (pinned), depending on the resolved saveWorkspaceProtocol value.

• -w --workspace — Add the dependency to the workspace root's package.json.

  Applies regardless of the current working directory: walks up from cwd looking for aube-workspace.yaml, pnpm-workspace.yaml, or a package.json with a workspaces field and runs the add against that directory.

• -W --ignore-workspace-root-check — Allow add to run in a workspace root.

  By default aube refuses to add dependencies to the root package.json of a workspace (a directory containing aube-workspace.yaml, pnpm-workspace.yaml, or a package.json with a workspaces field) because deps added there end up shared by every package and usually reflect a mistake. Pass this flag to opt in. Mirrors pnpm add -W.

• -h --help — Print help

Lockfile

• --frozen-lockfile — Error if the lockfile drifts from package.json.
• --no-frozen-lockfile — Always re-resolve, even if the lockfile is up to date.
• --prefer-frozen-lockfile — Use the lockfile when fresh, re-resolve when stale.

Network

• --fetch-retries <N> — Number of retry attempts for failed registry fetches.

  Overrides fetchRetries / fetch-retries from .npmrc / aube-workspace.yaml when set. Pair with --fetch-timeout to fail fast in scripted test runs.

• --fetch-retry-factor <N> — Exponential backoff factor between retry attempts.

  Overrides fetchRetryFactor / fetch-retry-factor from .npmrc / aube-workspace.yaml when set. Integer-only; fractional values like 1.5 are rejected.

• --fetch-retry-maxtimeout <MS> — Upper bound (ms) on the computed retry backoff.

  Overrides fetchRetryMaxtimeout / fetch-retry-maxtimeout from .npmrc / aube-workspace.yaml when set.

• --fetch-retry-mintimeout <MS> — Lower bound (ms) on the computed retry backoff.

  Overrides fetchRetryMintimeout / fetch-retry-mintimeout from .npmrc / aube-workspace.yaml when set.

• --fetch-timeout <MS> — Per-request HTTP timeout in milliseconds.

  Overrides fetchTimeout / fetch-timeout from .npmrc / aube-workspace.yaml when set. Covers the whole request (headers and body together).

• --registry <URL> — Override the default registry URL for this invocation.

  Use this npm registry URL for package metadata, tarballs, audit requests, dist-tags, and registry writes.

Virtual store

• --disable-global-virtual-store — Force the shared global virtual store off for this invocation.

  Packages are materialized inside the project's virtual store instead of symlinked from the shared tree under <cacheDir>/virtual-store/v1/ (by default ~/.cache/aube/virtual-store/v1/).

  Aliases: --disable-gvs

• --enable-global-virtual-store — Force the shared global virtual store on for this invocation.

  Overrides CI's default per-project materialization and the disableGlobalVirtualStoreForPackages auto-disable heuristic.

  Aliases: --enable-gvs