aube · diff

git:20260906.3c6592e to git:20260912.01a02ee

11 added, 4 removed. Audit B to B.

---

name: aube

description: >-

Use when managing a Node.js project's dependencies or scripts with aube

(https://aube.sh/), or migrating a project from pnpm, npm, or bun to

aube — including its lockfile, CI, lifecycle-script jail, and Dependabot

handling.

---

# aube

Use aube as the Node.js package manager, installed and pinned through mise. aube

is jdx's fast, security-first package manager (https://aube.sh/); this skill

captures the *how we use it here* decisions, not the official reference.

## Core conventions

1. **Install through mise** — `mise use aube` and pin in `[tools]` (e.g.

`aube = "2.2.9"`); never install aube standalone. See

[`mise`](../mise/SKILL.md).

2. **Single version source** — `mise.toml` drives both node and aube; after

migrating, remove the `packageManager` field from `package.json` so versions

do not fork.

3. **Keep a Dependabot-compatible lockfile** — aube reads and writes an existing

`pnpm-lock.yaml` or `package-lock.json` in place, so keep that committed

rather than switching to `aube-lock.yaml`. Dependabot lacks an aube ecosystem

and cannot maintain `aube-lock.yaml`. For new projects, set

`defaultLockfileFormat = "pnpm"` in `aube-workspace.yaml`, `.npmrc`, or

`settings.toml`. In `dependabot.yml`, use the `npm` ecosystem for these

projects — no `aube` ecosystem exists. Adopt `aube-lock.yaml` only without

Dependabot. Locked versions are trusted on frozen installs (`aube ci`)

without per-install revalidation.

4. **Accept supply-chain defaults** — aube denies lifecycle scripts by default,

holds new releases behind a 24h cooling window, checks typosquats, and

downgrades trust. Keep these; allow only the specific builds you need.

5. **Phased migration** — pilot in one project or subcomponent before

committing; do not replace wholesale.

## Commands

| Command | Use |

| --- | --- |

- | `aubr <script>` (= `aube run`) | Daily driver: `aubr build`, `aubr test`, `aubr dev`. Echoes `$ <cmd>` to stderr (`--silent` to mute). |

+ | `aube run <script>` (alias `aubr`) | Daily driver: `aube run build`, `aube test`, `aube run dev`. Echoes `$ <cmd>` to stderr (`--silent` to mute). |

| `aube test` | Auto-installs on stale state, then runs `test` script. |

| `aube ci` | Frozen-lockfile install for CI; runs no scripts by default. |

| `aube install` | Local setup / Docker layers. |

| `aube add <pkg>` | Add a dependency (malware-checked by default). |

- | `aubx <tool>` (= `aube dlx`) | Run a one-off tool without installing. |

+ | `aube dlx <pkg>` (alias `aubx`) | Run a one-off tool without installing. |

| `aube exec [--] <cmd>` | Run binary from deps. Put `--` before binary so flags pass through (see Gotchas). |

| `aube approve-builds` | Interactive review/approval of lifecycle build scripts. |

+ Prefer `aube run`/`aube dlx`/`aube exec` over `aubr`/`aubx` in scripts and CI

+ (see Gotchas).

## CI (GitHub Actions)

Prefer `jdx/aube-action@v1` over `jdx/mise-action@v4`: aube's repo moved

`jdx/aube` -> `aubepkg/aube`, and mise's aqua backend still verifies GitHub

attestations against the old identity, breaking `mise install aube` for every

release since 2.2.8. `jdx/aube-action@v1` downloads the release directly (no

attestation check) and installs Node.js too via `node-version: auto` (reads

`mise.toml`, `.nvmrc`, etc.) — drop `actions/setup-node`. Still need

`mise-action` for other tools in the same job? Set

`MISE_AQUA_GITHUB_ATTESTATIONS: false` on that step instead.

Cache both aube directories — the content store and registry metadata are

separate (see https://aube.sh/package-manager/ci.html#cache-choices) — via

`aube store path` / `aube cache path`, not hardcoded paths:

```yaml

- uses: jdx/aube-action@v1

with:

node-version: auto

- id: aube-paths

run: |

echo "store=$(aube store path)" >> "$GITHUB_OUTPUT"

echo "cache=$(aube cache path)" >> "$GITHUB_OUTPUT"

- uses: actions/cache@v6

with:

path: ${{ steps.aube-paths.outputs.store }}

key: ${{ runner.os }}-aube-store-${{ hashFiles('**/pnpm-lock.yaml') }}

- uses: actions/cache@v6

with:

path: ${{ steps.aube-paths.outputs.cache }}

key: ${{ runner.os }}-aube-cache-${{ hashFiles('**/pnpm-lock.yaml') }}

- run: aube ci

- - run: aubr test

+ - run: aube test

```

## Lifecycle scripts

aube jails lifecycle scripts by default. Allow needed builds via

`aube approve-builds` or `allowBuilds` in `aube-workspace.yaml` /

`pnpm.allowBuilds` in `package.json`, e.g. `esbuild`, `workerd`. Verify

locally before relying on CI. Jailed builds can also be granted explicit

permissions (`jailBuildPermissions`).

## Gotchas

- **Third-party actions auto-detect the package manager** — e.g.

`wrangler-action` picks missing pnpm on `pnpm-lock.yaml`. Call binary

directly: `aube exec wrangler deploy` with `CLOUDFLARE_API_TOKEN` in env.

- **`aube exec` swallows global flags** — `aube exec tsc --version` prints aube's

version. Put `--` before binary: `aube exec -- tsc --version`.

- - **`aubr` echoes commands to stderr** — prints expanded command prefixed with `$`

+ - **`aube run` echoes commands to stderr** — prints expanded command prefixed with `$`

to stderr (matching npm/pnpm); pass `--silent` / `-s` if scripts parse stderr.

+ - **`aubr`/`aubx` missing from `PATH` since aube 2.2.13+** — the mise packslip

+ manifest lists only `"bin": ["aube"]`, so `.mise-bins/` (mise's `PATH` dir)

+ has no `aubr`/`aubx` symlinks; both exit 127. Use `aube run`/`aube dlx`, or

+ symlink them yourself in mise `postinstall`.

- **Global installs use aube data root in 2.x** — `aube add -g` installs to

`$XDG_DATA_HOME/aube/bin` (`~/.local/share/aube/bin`), ignoring `PNPM_HOME`.

Add this directory to `$PATH`.

- **bun -> aube is also a runtime migration** — migrating runtime (`node:*`)

and test runner (bun test -> Vitest) is separate from package-manager switch.

- **starship `nodejs`/`package` modules loop under aube** — disable in

`~/.config/starship.toml` (`[nodejs]` and `[package]` `disabled = true`) to

prevent prompt loops.

- **`mise install aube` fails GitHub attestation verification** — see CI

section for the `jdx/aube-action` fix.

## Related

- [`mise`](../mise/SKILL.md) — installs and pins aube locally; provides the

single version source (`mise.toml`) that `jdx/aube-action@v1` reads in CI.