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
| Code | Meaning | Fix |
|---|---|---|
AGENT_BLOCKED | pull in an AI agent shell without --yes | Use shelve run -- <cmd> or pass --yes if disk .env is required |
AUTH_REQUIRED | No token | export SHELVE_TOKEN=… or shelve login |
CONFIG_MISSING | No shelve.json and missing env | Create config or set SHELVE_TEAM_SLUG + SHELVE_PROJECT |
MISSING_ENV | No environment selected | --env staging or defaultEnv in config |
MISSING_INPUT | Non-interactive mode missing a flag | Pass the flag shown in the error hint |
FETCH_FAILED | Network/API failure, no cache | Go online once, or use --offline if cache exists |
FORBIDDEN | Token lacks scope | Create a token with read/write for the team/project |
PROJECT_NOT_FOUND | Project missing | Enable autoCreateProject or shelve create |
PUSH_BLOCKED | Push disabled for this env | Check sync.protectedEnvironments or allowPush |
PULL_BLOCKED | Pull disabled for this env | Set sync.environments.<env>.allowPull |
SYNC_CONFLICT | Diverging keys and onPushConflict: fail | Run shelve diff, align values, or change policy |
ENV_PROTECTED | Server blocked write to protected env | Update project sync policy in Shelve settings |
See also shelve --help for the full list of structured error codes.
Exit codes
| Code | Meaning |
|---|---|
0 | Success |
1 | CLI or API error |
128 + n | Child killed by signal (run) |
129 | Parent process gone / stdin EIO |
130 / 143 | SIGINT / SIGTERM (often treated as clean shutdown in run) |
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" } } runspawn 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).