03Start · Quickstart

Put one artifact on the shelf.

The whole loop in five minutes, using throwaway paths under /tmp. You will register one artifact, review it, dry-run the cleanup, execute the approved plan, and verify. Trash gets purged separately at the end.

Read the steps as the four moves: Capture automatically in step 1, Review calmly in step 2, Approve exactly in step 3, and verify quietly in step 4. Step 5 repeats the same approval-first loop for physical deletion from trash.

1. Create something temporary

# make a scratch artifact to practice on
mkdir -p /tmp/artshelf-demo
echo "debug output" > /tmp/artshelf-demo/output.txt

# put it on the shelf: make this demo immediately due, then trash on approval
artshelf put /tmp/artshelf-demo \
  --reason "quickstart artifact" \
  --ttl 0m \
  --kind scratch \
  --cleanup trash \
  --owner manual \
  --label quickstart \
  --ledger /tmp/artshelf-ledger.jsonl \
  --registry /tmp/artshelf-registry.json \
  --json

Note the id the command returns. You will quote it in handoffs and cleanup reports.

2. Review without moving files

Non-destructive

These commands are safe for agents and cron jobs. They never move artifacts or trash entries; cleanup --dry-run may register a review plan.

# everything on the shelf
artshelf list --ledger /tmp/artshelf-ledger.jsonl

# quick counts: active, due, trashed
artshelf status --ledger /tmp/artshelf-ledger.jsonl

# check the ledger file itself is healthy
artshelf validate --ledger /tmp/artshelf-ledger.jsonl --json

# which records are due, kept, or missing
artshelf due --ledger /tmp/artshelf-ledger.jsonl --json

# preview cleanup and get a plan id (still moves nothing)
artshelf cleanup --dry-run --ledger /tmp/artshelf-ledger.jsonl --json

This demo uses --ttl 0m, so the dry-run writes a plan and prints the planId a human can approve. When nothing is ready, the dry-run reports not-created.

3. Execute only an approved plan

Copy the planId from the dry-run output in step 2.

# run only the plan that was reviewed
artshelf cleanup --execute \
  --plan-id plan_20260601_120000_ab12 \
  --ledger /tmp/artshelf-ledger.jsonl

Hard boundary

Execute is intentionally separate. Approval names the exact ledger path and reviewed plan id. No global execute path exists.

4. Verify quiet

After cleanup, run another read-only review.

# confirm nothing still needs attention
artshelf review --ledger /tmp/artshelf-ledger.jsonl --json

# see what cleanup moved into trash
artshelf trash list --ledger /tmp/artshelf-ledger.jsonl --json

5. Purge trash separately

Cleanup with cleanup=trash moves files into Artshelf trash. Physical deletion needs a separate reviewed purge plan.

# preview which trashed files are old enough to purge
artshelf trash purge --older-than 0m --dry-run --ledger /tmp/artshelf-ledger.jsonl --json

Then execute with the purge planId the dry-run reported.

# delete for real, but only with the reviewed purge plan id
artshelf trash purge --execute \
  --plan-id purge_20260601_120000_ab12 \
  --ledger /tmp/artshelf-ledger.jsonl