From 4069d0b9f5220e20935ab0bb526860f8c85fe686 Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Thu, 20 Aug 2026 08:07:45 +0000
Subject: [PATCH 1/4] fix(spec): preserve required root subcommands
---
argv/src/spec.rs | 6 ++++++
lib/src/spec/mod.rs | 8 ++++++++
usage-rs/tests/facade.rs | 9 +++++++++
3 files changed, 23 insertions(+)
diff --git a/argv/src/spec.rs b/argv/src/spec.rs
index 46c42996b..03858e9a3 100644
--- a/argv/src/spec.rs
+++ b/argv/src/spec.rs
@@ -1182,6 +1182,12 @@ impl Spec<'_> {
if self.root.cmd.allow_missing_positional {
writeln!(out, "allow_missing_positional #true")?;
}
+ // Root metadata is written separately from `write_command`, so keep the required
+ // subcommand bit here as well. Without it a required typed enum still parsed correctly,
+ // but its emitted portable spec rendered `[COMMAND]` and accepted an empty invocation.
+ if self.root.subcommand_required && !self.root.cmd.subcommands.is_empty() {
+ writeln!(out, "subcommand_required #true")?;
+ }
if let Some(heading) = self.root.subcommand_help_heading {
prop(out, "subcommand_help_heading", heading)?;
}
diff --git a/lib/src/spec/mod.rs b/lib/src/spec/mod.rs
index f3e331e4a..49fb6eb04 100644
--- a/lib/src/spec/mod.rs
+++ b/lib/src/spec/mod.rs
@@ -319,6 +319,9 @@ impl Spec {
"allow_missing_positional" => {
schema.cmd.allow_missing_positional = node.arg(0)?.ensure_bool()?;
}
+ "subcommand_required" => {
+ schema.cmd.subcommand_required = node.arg(0)?.ensure_bool()?;
+ }
"subcommand_help_heading" => {
schema.cmd.subcommand_help_heading = Some(node.arg(0)?.ensure_string()?);
}
@@ -644,6 +647,11 @@ impl Display for Spec {
node.push(true);
nodes.push(node);
}
+ if self.cmd.subcommand_required && !self.cmd.subcommands.is_empty() {
+ let mut node = KdlNode::new("subcommand_required");
+ node.push(true);
+ nodes.push(node);
+ }
if let Some(heading) = &self.cmd.subcommand_help_heading {
let mut node = KdlNode::new("subcommand_help_heading");
node.push(string_entry(None, heading));
diff --git a/usage-rs/tests/facade.rs b/usage-rs/tests/facade.rs
index 5864b84e3..e6b58c314 100644
--- a/usage-rs/tests/facade.rs
+++ b/usage-rs/tests/facade.rs
@@ -23,6 +23,15 @@ enum Command {
Version,
}
+#[test]
+fn required_root_subcommand_survives_spec_emission() {
+ let kdl = Ex::to_kdl();
+ assert!(kdl.contains("subcommand_required #true"), "{kdl}");
+
+ let spec: usage_parser::Spec = kdl.parse().expect("usage-lib should read derive output");
+ assert!(spec.cmd.subcommand_required);
+}
+
#[derive(Cli)]
#[command(bin = "negated-requirements", subcommand_negates_reqs)]
#[allow(dead_code)]
From 7503c6d9c8e52441ced7fb05f3165c277e4df82f Mon Sep 17 00:00:00 2001
From: default <216188+jdx@users.noreply.github.com>
Date: Thu, 20 Aug 2026 08:07:45 +0000
Subject: [PATCH 2/4] test(fleet): refresh typed adopter fixtures
---
PLAN.md | 12 +-
benches/fleet/README.md | 13 +-
benches/fleet/aube.usage.kdl | 4966 +++++++--------------
benches/fleet/communique.usage.kdl | 51 +-
benches/fleet/fnox.usage.kdl | 189 +-
benches/fleet/hk.usage.kdl | 868 ++--
benches/fleet/pitchfork.usage.kdl | 797 +---
benches/fleet/tak.usage.kdl | 97 +-
benches/shadows/aube/src/lib.rs | 5683 +++++++++++++++----------
benches/shadows/communique/src/lib.rs | 3 +-
benches/shadows/fnox/src/lib.rs | 69 +-
benches/shadows/hk/src/lib.rs | 1134 +++--
benches/shadows/pitchfork/src/lib.rs | 630 ++-
benches/shadows/tak/src/lib.rs | 143 +-
14 files changed, 7174 insertions(+), 7481 deletions(-)
diff --git a/PLAN.md b/PLAN.md
index 092422be8..d8fda3228 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -957,6 +957,11 @@ looking at the clap surface, not only at the spec.
`--usage-spec` solely to expose the new canonical metadata; that new entry
point has no clap-era behavior to preserve and is excluded from tak's
compatibility baseline.
+ The six completed typed adopters now supply current `usage-rs` fixtures and
+ regenerated shadows for hk, fnox, pitchfork, aube, tak, and communique. Their
+ delimiter, optional-value, relationship, and command-policy metadata is therefore
+ visible to the gate. mise remains on its clap-era fixture until its router port can
+ emit the replacement metadata.
- [x] **Docs and manpages on a fleet spec.** communique's checked-in spec and
the KDL its shadow emits render the same markdown (index and every
command) and the same manpage. usage-cli's own
@@ -1042,9 +1047,10 @@ a prerequisite for trying a CLI.
parsers. Adoption is measured by what it lets mise delete, listed below.
Do not start this until the clap-only rows in **Trying the fleet** that
mise actually uses are either implemented or accepted as lost.
-- [ ] **pitchfork** — not part of the five typed experiments, but already
- generates its spec from clap. It is the next small adopter after those
- experiment branches become mergeable.
+- [x] **pitchfork** — jdx/Pitchfork#754 removes clap, parses its typed command tree
+ with `usage-rs`, uses the built-in completion protocol, and passes its Rust and
+ bats suites against the stacked usage revision. Its refreshed spec is part of the
+ fleet gate alongside the five original typed experiments.
- [~] **Other languages** — Go now parses, validates, renders help and answers
completions from generated static tables, verified against the shared corpus.
JavaScript and Python implementations remain open.
diff --git a/benches/fleet/README.md b/benches/fleet/README.md
index 313d1a14f..710f17f65 100644
--- a/benches/fleet/README.md
+++ b/benches/fleet/README.md
@@ -2,10 +2,11 @@
One spec per jdx CLI, checked in as a fixture.
-Each is the output of that CLI's own `usage` subcommand — `clap_usage` over its clap
-definition — copied verbatim. They are here for the same reason `benches/mise.usage.kdl` is:
-the comparison needs a fixed input, and a reviewer needs to be able to read the diff when one
-of them changes.
+Each is the output of that CLI's own `usage` subcommand, copied verbatim. The fixtures now come
+from the typed `usage-rs` fleet rewrites; they therefore exercise the metadata the replacement
+actually emits instead of the subset an older `clap_usage` bridge could recover. They are here
+for the same reason `benches/mise.usage.kdl` is: the comparison needs a fixed input, and a
+reviewer needs to be able to read the diff when one of them changes.
## Why more than mise
@@ -26,5 +27,5 @@ None of the three is exotic. Each was simply outside one CLI's vocabulary.
These are snapshots, not links. A CLI that changes its own flags will not update the copy here,
and that is fine — the fixture's job is to hold a shape the renderers must agree on, not to
-track a moving target. Refresh one by re-running its `usage` subcommand and committing the
-diff, the same way `benches/mise.usage.kdl` is refreshed.
+track a moving target. Refresh one from its usage-migration branch by re-running its `usage`
+subcommand and committing the diff, the same way `benches/mise.usage.kdl` is refreshed.
diff --git a/benches/fleet/aube.usage.kdl b/benches/fleet/aube.usage.kdl
index 4266ecd3d..31c0cfda0 100644
--- a/benches/fleet/aube.usage.kdl
+++ b/benches/fleet/aube.usage.kdl
@@ -1,1329 +1,770 @@
-// @generated by usage-cli from clap metadata
+// @generated by usage-rs metadata
min_usage_version "4.0"
name aube
bin aube
-version "1.36.0"
about "A fast Node.js package manager"
-usage "Usage: aube [OPTIONS] [COMMAND]"
+external_subcommand #true
flag "-C --dir --cd --prefix" help="Change to directory before running (like `make -C` or `mise --cd`)" global=#true {
arg
}
-flag "-F --filter" help="Scope command execution to workspace packages matching PATTERN" var=#true global=#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.
-"""#
+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.\n\nSupports exact names (`my-pkg`), globs (`@scope/*`, `*-plugin`),\npaths (`./packages/api`), graph selectors (`pkg...`, `...pkg`),\ngit-ref selectors (`[origin/main]`), and exclusions (`!pkg`).\nRepeatable; matches are OR-ed.\n\nCurrently honored by `run`, `test`, `start`, `stop`, `restart`,\n`install`, `exec`, `list`, `publish`, `deploy`, `add`, `remove`,\n`update`, `why`, and implicit-script invocations."
arg
}
-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 "-r --recursive" help="Run the command across every workspace package." global=#true {
+ long_help "Run the command across every workspace package.\n\nEquivalent to `--filter=*`; if `--filter` is also given,\n`--recursive` is a no-op and the explicit filter wins. Honored\nby 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 "-V --version" help="Print version and check for updates." global=#true {
+ long_help "Print version and check for updates.\n\nManual flag so we can run the async update notifier alongside\nthe version print — clap's auto `Action::Version` exits inside\n`parse_from`, before the tokio runtime is built."
}
-flag --aggregate-output help="Group workspace command output after each package finishes" hide=#true global=#true {
- 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 --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.\n\nAccepted for pnpm compatibility; aube's workspace fanout is\ncurrently sequential, so output is already grouped."
}
-flag --color help="Force colored output even when stderr is not a TTY" global=#true {
- long_help #"""
-Force colored output even when stderr is not a TTY.
-
-Overrides `NO_COLOR` / `CLICOLOR=0`. Mutually exclusive with `--no-color`.
-"""#
+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.\n\nOverrides `NO_COLOR` / `CLICOLOR=0`. Mutually exclusive with\n`--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 {
- 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
+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:\n summary — sum_ms / mean / max / %wall table at end\n trace — summary + critical path + starvation + what-if + lifecycle\n live — like trace, plus print every span >= 100ms to stderr live\n full — like trace, plus write JSONL trace to a file (defaults to ./aube-diag.jsonl)\n\nQuick form: `--diag` with no value defaults to `trace`.\nOutput file path can be set via `--diag-file`. Threshold for live\nmode 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
}
-flag --diag-threshold-ms help="Live-mode threshold: only print spans whose duration is >= N ms (default 100)" global=#true {
+flag --diag-threshold-ms help="Live-mode threshold: only print spans whose duration is >= N ms (default 100)." global=#true {
arg
}
-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 --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.\n\nAccepted globally; selected commands already fail on empty matches."
}
-flag --filter-prod help="Production-only variant of `--filter`" var=#true global=#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`.
-"""#
+flag --filter-prod help="Production-only variant of `--filter`." global=#true var=#true {
+ long_help "Production-only variant of `--filter`.\n\nSame selector grammar as `--filter`, but graph walks (`pkg...`,\n`...pkg`) only follow `dependencies` / `optionalDependencies` /\n`peerDependencies` edges — `devDependencies` (and packages\nreachable solely through them) are skipped. Non-graph forms\n(exact name, glob, path, `[git-ref]`) behave identically to\n`--filter`. Repeatable; can be combined with `--filter`."
arg
}
-flag --ignore-workspace help="Ignore workspace discovery for commands that support workspace fanout" hide=#true global=#true {
- long_help #"""
-Ignore workspace discovery for commands that support workspace fanout.
-
-Parsed for pnpm compatibility.
-"""#
+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.\n\nParsed for pnpm compatibility."
}
-flag --include-workspace-root help="Include the workspace root in recursive workspace operations" hide=#true global=#true {
- long_help #"""
-Include the workspace root in recursive workspace operations.
-
-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.\n\nParsed for pnpm compatibility."
}
-flag --loglevel help="Set the log level. Logs at or above this level are shown" global=#true {
+flag --loglevel help="Set the log level. Logs at or above this level are shown." global=#true {
arg {
- choices trace debug info warn error silent
+ 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 --no-color help="Disable colored output." global=#true {
+ long_help "Disable colored output.\n\nOverrides `FORCE_COLOR` / `CLICOLOR_FORCE` and sets `NO_COLOR=1`\nso downstream libraries (miette, clx, child processes) all see\nthe 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`).
-"""#
+flag --reporter help="Output format: default, append-only, ndjson, silent." global=#true {
+ long_help "Output format: default, append-only, ndjson, silent.\n\n`default` renders the progress UI when stderr is a TTY;\n`append-only` disables the progress UI in favor of plain\nline-at-a-time logs; `ndjson` swaps the tracing fmt layer for\nthe JSON formatter (one JSON object per log event on stderr)\nand is what tooling wrappers should consume; `silent`\nsuppresses all non-error output (alias for `--loglevel silent`)."
arg {
- choices default append-only ndjson silent
+ 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" hide=#true global=#true {
- long_help #"""
-Stream workspace command output as each child process writes it.
-
-Accepted for pnpm compatibility; aube's workspace fanout is currently sequential.
-"""#
+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.\n\nAccepted for pnpm compatibility; aube's workspace fanout is\ncurrently sequential."
}
-flag --use-stderr help="Route lifecycle and workspace command output through stderr" hide=#true global=#true {
- long_help #"""
-Route lifecycle and workspace command output through stderr.
-
-Accepted for pnpm compatibility.
-"""#
+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.\n\nAccepted for pnpm compatibility."
}
-flag --workspace-packages help="Prefer workspace packages when resolving dependencies" hide=#true global=#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-packages help="Prefer workspace packages when resolving dependencies." global=#true hide=#true {
+ long_help "Prefer workspace packages when resolving dependencies.\n\nParsed for pnpm compatibility; aube already resolves workspace\npackages 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" hide=#true global=#true {
- long_help #"""
-Automatically answer yes to prompts.
-
-Parsed for pnpm compatibility; aube does not currently prompt on these paths.
-"""#
+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.\n\nParsed for pnpm compatibility; aube does not currently prompt\non these paths."
}
-cmd __node-gyp-bootstrap hide=#true help="Bootstrap aube's cached node-gyp and print the executable path" effect=write {
+cmd __node-gyp-bootstrap help="Bootstrap aube's cached node-gyp and print the executable path." hide=#true effect=write {
arg
}
-cmd access subcommand_required=#true help="Manage package access and visibility on the registry" effect=read {
- 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`" {
+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
}
- flag --fetch-retries help="Number of retry attempts for failed registry fetches" {
- 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.
-"""#
+ 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.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs."
arg
}
- flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" {
- 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 clap.
-"""#
+ flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network {
+ long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser."
arg
}
- flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" {
- long_help #"""
-Upper bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" {
- long_help #"""
-Lower bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" {
- 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.
-"""#
+ flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network {
+ long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together."
arg
}
- flag --registry help="Override the default registry URL for this invocation" {
- 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.
-"""#
+ flag --registry help="Override the default registry URL for this invocation." help_heading=Network {
+ long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes."
arg
}
- cmd get subcommand_required=#true help="Get package visibility status" effect=read {
- cmd status help="Get a package's public or restricted status" effect=read {
- arg help="Package name"
+ cmd get help="Get package visibility status." effect=read subcommand_required=#true {
+ cmd status help="Get a package's public or restricted status." effect=read {
+ arg help="Package name."
}
}
- cmd grant help="Grant a team read-only or read-write access to a package" effect=write {
- arg help="`read-only` or `read-write`"
- arg help="Team in `@scope:team` form"
- arg help="Package name"
+ cmd grant help="Grant a team read-only or read-write access to a package." effect=write {
+ arg help="`read-only` or `read-write`."
+ arg help="Team in `@scope:team` form."
+ arg help="Package name."
}
- cmd list subcommand_required=#true help="List packages visible to a user, organization, or team" effect=read {
- cmd collaborators help="List collaborators for a package, optionally filtering to one user" effect=read {
- arg help="Package name"
- arg "[USER]" help="Optional user name" required=#false
+ cmd list help="List packages visible to a user, organization, or team." effect=read subcommand_required=#true {
+ cmd collaborators help="List collaborators for a package, optionally filtering to one user." effect=read {
+ arg 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 {
- arg "[ENTITY]" help="User, `@organization`, or `@scope:team`" required=#false
+ cmd packages help="List packages visible to the current user or an optional entity." effect=read {
+ arg "[ENTITY]" help="User, `@organization`, or `@scope:team`."
}
}
- cmd ls help="Alias for `list packages`" effect=read {
- 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]`" required=#false var=#true
+ cmd ls help="Alias for `list packages`." effect=read {
+ 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 {
+ long_help "User, `@organization`, or `@scope:team`. Also accepts pnpm's\n`packages [ENTITY]` compatibility form. Accepted forms are\n`aube access ls [ENTITY]` and `aube access ls packages [ENTITY]`."
+ }
}
- cmd revoke help="Revoke a team's access to a package" effect=destructive {
- arg help="Team in `@scope:team` form"
- arg help="Package name"
+ cmd revoke help="Revoke a team's access to a package." effect=destructive {
+ arg help="Team in `@scope:team` form."
+ arg help="Package name."
}
- cmd set help="Set package visibility or a publish MFA requirement" effect=write {
- arg help="`status=public|private|restricted` or `mfa=none|publish|automation`"
- arg help="Package name"
+ cmd set help="Set package visibility or a publish MFA requirement." effect=write {
+ arg help="`status=public|private|restricted` or `mfa=none|publish|automation`."
+ arg help="Package name."
}
}
cmd activate help="Emit shell activation code for runtime tool shims" effect=write {
- arg help="Shell to emit activation code for" {
- choices bash fish zsh
- }
+ arg 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 "-g --global" help="Install the package globally." {
+ long_help "Install the package globally.\n\nInstalls into the aube/pnpm global directory and links its\nbinaries 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 {
- long_help #"""
-Pre-approve a dependency's lifecycle scripts as part of the add.
-
-Writes `allowBuilds: { : 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=`.
-
-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
+ 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.\n\nWrites `allowBuilds: { : true }` into the workspace yaml\n(or `package.json#aube.allowBuilds`) before the install runs,\nso the named package's `preinstall` / `install` / `postinstall`\nscripts execute on this invocation. Repeatable — pass the flag\nonce per package. Mirrors `pnpm add --allow-build=`.\n\nConflicts with `--no-save`, which only snapshots `package.json`\nand the lockfile and would leave an orphaned approval in the\nworkspace yaml on restore. Also conflicts with `--deny-build` for\nthe same package name."
+ arg 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 --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`]\nconfirm prompts / refusals for this invocation.\n\n`aube add` looks up each candidate's weekly download count and\nprompts (interactive) or fails (CI) when the count is below\n[`lowDownloadThreshold`], resembles a top-100,000 npm package,\nor is newer than [`minimumPackageAge`]. The flag is intended\nfor cases where you've already verified the package out-of-band.\nIt does not affect the OSV malicious-package check, which remains\na 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 --dangerously-allow-all-builds help="Allow every dependency's lifecycle scripts to run." {
+ long_help "Allow every dependency's lifecycle scripts to run.\n\nBypasses the `allowBuilds` allowlist for this invocation. Do not\nuse 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 {
- long_help #"""
-Mark a dependency's lifecycle scripts as reviewed and denied.
-
-Writes `allowBuilds: { : 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`.
-"""#
- arg
- }
- 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`" {
- 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 --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.\n\nWrites `allowBuilds: { : false }` into the workspace yaml\n(or `package.json#aube.allowBuilds`) before the install runs,\nso the named package's lifecycle scripts stay skipped without\ntripping `strictDepBuilds=true`. Repeatable — pass the flag\nonce per package.\n\nConflicts with `--no-save`, which only snapshots `package.json`\nand the lockfile and would leave an orphaned denial in the\nworkspace yaml on restore. Also conflicts with `--allow-build` for\nthe same package name and with `--dangerously-allow-all-builds`."
+ conflicts --no-save --dangerously-allow-all-builds
+ arg 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 --no-save-workspace-protocol help="Inverse of `--save-workspace-protocol`" {
- long_help #"""
-Inverse of `--save-workspace-protocol`.
-
-Forces the manifest specifier into a registry-style spec (`^`) 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 --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`.\n\nSnapshots `package.json` and the lockfile, links the named\npackages into `node_modules`, and then restores both files —\nso the dependency is usable for the current process but the\nproject's committed state is untouched.\n\nHandy for one-off experiments and for scripts that install a\ntool transiently. Mirrors `pnpm add --no-save`. Conflicts with\n`-g`/`--global`, which has to persist the install to its global\nmanifest."
}
- 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.
-"""#
+ flag --no-save-workspace-protocol help="Inverse of `--save-workspace-protocol`." overrides=--save-workspace-protocol {
+ long_help "Inverse of `--save-workspace-protocol`.\n\nForces the manifest specifier into a registry-style spec\n(`^`) for this invocation, even when\n`linkWorkspacePackages` matched a local sibling. The install\npipeline still prefers the local workspace copy at resolve\ntime — this flag only controls what's written to\n`package.json`. Mirrors `pnpm add --no-save-workspace-protocol`."
}
- flag --save-catalog-name help="Save the new dependency into a *named* catalog" {
- long_help #"""
-Save the new dependency into a *named* catalog.
-
-Writes the entry to `catalogs.` in the workspace yaml and `catalog:` into `package.json`. Same workspace/alias exclusions and `--no-save` conflict as `--save-catalog`. Mirrors `pnpm add --save-catalog-name=`.
-"""#
+ 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.\n\nWrites `catalog:` into `package.json` and seeds/upserts the\nresolved range under `catalog:` in the workspace yaml. Mirrors\n`pnpm add --save-catalog`.\n\nWorkspace and aliased specs (`workspace:*`, `npm:`, `jsr:`) are\nnever catalogized — the manifest gets the original spec and\nthe catalog yaml is left alone. If the package is already in\nthe target catalog, the existing entry is preserved (never\noverwritten); the manifest then gets `catalog:` only when the\nexisting entry is compatible with the user's range.\n\nConflicts with `--no-save`: catalog mutations write to the\nworkspace yaml, which the `--no-save` restore path doesn't\nsnapshot — combining the two would silently leave an orphaned\ncatalog 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.\n\nWrites the entry to `catalogs.` in the workspace yaml and\n`catalog:` into `package.json`. Same workspace/alias\nexclusions and `--no-save` conflict as `--save-catalog`. Mirrors\n`pnpm add --save-catalog-name=`."
arg
}
- flag --save-peer help="Add as a peer dependency (written to `peerDependencies` in package.json)" {
- 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-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\npackage.json).\n\nBy convention you usually pair this with `--save-dev` so the\npeer is also installed for local development; that's what pnpm\ndoes."
}
- flag --save-workspace-protocol help="Force the manifest specifier into `workspace:` form for this invocation, overriding `saveWorkspaceProtocol` from the workspace yaml / `.npmrc` / env" {
- 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:^` (pinned), depending on the resolved `saveWorkspaceProtocol` value.
-"""#
+ 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\ninvocation, overriding `saveWorkspaceProtocol` from the\nworkspace yaml / `.npmrc` / env.\n\nOnly meaningful when `linkWorkspacePackages` (or a workspace\nsibling already exists for the named package). With this flag\nthe entry written to `package.json` is `workspace:^` (rolling)\nor `workspace:^` (pinned), depending on the resolved\n`saveWorkspaceProtocol` value."
}
- flag "-w --workspace" help="Add the dependency to the workspace root's `package.json`" {
- 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 --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`.\n\nApplies regardless of the current working directory: walks up\nfrom cwd looking for `aube-workspace.yaml`, `pnpm-workspace.yaml`,\nor a `package.json` with a `workspaces` field and runs the add\nagainst 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`.
-"""#
- }
- flag --frozen-lockfile help="Error if the lockfile drifts from package.json"
- flag --no-frozen-lockfile help="Always re-resolve, even if the lockfile is up to date"
- flag --prefer-frozen-lockfile help="Use the lockfile when fresh, re-resolve when stale"
- flag --fetch-retries help="Number of retry attempts for failed registry fetches" {
- 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.
-"""#
+ 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.\n\nBy default aube refuses to add dependencies to the root\n`package.json` of a workspace (a directory containing\n`aube-workspace.yaml`, `pnpm-workspace.yaml`, or a `package.json`\nwith a `workspaces` field) because deps added there end up\nshared by every package and usually reflect a mistake. Pass\nthis flag to opt in. Mirrors `pnpm add -W`."
+ }
+ 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
+ }
+ 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.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs."
arg
}
- flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" {
- 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 clap.
-"""#
+ flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network {
+ long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser."
arg
}
- flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" {
- long_help #"""
-Upper bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" {
- long_help #"""
-Lower bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" {
- 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.
-"""#
+ flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network {
+ long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together."
arg
}
- flag --registry help="Override the default registry URL for this invocation" {
- 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.
-"""#
+ flag --registry help="Override the default registry URL for this invocation." help_heading=Network {
+ long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes."
arg
}
- flag "--disable-global-virtual-store --disable-gvs" help="Force the shared global virtual store off for this invocation" {
- 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 "--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.\n\nPackages are materialized inside the project's virtual store\ninstead 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" {
- 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.
-"""#
+ 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.\n\nOverrides CI's default per-project materialization and the\n`disableGlobalVirtualStoreForPackages` auto-disable heuristic."
}
- arg "[PACKAGES]…" help="Package(s) to add" required=#false var=#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"
- arg "[PKG]…" help="Packages to approve directly, skipping the picker" help_long=#"""
-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.
-"""# required=#false var=#true
+cmd approve-builds help="Approve ignored dependency build scripts." effect=write {
+ long_help "Approve ignored dependency build scripts.\n\nWrites entries under `allowBuilds` in `aube-workspace.yaml` (or\n`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."
+ arg "[PKG]..." help="Packages to approve directly, skipping the picker." {
+ long_help "Packages to approve directly, skipping the picker.\n\nEach name must match a currently-ignored build. Unknown names\nare rejected so a typo cannot silently no-op."
+ }
}
cmd audit help="Check installed packages against the registry advisory DB" effect=read {
- after_long_help #"""
-Examples:
-
- $ aube audit
- Severity Package Vulnerable Title
- moderate minimatch <3.0.5 Regular Expression Denial of Service
- https://github.com/advisories/GHSA-f8q6-p94x
-
- 1 vulnerability found
-
- # Only fail on high and above
- $ aube audit --audit-level high
-
- # Skip optional deps and dev deps
- $ aube audit --prod --no-optional
-
- # Pipe into jq
- $ aube audit --json | jq '.advisories | length'
-
- # Clean
- $ aube audit
- No known vulnerabilities found
-
-"""#
- 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`.
-"""#
+ flag --audit-level help="Only print advisories at or above this severity." {
+ long_help "Only print advisories at or above this severity.\n\nOne of: `info`, `low`, `moderate`, `high`, `critical`.\nDefaults to `audit.level` (or legacy `auditLevel`), then `low`."
arg {
- choices info low moderate high critical
+ choices {
+ choice info
+ choice low
+ choice moderate
+ choice high
+ choice critical
+ }
}
}
- flag "-D --dev" help="Only audit `devDependencies`"
- flag --fix help="Fix advisories" {
- long_help #"""
-Fix advisories.
-
-Bare `--fix` writes package.json overrides for backwards compatibility. `--fix=update` refreshes the lockfile without writing overrides.
-"""#
- arg {
- choices update override
+ flag "-D --dev" help="Only audit `devDependencies`." conflicts=--prod
+ flag --fix help="Fix advisories." value_optional=#true default_missing=override {
+ long_help "Fix advisories.\n\nBare `--fix` writes package.json overrides for backwards compatibility.\n`--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 {
- 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.
-"""#
+ 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.\n\nMatches against the numeric npm advisory `id`,\n`github_advisory_id` (`GHSA-…`), and any entry in `cves[]`\n(case-insensitive). Repeatable; comma-separated values are also\naccepted."
arg
}
- 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-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.\n\nUseful 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 --ignore-unfixable help="Drop advisories that have no non-vulnerable upgrade." {
+ long_help "Drop advisories that have no non-vulnerable upgrade.\n\nFilters out advisories for which no non-vulnerable version is\navailable in the package's packument. Same \"best non-vulnerable\"\nlogic as `--fix`: an advisory is kept only when an upgrade path\nexists."
}
- 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`"
- flag --fetch-retries help="Number of retry attempts for failed registry fetches" {
- 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.
-"""#
+ 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
+ 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.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs."
arg
}
- flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" {
- 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 clap.
-"""#
+ flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network {
+ long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser."
arg
}
- flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" {
- long_help #"""
-Upper bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" {
- long_help #"""
-Lower bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" {
- 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.
-"""#
+ flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network {
+ long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together."
arg
}
- flag --registry help="Override the default registry URL for this invocation" {
- 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.
-"""#
+ flag --registry help="Override the default registry URL for this invocation." help_heading=Network {
+ long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes."
arg
}
}
cmd bin help="Print the path to `node_modules/.bin`" effect=read {
- after_long_help #"""
-Examples:
-
- $ aube bin
- /home/user/project/node_modules/.bin
-
- $ aube bin -g
- /home/user/.local/share/aube/global/node_modules/.bin
-
- # From a workspace package, -w prints the workspace-root bin directory
- $ cd packages/app
- $ aube bin
- /home/user/project/packages/app/node_modules/.bin
- $ aube bin -w
- /home/user/project/node_modules/.bin
-
- # Extend PATH with the project bin directory
- $ export PATH="$(aube bin):$PATH"
-
-"""#
- flag "-g --global" help="Print the global bin directory instead of the project's"
- 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 "-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\npackage's.\n\nMirrors `pnpm bin -w`: from a sub-package, resolves the enclosing\nworkspace root and prints its `node_modules/.bin`. No-op when no\nworkspace root exists above cwd (single-project install), so the\nflag is safe to leave in shell aliases."
}
}
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
-
-"""#
- flag --fetch-retries help="Number of retry attempts for failed registry fetches" {
- 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.
-"""#
+ after_long_help "Examples:\n\n $ aube bugs\n\n $ aube bugs react\n\n $ aube issues react react-dom\n"
+ 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.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs."
arg
}
- flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" {
- 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 clap.
-"""#
+ flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network {
+ long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser."
arg
}
- flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" {
- long_help #"""
-Upper bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" {
- long_help #"""
-Lower bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" {
- 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.
-"""#
+ flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network {
+ long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together."
arg
}
- flag --registry help="Override the default registry URL for this invocation" {
- 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.
-"""#
+ flag --registry help="Override the default registry URL for this invocation." help_heading=Network {
+ long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes."
arg
}
- arg "[PACKAGES]…" help="Packages to open bug trackers for. Defaults to the current project" required=#false var=#true
+ arg "[PACKAGES]..." help="Packages to open bug trackers for. Defaults to the current project."
}
-cmd cache subcommand_required=#true help="Inspect and manage the packument metadata cache" effect=read {
- 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/*`).
-"""#
- arg … help="One or more package name patterns" help_long=#"""
-One or more package name patterns.
-
-Glob metacharacters (`*`, `?`, `[...]`) are supported.
-"""# var=#true
+cmd cache help="Inspect and manage the packument metadata cache" effect=read subcommand_required=#true {
+ cmd delete help="Delete metadata cache for the specified package(s)." effect=write {
+ long_help "Delete metadata cache for the specified package(s).\n\nSupports glob patterns; matches against the package name (e.g.\n`lodash`, `@babel/*`)."
+ arg ... help="One or more package name patterns." {
+ long_help "One or more package name patterns.\n\nGlob 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.
-"""#
- arg "[PATTERNS]…" help="Optional glob patterns to filter the listing" help_long=#"""
-Optional glob patterns to filter the listing.
-
-With no patterns, every cached package is printed.
-"""# required=#false var=#true
+ cmd list help="List the available packages in the metadata cache." effect=read {
+ long_help "List the available packages in the metadata cache.\n\nOptional glob filters narrow the result; with no filter every\ncached package is listed."
+ arg "[PATTERNS]..." help="Optional glob patterns to filter the listing." {
+ long_help "Optional glob patterns to filter the listing.\n\nWith 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.
-"""#
+ cmd list-registries help="List configured registries from the project + user `.npmrc`." effect=read {
+ long_help "List configured registries from the project + user `.npmrc`.\n\nAube stores all packuments in a single flat directory (unlike\npnpm's per-host layout), so this prints the registries you're\ncurrently configured to talk to rather than the registries that\nhappen to be in the cache."
}
- 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" {
+ cmd path help="Print the directory used for metadata and policy caches." effect=read {
+ }
+ 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
}
- flag --dry-run help="Do not actually delete anything"
+ flag --dry-run help="Do not actually delete anything."
}
- 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"
- arg help="Package name (scoped names like `@babel/core` are accepted)"
+ cmd view help="View the cached metadata for a single package." effect=read {
+ long_help "View the cached metadata for a single package.\n\nPrints a summary (versions, dist-tags, ETag, fetched-at) by\ndefault; `--json` dumps the raw cache file."
+ flag --json help="Dump the raw on-disk cache JSON instead of a summary."
+ arg 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 {
- arg help="File hash to look up" help_long=#"""
-File hash to look up.
-
-Accepts `sha512-` (pnpm integrity format) or a raw hex CAS digest.
-"""#
+ arg help="File hash to look up." {
+ long_help "File hash to look up.\n\nAccepts `sha512-` (pnpm integrity format) or a raw hex\nCAS digest."
+ }
}
cmd cat-index help="Print the cached package index JSON for `@`" effect=read {
- arg help="Package to inspect, in `name@version` form (e.g. `lodash@4.17.21`, `@babel/core@7.26.0`)" help_long=#"""
-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.
-"""#
+ arg 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`,\n`@babel/core@7.26.0`).\n\nAn exact version is required — ranges and dist-tags aren't\nresolved 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.
-"""#
- after_long_help #"""
-Examples:
-
- $ aube check
- node_modules symlink tree is consistent (checked 248 packages).
-
- # With issues
- $ aube check
- 2 broken dependency links found:
-
- vscode-languageserver@9.0.1
- ✕ cannot resolve: vscode-languageserver-protocol@3.17.5
-
- vscode-languageserver-protocol@3.17.5
- ✕ cannot resolve: vscode-languageserver-types@3.17.5
- ✕ cannot resolve: vscode-jsonrpc@8.2.1
-
- # Machine-readable
- $ aube check --json
-
-"""#
- flag --json help="Emit a JSON report instead of the human-readable list"
+cmd check help="Verify installed packages can resolve their declared deps." effect=read {
+ long_help "Verify installed packages can resolve their declared deps.\n\nWalks the `node_modules/` symlink tree and confirms every\ndependency in each `package.json` resolves to a real entry."
+ flag --json help="Emit a JSON report instead of the human-readable list."
}
-cmd ci help="Clean install: delete node_modules, then install with frozen lockfile" effect=write {
+cmd ci help="Clean install: delete node_modules, then install with frozen lockfile." effect=write {
alias clean-install
- alias ic install-clean hide=#true
- long_help #"""
-Clean install: delete node_modules, then install with frozen lockfile.
-
-Use in CI to guarantee a reproducible install from the committed lockfile.
-"""#
+ alias ic
+ alias install-clean
+ long_help "Clean install: delete node_modules, then install with frozen lockfile.\n\nUse 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"
- flag --frozen-lockfile help="Error if the lockfile drifts from package.json"
- flag --no-frozen-lockfile help="Always re-resolve, even if the lockfile is up to date"
- flag --prefer-frozen-lockfile help="Use the lockfile when fresh, re-resolve when stale"
- flag --fetch-retries help="Number of retry attempts for failed registry fetches" {
- 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.
-"""#
+ 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
+ }
+ 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.\n\nOverrides `fetchRetries` / `fetch-retries` from `.npmrc` /\n`aube-workspace.yaml` when set. Pair with `--fetch-timeout` to\nfail fast in scripted test runs."
arg
}
- flag --fetch-retry-factor help="Exponential backoff factor between retry attempts" {
- 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 clap.
-"""#
+ flag --fetch-retry-factor help="Exponential backoff factor between retry attempts." help_heading=Network {
+ long_help "Exponential backoff factor between retry attempts.\n\nOverrides `fetchRetryFactor` / `fetch-retry-factor` from\n`.npmrc` / `aube-workspace.yaml` when set. Integer-only — the\nunderlying `FetchPolicy.retry_factor` is `u32`. Fractional\nvalues like `1.5` are rejected by the CLI parser."
arg
}
- flag --fetch-retry-maxtimeout help="Upper bound (ms) on the computed retry backoff" {
- long_help #"""
-Upper bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMaxtimeout` / `fetch-retry-maxtimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-retry-mintimeout help="Lower bound (ms) on the computed retry backoff" {
- long_help #"""
-Lower bound (ms) on the computed retry backoff.
-
-Overrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from `.npmrc` / `aube-workspace.yaml` when set.
-"""#
+ 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.\n\nOverrides `fetchRetryMintimeout` / `fetch-retry-mintimeout` from\n`.npmrc` / `aube-workspace.yaml` when set."
arg
}
- flag --fetch-timeout help="Per-request HTTP timeout in milliseconds" {
- 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.
-"""#
+ flag --fetch-timeout help="Per-request HTTP timeout in milliseconds." help_heading=Network {
+ long_help "Per-request HTTP timeout in milliseconds.\n\nOverrides `fetchTimeout` / `fetch-timeout` from `.npmrc` /\n`aube-workspace.yaml` when set. Applied via `reqwest`'s\n`.timeout()` so it covers headers + body together."
arg
}
- flag --registry help="Override the default registry URL for this invocation" {
- 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.
-"""#
+ flag --registry help="Override the default registry URL for this invocation." help_heading=Network {
+ long_help "Override the default registry URL for this invocation.\n\nUse this npm registry URL for package metadata, tarballs,\naudit requests, dist-tags, and registry writes."
arg
}
- flag "--disable-global-virtual-store --disable-gvs" help="Force the shared global virtual store off for this invocation" {
- 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 "--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.\n\nPackages are materialized inside the project's virtual store\ninstead 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" {
- 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.
-"""#
+ 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.\n\nOverrides CI's default per-project materialization and the\n`disableGlobalVirtualStoreForPackages` auto-disable heuristic."
}
}
-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`.
-"""#
+cmd clean help="Remove `node_modules` across every workspace project." effect=write {
+ long_help "Remove `node_modules` across every workspace project.\n\n`--lockfile` / `-l` also deletes lockfiles. A `clean` script in\nthe 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.\n\nTargets `aube-lock.yaml`, `pnpm-lock.yaml`, `package-lock.json`,\n`npm-shrinkwrap.json`, `yarn.lock`, and `bun.lock`."
}
}
cmd completion help="Generate shell completions (bash, zsh, fish)" effect=read {
- flag --complete help="Emit dynamic candidates for the shell completion engine" hide=#true {
- arg {
- choices package bin workspace setting patch
- }
- }
- flag --query help="Current word being completed" hide=#true default="" {
- arg
- }
arg help="The shell to generate completions for (bash, zsh, fish)"
}
cmd config help="Read and write settings in `.npmrc`" effect=read {
- alias c hide=#true
- 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.
-"""#
+ alias c
+ flag --all help="Also list settings that have no value set." {
+ long_help "Also list settings that have no value set.\n\nRenders one row per setting in `settings.toml`, with the\ndefault and description shown for unset entries.\n\nOnly valid with `--location merged` (the default), since a\nper-file view can't distinguish \"not set anywhere\" from \"set in\nthe 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 --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.\n\nMatches `pnpm config list --json`. Honors `--all` and\n`--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.
-"""#
+ flag --local help="Shortcut for `--location project`." {
+ long_help "Shortcut for `--location project`.\n\nConflicts with `--all` since `--all` only makes sense against\nthe 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.
-"""#
+ flag --location help="Which config location(s) to list." {
+ long_help "Which config location(s) to list.\n\n`merged` (default) walks `~/.npmrc`, user aube config, then\nthe project's `.npmrc` with last-write-wins precedence,\nmatching how install reads config."
arg {
- choices merged user project global
+ 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 `/.npmrc`"
+ choice global help="Alias for `user`."
+ }
}
}
cmd delete help="Delete a key from aube config or the selected `.npmrc` file" effect=destructive {
- alias rm remove unset
- flag --local help="Shortcut for `--location project`"
- 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, `/.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.
-"""#
+ 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.\n\nDefaults to `user`. Delete sweeps both aube's own config\n(`~/.config/aube/config.toml` at user-scope,\n`/.config/aube/config.toml` at project-scope) and the\nmatching `.npmrc`, so the call works regardless of which file\nthe value was originally written to."
arg {
- choices user project global
+ choices {
+ choice user help="User config (`~/.config/aube/config.toml` for known aube settings, `~/.npmrc` for registry/auth and unknown keys)"
+ choice project help="`/.npmrc`"
+ choice global help="Alias for `user` — aube has no separate global config file."
+ }
}
}
- arg help="The setting key" help_long=#"""
-The setting key.
-
-Accepts either a pnpm canonical name (e.g. `autoInstallPeers`) or an `.npmrc` alias (e.g. `auto-install-peers`).
-"""#
+ arg help="The setting key." {
+ long_help "The setting key.\n\nAccepts either a pnpm canonical name (e.g. `autoInstallPeers`)\nor an `.npmrc` alias (e.g. `auto-install-peers`)."
+ }
}
cmd explain help="Explain a known setting, including defaults and supported config sources" effect=read {
- arg help="Setting key, `.npmrc` alias, env var, workspace YAML key, or CLI flag"
+ arg 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
- arg … help="Words to search for" var=#true
+ arg ... 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 --json help="Emit the value as JSON." {
+ long_help "Emit the value as JSON.\n\nMatches `pnpm config get --json`: a missing key renders as\n`undefined`, a found value is JSON-encoded."
}
- flag --local help="Shortcut for `--location project`"
- 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.
-"""#
+ 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.\n\nDefaults to `merged` — the last-write-wins view of user aube\nconfig, `~/.npmrc`, then `./.npmrc`, matching what install\nactually sees. Use `user` or `project` to restrict the lookup."
arg {
- choices merged user project global
+ 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 `/.npmrc`"
+ choice global help="Alias for `user`."
+ }
}
}
- arg help="The setting key" help_long=#"""
-The setting key.
-
-Accepts either a pnpm canonical name (e.g. `autoInstallPeers`) or an `.npmrc` alias (e.g. `auto-install-peers`).
-"""#
+ arg help="The setting key." {
+ long_help "The setting key.\n\nAccepts either a pnpm canonical name (e.g. `autoInstallPeers`)\nor 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 --all help="Also list settings that have no value set." {
+ long_help "Also list settings that have no value set.\n\nRenders one row per setting in `settings.toml`, with the\ndefault and description shown for unset entries.\n\nOnly valid with `--location merged` (the default), since a\nper-file view can't distinguish \"not set anywhere\" from \"set in\nthe 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 --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.\n\nMatches `pnpm config list --json`. Honors `--all` and\n`--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.
-"""#
+ flag --local help="Shortcut for `--location project`." {
+ long_help "Shortcut for `--location project`.\n\nConflicts with `--all` since `--all` only makes sense against\nthe 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.
-"""#
+ flag --location help="Which config location(s) to list." {
+ long_help "Which config location(s) to list.\n\n`merged` (default) walks `~/.npmrc`, user aube config, then\nthe project's `.npmrc` with last-write-wins precedence,\nmatching how install reads config."
arg {
- choices merged user project global
+ 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 `/.npmrc`"
+ choice global help="Alias for `user`."
+ }
}
}
}
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`"
- 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, `/.config/aube/config.toml` at project scope) where sibling tools don't see them.
-
-Dotted writes for aube map settings (`allowBuilds.`, `overrides.`, …) edit one entry at a time. At project scope (`--local`) they land in `pnpm-workspace.yaml#