Troubleshooting

Quick fixes for the most common CLI issues. Run shelve doctor (or shelve --json doctor) first — it checks config, auth, API, cache, and agent context in one shot.

shelve doctor
shelve --json doctor

Error codes

See also shelve --help for the full list of structured error codes.

Monorepo runs

push, pull, diff and sync run once per package when started from a workspace root. A failing package stops the run; the packages before it have already been applied (a pull has written its env file, a push has reached Shelve). The error names the package that failed and the ones that completed, in the hint and in context under --json:

{
  "ok": false,
  "error": {
    "code": "PUSH_BLOCKED",
    "message": "apps/web: Push to \"production\" is blocked by sync policy.",
    "hint": "Remove the environment from sync.protectedEnvironments or set allowPush: true. Already completed: apps/api.",
    "context": { "failedPackage": "apps/web", "completedPackages": ["apps/api"] }
  }
}

Fix the named package, then re-run. Use --path <dir> to retry just that one.

Exit codes

Common symptoms

CLI hangs waiting for input

Cause: Interactive prompt (login, missing --env, confirmation).

Fix:

export SHELVE_TOKEN=…
export SHELVE_TEAM_SLUG=…
export SHELVE_PROJECT=…
shelve --non-interactive doctor

shelve run dev exits instantly

Cause: Script resolution failed or script exits immediately.

Fix:

shelve run --debug dev
shelve run -- pnpm dev

Secrets not updated after Shelve UI change

Cause: Old process env or stale cache.

Fix: Restart with shelve run, or use --watch --restart-on-change.

pull fails in Cursor / Claude Code

Cause: Agent guard (AGENT_BLOCKED).

Fix: Prefer shelve run -- <cmd>. Only shelve pull --yes if you explicitly need a .env file.

Offline / plane mode

Fix:

# After one successful online run:
shelve run --offline -- pnpm build

JSON automation parse errors

• Success → stdout: { "ok": true, "data": … }
• Errors → stderr: { "ok": false, "error": { "code", "message" } }
• run spawn metadata → stderr event: { "ok": true, "event": "child_spawned", … }

Secret values are never included in JSON output.

CI / GitHub Actions

Use the composite action:

- uses: ./.github/actions/shelve-run
  with:
    token: ${{ secrets.SHELVE_TOKEN }}
    team-slug: my-team
    project: my-app
    env: ci
    command: pnpm test

Validate secrets before the main job:

- run: npx @shelve/cli --json doctor
  env:
    SHELVE_TOKEN: ${{ secrets.SHELVE_TOKEN }}
    SHELVE_TEAM_SLUG: my-team
    SHELVE_PROJECT: my-app

Agent skill

Install the published skills:

npx skills add https://shelve.cloud

Catalog: https://shelve.cloud/.well-known/skills/index.json (skill: shelve).