scpm add
- Usage:
scpm add [FLAGS] [PACKAGES]… - Aliases:
a
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 scpm/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#scpm.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 lowDownloadThreshold confirm prompt / refusal for this invocation.
scpm add looks up each candidate's weekly download count and prompts (interactive) or fails (CI) when the count is below lowDownloadThreshold. The flag is intended for the cases where you've already verified the package out-of-band — adding a brand-new niche tool, a fresh fork, an internal scratch package — and don't want the prompt to interrupt scripted workflows. Does not affect the OSV malicious-package check, which remains a hard block.
--deny-build… <PKG>
Mark a dependency's lifecycle scripts as reviewed and denied.
Writes allowBuilds: { <pkg>: false } into the workspace yaml (or package.json#scpm.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.
--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 scpm-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 scpm refuses to add dependencies to the root package.json of a workspace (a directory containing scpm-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.
--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
--fetch-retries <N>
Number of retry attempts for failed registry fetches.
Overrides fetchRetries / fetch-retries from .npmrc / scpm-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 / scpm-workspace.yaml when set. Integer-only — the underlying FetchPolicy.retry_factor is u32. Fractional values like 1.5 are rejected by clap.
--fetch-retry-maxtimeout <MS>
Upper bound (ms) on the computed retry backoff.
Overrides fetchRetryMaxtimeout / fetch-retry-maxtimeout from .npmrc / scpm-workspace.yaml when set.
--fetch-retry-mintimeout <MS>
Lower bound (ms) on the computed retry backoff.
Overrides fetchRetryMintimeout / fetch-retry-mintimeout from .npmrc / scpm-workspace.yaml when set.
--fetch-timeout <MS>
Per-request HTTP timeout in milliseconds.
Overrides fetchTimeout / fetch-timeout from .npmrc / scpm-workspace.yaml when set. Applied via reqwest's .timeout() so it covers headers + 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.
--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 ~/.cache/scpm/virtual-store/.
--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.