// @generated by usage-rs metadata

min_usage_version "4.0"

name aube

bin aube

about "A fast Node.js package manager"

view aubr root=run globals=#true

view aubx root=dlx globals=#true

external_subcommand #true

flagset network-args {

flag --fetch-retries help="Number of retry attempts for failed registry fetches." help_heading=Network {

long_help #"""

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.

"""#

arg <N>

}

flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network {

long_help #"""

Exponential backoff factor between retry attempts.

Overrides `fetchRetryFactor` / `fetch-retry-factor` from `.npmrc` / `aube-workspace.yaml` when set. Integer-only — the underlying `FetchPolicy.retry_factor` is `u32`. Fractional values like `1.5` are rejected by the CLI parser.

"""#

arg <N>

}

flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff." help_heading=Network {

long_help #"""

Upper bound (ms) on the computed retry backoff.

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

"""#

arg <MS>

}

flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff." help_heading=Network {

long_help #"""

Lower bound (ms) on the computed retry backoff.

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

"""#

arg <MS>

}

flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network {

long_help #"""

Per-request HTTP timeout in milliseconds.

Overrides `fetchTimeout` / `fetch-timeout` from `.npmrc` / `aube-workspace.yaml` when set. Applied via `reqwest`'s `.timeout()` so it covers headers + body together.

"""#

arg <MS>

}

flag --registry help="Override the default registry URL for this invocation." help_heading=Network {

long_help #"""

Override the default registry URL for this invocation.

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

"""#

arg <URL>

}

}

flagset lockfile-args {

flag --frozen-lockfile help="Error if the lockfile drifts from package.json." help_heading=Lockfile {

conflicts --no-frozen-lockfile --prefer-frozen-lockfile

}

flag --no-frozen-lockfile help="Always re-resolve, even if the lockfile is up to date." help_heading=Lockfile {

conflicts --frozen-lockfile --prefer-frozen-lockfile

}

flag --prefer-frozen-lockfile help="Use the lockfile when fresh, re-resolve when stale." help_heading=Lockfile {

conflicts --frozen-lockfile --no-frozen-lockfile

}

}

flagset virtual-store-args {

flag "--disable-global-virtual-store --disable-gvs" help="Force the shared global virtual store off for this invocation." help_heading="Virtual store" conflicts=--enable-global-virtual-store {

long_help #"""

Force the shared global virtual store off for this invocation.

Packages are materialized inside the project's virtual store instead of symlinked from `~/.cache/aube/virtual-store/`.

"""#

}

flag "--enable-global-virtual-store --enable-gvs" help="Force the shared global virtual store on for this invocation." help_heading="Virtual store" conflicts=--disable-global-virtual-store {

long_help #"""

Force the shared global virtual store on for this invocation.

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

"""#

}

}

flagset script-args {

flag --no-install help="Skip auto-install check"

use lockfile-args

use network-args

use virtual-store-args

}

flagset fallback-args {

use network-args

}

flagset clean-args {

flag "-l --lockfile" help="Also remove lockfiles at the workspace root." {

long_help #"""

Also remove lockfiles at the workspace root.

Targets `aube-lock.yaml`, `pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, and `bun.lock`.

"""#

}

}

flag "-C --dir --cd --prefix" help="Change to directory before running (like `make -C` or `mise --cd`)" global=#true {

arg <DIR>

}

flag "-F --filter" help="Scope command execution to workspace packages matching PATTERN." global=#true var=#true {

long_help #"""

Scope command execution to workspace packages matching PATTERN.

Supports exact names (`my-pkg`), globs (`@scope/*`, `*-plugin`), paths (`./packages/api`), graph selectors (`pkg...`, `...pkg`), git-ref selectors (`[origin/main]`), and exclusions (`!pkg`). Repeatable; matches are OR-ed.

Currently honored by `run`, `test`, `start`, `stop`, `restart`, `install`, `exec`, `list`, `publish`, `deploy`, `add`, `remove`, `update`, `why`, and implicit-script invocations.

"""#

arg <WORKSPACE>

}

flag "-r --recursive" help="Run the command across every workspace package." global=#true {

long_help #"""

Run the command across every workspace package.

Equivalent to `--filter=*`; if `--filter` is also given, `--recursive` is a no-op and the explicit filter wins. Honored by the same commands as `--filter`.

"""#

}

flag "-v --verbose" help="Enable verbose/debug logging (shortcut for `--loglevel debug`)" global=#true

flag "-V --version" help="Print version and check for updates." global=#true {

long_help #"""

Print version and check for updates.

Manual flag so we can run the async update notifier alongside the version print — clap's auto `Action::Version` exits inside `parse_from`, before the tokio runtime is built.

"""#

}

flag --aggregate-output help="Group workspace command output after each package finishes." global=#true hide=#true conflicts=--stream {

long_help #"""

Group workspace command output after each package finishes.

Accepted for pnpm compatibility; aube's workspace fanout is currently sequential, so output is already grouped.

"""#

}

flag --color help="Force colored output even when stderr is not a TTY." global=#true conflicts=--no-color {

long_help #"""

Force colored output even when stderr is not a TTY.

Overrides `NO_COLOR` / `CLICOLOR=0`. Mutually exclusive with `--no-color`.

"""#

}

flag --diag help=#"""

Enable cold-install deep diagnostics. Modes:

summary — sum_ms / mean / max / %wall table at end

trace — summary + critical path + starvation + what-if + lifecycle

live — like trace, plus print every span >= 100ms to stderr live

full — like trace, plus write JSONL trace to a file (defaults to ./aube-diag.jsonl)

"""# global=#true value_optional=#true default_missing=trace {

long_help #"""

Enable cold-install deep diagnostics. Modes:

summary — sum_ms / mean / max / %wall table at end

trace — summary + critical path + starvation + what-if + lifecycle

live — like trace, plus print every span >= 100ms to stderr live

full — like trace, plus write JSONL trace to a file (defaults to ./aube-diag.jsonl)

Quick form: `--diag` with no value defaults to `trace`. Output file path can be set via `--diag-file`. Threshold for live mode via `--diag-threshold-ms`.

"""#

arg "[MODE]" required=#false

}

flag --diag-file help="Path for `--diag full` JSONL trace (default: ./aube-diag.jsonl)" global=#true {

arg <PATH>

}

flag --diag-threshold-ms help="Live-mode threshold: only print spans whose duration is >= N ms (default 100)." global=#true {

arg <MS>

}

flag --fail-if-no-match help="Error when a workspace selector matches no packages." global=#true {

long_help #"""

Error when a workspace selector matches no packages.

Accepted globally; selected commands already fail on empty matches.

"""#

}

flag --filter-prod help="Production-only variant of `--filter`." global=#true var=#true {

long_help #"""

Production-only variant of `--filter`.

Same selector grammar as `--filter`, but graph walks (`pkg...`, `...pkg`) only follow `dependencies` / `optionalDependencies` / `peerDependencies` edges — `devDependencies` (and packages reachable solely through them) are skipped. Non-graph forms (exact name, glob, path, `[git-ref]`) behave identically to `--filter`. Repeatable; can be combined with `--filter`.

"""#

arg <PATTERN>

}

flag --ignore-workspace help="Ignore workspace discovery for commands that support workspace fanout." global=#true hide=#true {

long_help #"""

Ignore workspace discovery for commands that support workspace fanout.

Parsed for pnpm compatibility.

"""#

}

flag --include-workspace-root help="Include the workspace root in recursive workspace operations." global=#true hide=#true {

long_help #"""

Include the workspace root in recursive workspace operations.

Parsed for pnpm compatibility.

"""#

}

flag --loglevel help="Set the log level. Logs at or above this level are shown." global=#true {

arg <LEVEL> {

choices {

choice trace

choice debug

choice info

choice warn

choice error

choice silent

}

}

}

flag --no-color help="Disable colored output." global=#true {

long_help #"""

Disable colored output.

Overrides `FORCE_COLOR` / `CLICOLOR_FORCE` and sets `NO_COLOR=1` so downstream libraries (miette, clx, child processes) all see the same choice.

"""#

}

flag --reporter help="Output format: default, append-only, ndjson, silent." global=#true {

long_help #"""

Output format: default, append-only, ndjson, silent.

`default` renders the progress UI when stderr is a TTY; `append-only` disables the progress UI in favor of plain line-at-a-time logs; `ndjson` swaps the tracing fmt layer for the JSON formatter (one JSON object per log event on stderr) and is what tooling wrappers should consume; `silent` suppresses all non-error output (alias for `--loglevel silent`).

"""#

arg <NAME> {

choices {

choice default

choice append-only

choice ndjson

choice silent

}

}

}

flag --silent help="Suppress all non-error output (alias for `--loglevel silent`)" global=#true

flag --stream help="Stream workspace command output as each child process writes it." global=#true hide=#true conflicts=--aggregate-output {

long_help #"""

Stream workspace command output as each child process writes it.

Accepted for pnpm compatibility; aube's workspace fanout is currently sequential.

"""#

}

flag --use-stderr help="Route lifecycle and workspace command output through stderr." global=#true hide=#true {

long_help #"""

Route lifecycle and workspace command output through stderr.

Accepted for pnpm compatibility.

"""#

}

flag --workspace-packages help="Prefer workspace packages when resolving dependencies." global=#true hide=#true {

long_help #"""

Prefer workspace packages when resolving dependencies.

Parsed for pnpm compatibility; aube already resolves workspace packages when a workspace is present.

"""#

}

flag --workspace-root help="Run from the workspace root regardless of the current package." global=#true

flag "-y --yes" help="Automatically answer yes to prompts." global=#true hide=#true {

long_help #"""

Automatically answer yes to prompts.

Parsed for pnpm compatibility; aube does not currently prompt on these paths.

"""#

}

flag "-h --help" help="Print help" action=help builtin=#true

cmd __node-gyp-bootstrap help="Bootstrap aube's cached node-gyp and print the executable path." hide=#true effect=write {

flag "-h --help" help="Print help" action=help builtin=#true

arg <PROJECT_DIR>

}

cmd access help="Manage package access and visibility on the registry" effect=read subcommand_required=#true {

flag --json help="Emit registry responses as JSON when the subcommand has a result."

flag --otp help="One-time password from a 2FA authenticator; sent as `npm-otp`." {

arg <OTP>

}

use network-args

flag "-h --help" help="Print help" action=help builtin=#true

cmd get help="Get package visibility status." effect=read subcommand_required=#true {

flag "-h --help" help="Print help" action=help builtin=#true

cmd status help="Get a package's public or restricted status." effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg <PACKAGE> help="Package name."

}

}

cmd grant help="Grant a team read-only or read-write access to a package." effect=write {

flag "-h --help" help="Print help" action=help builtin=#true

arg <PERMISSIONS> help="`read-only` or `read-write`."

arg <TEAM> help="Team in `@scope:team` form."

arg <PACKAGE> help="Package name."

}

cmd list help="List packages visible to a user, organization, or team." effect=read subcommand_required=#true {

flag "-h --help" help="Print help" action=help builtin=#true

cmd collaborators help="List collaborators for a package, optionally filtering to one user." effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg <PACKAGE> help="Package name."

arg "[USER]" help="Optional user name."

}

cmd packages help="List packages visible to the current user or an optional entity." effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg "[ENTITY]" help="User, `@organization`, or `@scope:team`."

}

}

cmd ls help="Alias for `list packages`." effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg "[ENTITIES]..." help="User, `@organization`, or `@scope:team`. Also accepts pnpm's `packages [ENTITY]` compatibility form. Accepted forms are `aube access ls [ENTITY]` and `aube access ls packages [ENTITY]`." var_max=2

}

cmd revoke help="Revoke a team's access to a package." effect=destructive {

flag "-h --help" help="Print help" action=help builtin=#true

arg <TEAM> help="Team in `@scope:team` form."

arg <PACKAGE> help="Package name."

}

cmd set help="Set package visibility or a publish MFA requirement." effect=write {

flag "-h --help" help="Print help" action=help builtin=#true

arg <SETTING> help="`status=public|private|restricted` or `mfa=none|publish|automation`."

arg <PACKAGE> help="Package name."

}

}

cmd activate help="Emit shell activation code for runtime tool shims" effect=write {

flag "-h --help" help="Print help" action=help builtin=#true

arg <SHELL> help="Shell to emit activation code for"

}

cmd add help="Add a dependency" effect=write {

alias a

flag "-D --save-dev" help="Add as dev dependency"

flag "-E --save-exact" help="Pin the exact resolved version (no `^` prefix)"

flag "-g --global" help="Install the package globally." {

long_help #"""

Install the package globally.

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

"""#

}

flag "-O --save-optional" help="Add as optional dependency"

flag --allow-build help="Pre-approve a dependency's lifecycle scripts as part of the add." var=#true conflicts=--no-save require_equals=#true {

long_help #"""

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.

"""#

arg <PKG> validate="value != ''" validate_error="The --allow-build flag is missing a package name. Please specify the package name(s) that are allowed to run installation scripts."

}

flag --allow-low-downloads help="Bypass the similar-name, new-name, and [`lowDownloadThreshold`] confirm prompts / refusals for this invocation." {

long_help #"""

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.

"""#

}

flag --dangerously-allow-all-builds help="Allow every dependency's lifecycle scripts to run." {

long_help #"""

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

"""#

}

flag --deny-build help="Mark a dependency's lifecycle scripts as reviewed and denied." var=#true require_equals=#true {

long_help #"""

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

"""#

conflicts --no-save --dangerously-allow-all-builds

arg <PKG> validate="value != ''" validate_error="The --deny-build flag is missing a package name. Please specify the package name(s) that are denied from running installation scripts."

}

flag --ignore-scripts help="Skip root and approved dependency lifecycle scripts." hide=#true

flag --no-save help="Install without persisting the dependency to `package.json`." conflicts=--global {

long_help #"""

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.

"""#

}

flag --no-save-workspace-protocol help="Inverse of `--save-workspace-protocol`." overrides=--save-workspace-protocol {

long_help #"""

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

"""#

}

flag --save-catalog help="Save the new dependency into the workspace's default catalog." {

long_help #"""

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.

"""#

conflicts --save-catalog-name --no-save

}

flag --save-catalog-name help="Save the new dependency into a *named* catalog." conflicts=--no-save {

long_help #"""

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

"""#

arg <NAME>

}

flag --save-peer help="Add as a peer dependency (written to `peerDependencies` in package.json)." conflicts=--save-optional {

long_help #"""

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.

"""#

}

flag --save-workspace-protocol help="Force the manifest specifier into `workspace:` form for this invocation, overriding `saveWorkspaceProtocol` from the workspace yaml / `.npmrc` / env." overrides=--no-save-workspace-protocol {

long_help #"""

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.

"""#

}

flag "-w --workspace" help="Add the dependency to the workspace root's `package.json`." conflicts=--global {

long_help #"""

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.

"""#

}

flag "-W --ignore-workspace-root-check" help="Allow `add` to run in a workspace root." {

long_help #"""

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

"""#

}

use lockfile-args

use network-args

use virtual-store-args

flag "-h --help" help="Print help" action=help builtin=#true

arg "[PACKAGES]..." help="Package(s) to add"

}

cmd approve-builds help="Approve ignored dependency build scripts." effect=write {

long_help #"""

Approve ignored dependency build scripts.

Writes entries under `allowBuilds` in `aube-workspace.yaml` (or `pnpm-workspace.yaml` if present).

"""#

flag --all help="Approve every pending ignored build without prompting."

flag "-g --global" help="Operate on globally-installed packages instead of the current project."

flag "-h --help" help="Print help" action=help builtin=#true

arg "[PKG]..." help="Packages to approve directly, skipping the picker." {

long_help #"""

Packages to approve directly, skipping the picker.

Each name must match a currently-ignored build. Unknown names are rejected so a typo cannot silently no-op.

"""#

}

}

cmd audit help="Check installed packages against the registry advisory DB" effect=read {

flag --audit-level help="Only print advisories at or above this severity." {

long_help #"""

Only print advisories at or above this severity.

One of: `info`, `low`, `moderate`, `high`, `critical`. Defaults to `audit.level` (or legacy `auditLevel`), then `low`.

"""#

arg <AUDIT_LEVEL> {

choices {

choice info

choice low

choice moderate

choice high

choice critical

}

}

}

flag "-D --dev" help="Only audit `devDependencies`." conflicts=--prod

flag --fix help="Fix advisories." value_optional=#true default_missing=override {

long_help #"""

Fix advisories.

Bare `--fix` writes package.json overrides for backwards compatibility. `--fix=update` refreshes the lockfile without writing overrides.

"""#

arg "[FIX]" required=#false {

choices {

choice update help="Refresh the lockfile to patched versions allowed by existing ranges."

choice override help="Write package.json overrides that force patched versions."

}

}

}

flag --ignore help="Drop advisories whose ID matches one of these values." var=#true delimiter=, {

long_help #"""

Drop advisories whose ID matches one of these values.

Matches against the numeric npm advisory `id`, `github_advisory_id` (`GHSA-…`), and any entry in `cves[]` (case-insensitive). Repeatable; comma-separated values are also accepted.

"""#

arg <ID>

}

flag --ignore-registry-errors help="Use exit code 0 if the registry responds with an error." {

long_help #"""

Use exit code 0 if the registry responds with an error.

Useful when audit checks run in CI and the registry has a hiccup.

"""#

}

flag --ignore-unfixable help="Drop advisories that have no non-vulnerable upgrade." {

long_help #"""

Drop advisories that have no non-vulnerable upgrade.

Filters out advisories for which no non-vulnerable version is available in the package's packument. Same "best non-vulnerable" logic as `--fix`: an advisory is kept only when an upgrade path exists.

"""#

}

flag "-i --interactive" help="Pick which advisories to fix interactively."

flag --json help="Emit the report as JSON (pnpm-compatible shape) instead of a table."

flag --no-optional help="Skip `optionalDependencies`."

flag "-P --prod --production" help="Only audit `dependencies` and `optionalDependencies`." conflicts=--dev

use network-args

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd bin help="Print the path to `node_modules/.bin`" effect=read {

flag "-g --global" help="Print the global bin directory instead of the project's" conflicts=--workspace-root

flag "-w --workspace-root --workspace" help="Print the workspace-root bin directory instead of the current package's." {

long_help #"""

Print the workspace-root bin directory instead of the current package's.

Mirrors `pnpm bin -w`: from a sub-package, resolves the enclosing workspace root and prints its `node_modules/.bin`. No-op when no workspace root exists above cwd (single-project install), so the flag is safe to leave in shell aliases.

"""#

}

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd bugs help="Open package bug tracker URLs" effect=read {

alias issues

after_long_help #"""

Examples:

$ aube bugs

$ aube bugs react

$ aube issues react react-dom

"""#

use network-args

flag "-h --help" help="Print help" action=help builtin=#true

arg "[PACKAGES]..." help="Packages to open bug trackers for. Defaults to the current project."

}

cmd cache help="Inspect and manage the packument metadata cache" effect=read subcommand_required=#true {

flag "-h --help" help="Print help" action=help builtin=#true

cmd delete help="Delete metadata cache for the specified package(s)." effect=write {

long_help #"""

Delete metadata cache for the specified package(s).

Supports glob patterns; matches against the package name (e.g. `lodash`, `@babel/*`).

"""#

flag "-h --help" help="Print help" action=help builtin=#true

arg <PATTERNS>... help="One or more package name patterns." {

long_help #"""

One or more package name patterns.

Glob metacharacters (`*`, `?`, `[...]`) are supported.

"""#

}

}

cmd list help="List the available packages in the metadata cache." effect=read {

long_help #"""

List the available packages in the metadata cache.

Optional glob filters narrow the result; with no filter every cached package is listed.

"""#

flag "-h --help" help="Print help" action=help builtin=#true

arg "[PATTERNS]..." help="Optional glob patterns to filter the listing." {

long_help #"""

Optional glob patterns to filter the listing.

With no patterns, every cached package is printed.

"""#

}

}

cmd list-registries help="List configured registries from the project + user `.npmrc`." effect=read {

long_help #"""

List configured registries from the project + user `.npmrc`.

Aube stores all packuments in a single flat directory (unlike pnpm's per-host layout), so this prints the registries you're currently configured to talk to rather than the registries that happen to be in the cache.

"""#

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd path help="Print the directory used for metadata and policy caches." effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd prune help="Remove stale extracted primer files from the metadata cache." effect=write {

flag --age-days help="Minimum age in days before an old primer file is removed." default="30" {

arg <AGE_DAYS>

}

flag --dry-run help="Do not actually delete anything."

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd view help="View the cached metadata for a single package." effect=read {

long_help #"""

View the cached metadata for a single package.

Prints a summary (versions, dist-tags, ETag, fetched-at) by default; `--json` dumps the raw cache file.

"""#

flag --json help="Dump the raw on-disk cache JSON instead of a summary."

flag "-h --help" help="Print help" action=help builtin=#true

arg <NAME> help="Package name (scoped names like `@babel/core` are accepted)."

}

}

cmd cat-file help="Print a file from the global store by integrity or hex hash" effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg <HASH> help="File hash to look up." {

long_help #"""

File hash to look up.

Accepts `sha512-<base64>` (pnpm integrity format) or a raw hex CAS digest.

"""#

}

}

cmd cat-index help="Print the cached package index JSON for `<name>@<version>`" effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg <PACKAGE> help="Package to inspect, in `name@version` form (e.g. `lodash@4.17.21`, `@babel/core@7.26.0`)." {

long_help #"""

Package to inspect, in `name@version` form (e.g. `lodash@4.17.21`, `@babel/core@7.26.0`).

An exact version is required — ranges and dist-tags aren't resolved here.

"""#

}

}

cmd check help="Verify installed packages can resolve their declared deps." effect=read {

long_help #"""

Verify installed packages can resolve their declared deps.

Walks the `node_modules/` symlink tree and confirms every dependency in each `package.json` resolves to a real entry.

"""#

flag --json help="Emit a JSON report instead of the human-readable list."

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd ci help="Clean install: delete node_modules, then install with frozen lockfile." effect=write {

alias clean-install

alias ic

alias install-clean

long_help #"""

Clean install: delete node_modules, then install with frozen lockfile.

Use in CI to guarantee a reproducible install from the committed lockfile.

"""#

flag --ignore-scripts help="Skip lifecycle scripts (no-op; aube already skips by default)"

flag --no-optional help="Skip optionalDependencies; don't install optional native modules"

use lockfile-args

use network-args

use virtual-store-args

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd clean help="Remove `node_modules` across every workspace project." effect=write {

long_help #"""

Remove `node_modules` across every workspace project.

`--lockfile` / `-l` also deletes lockfiles. A `clean` script in the root `package.json` overrides the built-in.

"""#

flag "-l --lockfile" help="Also remove lockfiles at the workspace root." {

long_help #"""

Also remove lockfiles at the workspace root.

Targets `aube-lock.yaml`, `pnpm-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, and `bun.lock`.

"""#

}

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd completion help="Generate shell completions (bash, zsh, fish)" effect=read {

flag --force help="Replace a file at a target path that aube did not write" effect=write requires=--install

flag --install help="Install the scripts where this shell looks for them, instead of printing them" effect=write {

long_help #"""

Install the scripts where this shell looks for them, instead of printing them

Writes one script per program — aube, aubr and aubx — and nothing else: no shell rc file and no PowerShell profile is edited. Where a shell needs a one-time line of its own, it is printed for you to add.

"""#

}

flag "-h --help" help="Print help" action=help builtin=#true

arg <SHELL> help="The shell to generate completions for (bash, zsh, fish)"

}

cmd config help="Read and write settings in `.npmrc`" effect=read {

alias c

flag --all help="Also list settings that have no value set." {

long_help #"""

Also list settings that have no value set.

Renders one row per setting in `settings.toml`, with the default and description shown for unset entries.

Only valid with `--location merged` (the default), since a per-file view can't distinguish "not set anywhere" from "set in the other file" and would render misleading defaults.

"""#

}

flag --json help="Emit all entries as a JSON object keyed by setting name." {

long_help #"""

Emit all entries as a JSON object keyed by setting name.

Matches `pnpm config list --json`. Honors `--all` and `--location` the same way the default text output does.

"""#

}

flag --local help="Shortcut for `--location project`." {

long_help #"""

Shortcut for `--location project`.

Conflicts with `--all` since `--all` only makes sense against the merged view — see the `--all` docs for why.

"""#

conflicts --location --all

}

flag --location help="Which config location(s) to list." {

long_help #"""

Which config location(s) to list.

`merged` (default) walks `~/.npmrc`, user aube config, then the project's `.npmrc` with last-write-wins precedence, matching how install reads config.

"""#

arg <LOCATION> {

choices {

choice merged help="Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses)."

choice user help="Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)"

choice project help="Only `<cwd>/.npmrc`"

choice global help="Alias for `user`."

}

}

}

flag "-h --help" help="Print help" action=help builtin=#true

cmd delete help="Delete a key from aube config or the selected `.npmrc` file" effect=destructive {

alias rm

alias remove

alias unset

flag --local help="Shortcut for `--location project`." conflicts=--location

flag --location help="Which config location to act on." default=user {

long_help #"""

Which config location to act on.

Defaults to `user`. Delete sweeps both aube's own config (`~/.config/aube/config.toml` at user-scope, `<cwd>/.config/aube/config.toml` at project-scope) and the matching `.npmrc`, so the call works regardless of which file the value was originally written to.

"""#

arg <LOCATION> {

choices {

choice user help="User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)"

choice project help="`<cwd>/.npmrc`"

choice global help="Alias for `user` — aube has no separate global config file."

}

}

}

flag "-h --help" help="Print help" action=help builtin=#true

arg <KEY> help="The setting key." {

long_help #"""

The setting key.

Accepts either a pnpm canonical name (e.g. `autoInstallPeers`) or an `.npmrc` alias (e.g. `auto-install-peers`).

"""#

}

}

cmd explain help="Explain a known setting, including defaults and supported config sources" effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg <KEY> help="Setting key, `.npmrc` alias, env var, workspace YAML key, or CLI flag."

}

cmd find help="Search known settings by name, source key, or description" effect=read {

alias search

flag "-h --help" help="Print help" action=help builtin=#true

arg <QUERY>... help="Words to search for."

}

cmd get help="Print the effective value of a key" effect=read {

flag --json help="Emit the value as JSON." {

long_help #"""

Emit the value as JSON.

Matches `pnpm config get --json`: a missing key renders as `undefined`, a found value is JSON-encoded.

"""#

}

flag --local help="Shortcut for `--location project`." conflicts=--location

flag --location help="Which config location(s) to read." default=merged {

long_help #"""

Which config location(s) to read.

Defaults to `merged` — the last-write-wins view of user aube config, `~/.npmrc`, then `./.npmrc`, matching what install actually sees. Use `user` or `project` to restrict the lookup.

"""#

arg <LOCATION> {

choices {

choice merged help="Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses)."

choice user help="Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)"

choice project help="Only `<cwd>/.npmrc`"

choice global help="Alias for `user`."

}

}

}

flag "-h --help" help="Print help" action=help builtin=#true

arg <KEY> help="The setting key." {

long_help #"""

The setting key.

Accepts either a pnpm canonical name (e.g. `autoInstallPeers`) or an `.npmrc` alias (e.g. `auto-install-peers`).

"""#

}

}

cmd list help="Print every key/value from aube config and selected `.npmrc` file(s)" effect=read {

alias ls

flag --all help="Also list settings that have no value set." {

long_help #"""

Also list settings that have no value set.

Renders one row per setting in `settings.toml`, with the default and description shown for unset entries.

Only valid with `--location merged` (the default), since a per-file view can't distinguish "not set anywhere" from "set in the other file" and would render misleading defaults.

"""#

}

flag --json help="Emit all entries as a JSON object keyed by setting name." {

long_help #"""

Emit all entries as a JSON object keyed by setting name.

Matches `pnpm config list --json`. Honors `--all` and `--location` the same way the default text output does.

"""#

}

flag --local help="Shortcut for `--location project`." {

long_help #"""

Shortcut for `--location project`.

Conflicts with `--all` since `--all` only makes sense against the merged view — see the `--all` docs for why.

"""#

conflicts --location --all

}

flag --location help="Which config location(s) to list." {

long_help #"""

Which config location(s) to list.

`merged` (default) walks `~/.npmrc`, user aube config, then the project's `.npmrc` with last-write-wins precedence, matching how install reads config.

"""#

arg <LOCATION> {

choices {

choice merged help="Merge `~/.npmrc`, user aube config, and project `.npmrc`, last-write-wins (same precedence install uses)."

choice user help="Only user config (`~/.config/aube/config.toml` + `~/.npmrc`)"

choice project help="Only `<cwd>/.npmrc`"

choice global help="Alias for `user`."

}

}

}

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd set help="Write a key=value pair to aube config or the selected `.npmrc` file" effect=write {

flag --local help="Shortcut for `--location project`." conflicts=--location

flag --location help="Which config location to write to." default=user {

long_help #"""

Which config location to write to.

Defaults to `user`. Writes land in `.npmrc` for the npm-shared surface — per-host auth/cert templates, scoped registries, and settings tagged `npmShared = true` in the settings registry (`registry`, `proxy` / `https-proxy`, `engine-strict`, `ignore-scripts`, etc.) — so npm and yarn read the same value. Aube-only and pnpm-only settings, plus unknown keys, land in aube's own config (`~/.config/aube/config.toml` at user scope, `<cwd>/.config/aube/config.toml` at project scope) where sibling tools don't see them.

Dotted writes for aube map settings (`allowBuilds.<pkg>`, `overrides.<pkg>`, …) edit one entry at a time. At project scope (`--local`) they land in `pnpm-workspace.yaml#<map>.<entry>` or `package.json#aube.<map>.<entry>` if no workspace yaml exists, the same place install reads from. User-scope dotted writes for these maps error: aube only reads them per project.

"""#

arg <LOCATION> {

choices {

choice user help="User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)"

choice project help="`<cwd>/.npmrc`"

choice global help="Alias for `user` — aube has no separate global config file."

}

}

}

flag "-h --help" help="Print help" action=help builtin=#true

arg <KEY> help="Setting key (canonical name or `.npmrc` alias)."

arg <VALUE> help="Value to write. Stored verbatim after `key=`."

}

cmd tui help="Browse known settings in an interactive terminal UI" effect=write {

flag "-h --help" help="Print help" action=help builtin=#true

}

}

cmd create help="Scaffold a project from a `create-*` starter kit (via dlx)" {

use network-args

flag "-h --help" help="Print help" action=help builtin=#true

arg "[PARAMS]..." help="Template package name followed by any args to pass through to the scaffold binary." double_dash=automatic {

long_help #"""

Template package name followed by any args to pass through to the scaffold binary.

The first positional is the template; the rest are forwarded verbatim to `create-<template>`.

"""#

}

}

cmd dedupe help="Re-resolve the lockfile to collapse duplicate versions" effect=write {

flag --check help="Check whether dedupe would change the lockfile; don't write anything." {

long_help #"""

Check whether dedupe would change the lockfile; don't write anything.

Exits non-zero when dedupe would make changes — useful in CI.

"""#

}

use lockfile-args

use network-args

use virtual-store-args

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd deploy help="Deploy a workspace package into a target directory with deps inlined" effect=write {

flag "-D --dev" help="Install only `devDependencies`." {

long_help #"""

Install only `devDependencies`.

Implemented by stripping `dependencies` and `optionalDependencies` from the deployed `package.json` before install runs.

"""#

conflicts --prod --no-prod

}

flag --no-optional help="Skip `optionalDependencies`"

flag "-P --prod --production" help="Install only production dependencies (default)." {

long_help #"""

Install only production dependencies (default).

Accepted for pnpm compatibility.

"""#

}

flag --no-prod help="Deploy every dependency kind (production + dev + optional)." {

long_help #"""

Deploy every dependency kind (production + dev + optional).

Opts out of the implicit `--prod` deploy default. Useful when a deployed package needs its devDependencies at runtime (test harnesses, build-step deploys). Combine with `--no-optional` to drop optionals while keeping prod + dev. Mutually exclusive with `--prod` and `--dev`.

"""#

conflicts --prod --dev

}

flag --offline help="Fail if any metadata or tarball isn't already in the local cache." conflicts=--prefer-offline {

long_help #"""

Fail if any metadata or tarball isn't already in the local cache.

Never hits the network. Useful in multi-stage Dockerfiles where an earlier `aube install` already populated the store: deploy then reproduces a prod-only tree without re-fetching anything.

"""#

}

flag --prefer-offline help="Prefer cached metadata over revalidation; only hit the network on a miss." conflicts=--offline

use lockfile-args

use network-args

use virtual-store-args

flag "-h --help" help="Print help" action=help builtin=#true

arg <TARGET> help="Target directory to deploy into." {

long_help #"""

Target directory to deploy into.

Must be empty or not yet exist.

"""#

}

}

cmd deprecate help="Mark published versions of a package as deprecated on the registry" effect=write {

flag --dry-run help="Don't PUT anything — print which versions would be touched and exit."

flag --otp help="One-time password from a 2FA authenticator; sent as `npm-otp`." {

arg <CODE>

}

use network-args

flag "-h --help" help="Print help" action=help builtin=#true

arg <PACKAGE> help="Package spec: `name`, `name@version`, or `name@<range>`." {

long_help #"""

Package spec: `name`, `name@version`, or `name@<range>`.

Omitting the version deprecates every published version.

"""#

}

arg <MESSAGE> help="Deprecation message shown to installers." {

long_help #"""

Deprecation message shown to installers.

Pass an empty string to clear an existing deprecation (or use `aube undeprecate`).

"""#

}

}

cmd deprecations help="Report deprecated packages in the resolved dependency graph" effect=read {

flag --exit-code help="Exit with a non-zero status if any deprecations are found."

flag --json help="Emit JSON instead of the default text layout."

flag --transitive help="Include transitive dependencies as well as direct ones."

use network-args

flag "-h --help" help="Print help" action=help builtin=#true

}

cmd diag help="Diagnostic trace analysis (compare/analyze JSONL traces)" effect=read subcommand_required=#true {

flag "-h --help" help="Print help" action=help builtin=#true

cmd analyze help="Show critical path / starvation / per-pkg lifecycle from a saved trace." effect=read {

flag "-h --help" help="Print help" action=help builtin=#true

arg <PATH> help="Trace JSONL"

}

cmd compare help="Diff two diag JSONL traces and surface per-operation regressions." effect=read {

flag --min-delta-ms help="Minimum |Δsum_ms| to surface (default 50)" default="50" {

arg <MIN_DELTA_MS>

}

flag --min-pct help="Minimum |%change| to surface (default 10)" default="10" {

arg <MIN_PCT>

}

flag "-h --help" help="Print help" action=help builtin=#true

arg <A> help="Baseline trace"

arg <B> help="Comparison trace"

}

}

cmd dist-tag help="Manage package distribution tags on the registry" effect=read subcommand_required=#true {

alias dist-tags

use network-args

flag "-h --help" help="Print help" action=help builtin=#true

cmd add help="Add or update a dist-tag on a package." effect=write {

long_help #"""

Add or update a dist-tag on a package.

Spec must include a concrete version: `aube dist-tag add react@18.2.0 stable`. The tag argument defaults to `latest`.

"""#

flag --otp help="One-time password from a 2FA authenticator; sent as `npm-otp`." {

arg <OTP>

}

flag "-h --help" help="Print help" action=help builtin=#true

arg <SPEC> help="Package spec in `name@version` form (exact version required, ranges and tags aren't resolved here)."

arg "[TAG]" help="Tag to create or update. Defaults to `latest`."

}

cmd ls help="List every dist-tag for a package." effect=read {

long_help #"""

List every dist-tag for a package.

Reads the package name from `./package.json` when no argument is given.

"""#

flag "-h --help" help="Print help" action=help builtin=#true

arg "[PACKAGE]" help="Package name (no version)." {

long_help #"""

Package name (no version).

Defaults to the current project's `package.json` `name` field.

"""#