Install the CLI, then run doctor.

Requirements

Node.js 22+

the package declares node >=22; CI runs on Node 24

npm or pnpm

any Node package manager can install the global package

Git + Corepack

only needed for the source install below

Installation

Pick one method. All three end with the same global artshelf command.

# npm
npm install -g artshelf

# pnpm
pnpm add -g artshelf

# from source (needs git + corepack)
git clone https://github.com/calvinnwq/artshelf.git
cd artshelf
corepack enable
pnpm install --frozen-lockfile
pnpm run build
npm link

# verify whichever you picked
artshelf --version
artshelf doctor

# later, for npm installs only
artshelf update

npm link connects the local checkout to your global npm bin, so later rebuilds update the artshelf command. To remove an npm install, run npm uninstall -g artshelf; for a source install, run npm unlink -g artshelf.

Artshelf checks npm occasionally and prints update notices to stderr, so scripted JSON output stays clean. artshelf update is for npm global installs only and runs npm install -g artshelf@latest. pnpm global installs should update with pnpm add -g artshelf@latest; source installs should update by pulling, rebuilding, and linking again. Set ARTSHELF_NO_UPDATE_CHECK=1 for scheduled jobs that must avoid network and update-cache writes.

Updating a source install

# pull the latest changes and rebuild
cd artshelf
git pull
pnpm install --frozen-lockfile
pnpm run build
npm link

Recommended agent setup

Artshelf is agent-operated, so let your agent finish the job. The repo ships INSTALL.md with the full agent setup steps: install the portable skill together with its bundled report renderer script, learn the four-move Capture automatically, Review calmly, Approve exactly, Verify quiet loop, register existing ledgers, and ask you first before creating any scheduled review job. Scheduled jobs stay read-only; cleanup, dispose, and purge execution always come back to you.

Copy this one line into your coding agent:

Follow the instructions in https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md to set up Artshelf in this workspace.

What the agent will follow, in full:

# Artshelf agent setup

These instructions are written for a coding agent. If you are a human, paste
this one line into your agent and let it do the rest:

> Follow the instructions in
> https://github.com/calvinnwq/artshelf/blob/main/INSTALL.md
> to set up Artshelf in this workspace.

## 1. Install the CLI

Check whether it is already installed before changing anything:

```bash
artshelf --version
artshelf doctor
```

If the command is missing, install it from npm and verify again:

```bash
npm install -g artshelf      # or: pnpm add -g artshelf
artshelf --version
artshelf doctor
```

If Artshelf says a newer version is available and you used npm, update the npm
install and verify again:

```bash
artshelf update
artshelf --version
artshelf doctor
```

If you used pnpm, update with `pnpm add -g artshelf@latest` instead.
For source installs, pull, rebuild, and run `npm link` again.

Only use a source install when the user asks for one, and ask the user where
to clone the repo first instead of assuming a repo path:

```bash
git clone https://github.com/calvinnwq/artshelf.git "$ARTSHELF_REPO"
cd "$ARTSHELF_REPO"
corepack enable
pnpm install --frozen-lockfile
pnpm run build
npm link
artshelf --version
artshelf doctor
```

## 2. Install the portable skill, including its script

Install, copy, or reference the portable skill so you register temporary
artifacts when you create them and check the shelf before handoffs.
It teaches the four-move loop: Capture automatically, Review calmly, Approve
exactly, and Verify quiet.
Copy the whole `skills/artshelf` directory, not just SKILL.md: the skill ships
with `scripts/render-review-report.mjs` (the deterministic review report
renderer) plus its `schemas/` and `examples/`, and those must travel together.

```bash
# from the installed npm package
rm -rf <your-skills-dir>/artshelf
cp -R "$(npm root -g)/artshelf/skills/artshelf" <your-skills-dir>/

# or from a source checkout
rm -rf <your-skills-dir>/artshelf
cp -R "$ARTSHELF_REPO/skills/artshelf" <your-skills-dir>/
```

Re-run the replacement copy after upgrading the package so the skill and
script stay in sync with the CLI.

## 3. Register existing ledgers

`artshelf put` registers its ledger automatically. Register any existing
project ledgers so `--all` commands can see them:

```bash
artshelf ledgers add --ledger <repo>/.artshelf/ledger.jsonl --name <project> --scope repo --json
artshelf ledgers list --json
```

If `ledgers list`, `doctor`, or `status --all --agent` reports stale/missing
registrations, review a registry-prune plan instead of hand-editing the registry:

```bash
artshelf ledgers prune --dry-run --registry <registry-path> --json
# after approval: approve artshelf ledgers prune registry <registry-path> plan <plan-id>
artshelf ledgers prune --execute --plan-id <plan-id> --registry <registry-path> --json
```

## 4. Scheduled review (ask the user first)

Ask the user whether they want a scheduled review job before creating one.
If they approve, schedule a read-only review job (daily works well) in your
host runtime that disables update checks and runs:

```bash
ARTSHELF_NO_UPDATE_CHECK=1 \
artshelf review --all --json
```

and reports what needs attention. Scheduled jobs are review and report only:
never schedule `artshelf cleanup --execute`, `artshelf ledgers prune --execute`,
`artshelf dispose --execute`, or `artshelf trash purge --execute`.

## 5. Verify and report

Finish by showing the user the output of:

```bash
artshelf doctor
artshelf ledgers list --json
```