git:20260906.e457ebd to git:20260906.3c6592e

---

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

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

## CI (GitHub Actions)

```yaml

- uses: jdx/aube-action@v1

with:

run: |

with:

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

with:

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

- run: aube ci

- run: aubr 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 `$`

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

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

## Related