Shelve| v3.3.0
Open App S
CLI

Agents & automation

Run the Shelve CLI from CI, scripts, and AI coding agents with global flags, JSON output, and non-interactive guards.

The Shelve CLI is designed to work in CI, shell scripts, and AI agent shells (Cursor, Claude Code, Codex, …) without hanging on prompts or polluting logs with spinners.

Prefer shelve run -- <cmd> over shelve pull. run keeps secrets in the child process memory only. pull writes plaintext to disk where agents can read them.

Recommended workflow

  1. Run shelve doctor --json (or shelve doctor) to validate setup.
  2. Set context once with environment variables (no shelve login prompt required):
    terminal
    export SHELVE_TOKEN="shlv_…"
export SHELVE_TEAM_SLUG="my-team"
export SHELVE_PROJECT="my-app"
export SHELVE_DEFAULT_ENV="development"   # optional
export SHELVE_URL="https://app.shelve.cloud" # optional
  3. Run shelve init once per repo (agent ignore files + .gitignore block).
  4. Inject secrets with shelve run -- pnpm dev (or your command).
  5. Use --json when a script needs to parse output.
  6. Use --non-interactive (or rely on agent/CI auto-detection) so missing flags fail fast.

Global flags

These flags can appear before or after the subcommand (for example shelve run --json -- pnpm dev or shelve --json config):

--json
boolean
Success → JSON on stdout: { "ok": true, "command"?: string, "data"?: object }.
Errors → JSON on stderr: { "ok": false, "error": { "code", "message", "status"?, "hint"? } }.
Secret values are never included in JSON output.
--quiet
boolean
Suppress clack intro/outro/spinners. Minimal text output only.
--yes
boolean
Skip confirmation prompts (pull, push when confirmChanges is enabled, etc.).
--non-interactive
boolean
Fail with a structured error instead of prompting when required input is missing (MISSING_*, AUTH_REQUIRED, …).
--debug
boolean
Verbose debug logs. Also enabled by SHELVE_DEBUG=1 or DEBUG=true. HTTP requests are logged without Authorization headers or secret values.

Auto non-interactive mode

The CLI enters non-interactive mode when any of these is true:

  • --non-interactive is passed
  • CI=true or CI=1
  • The shell is detected as an AI agent via std-env (cursor, claude, codex, …)
  • AI_AGENT is set (force-detect)

In agent shells, shelve pull without --yes fails immediately with code AGENT_BLOCKED instead of prompting.

JSON output by command

Commanddata shape
doctor{ healthy, checks[], exitCodes, errorCodes }
configMerged config; token redacted as "***"
me{ loggedIn, username?, email? }
push{ env, variableCount, pushed }
pull{ env, variableCount, file, keys[] } — no values
init{ writtenFiles, skippedFiles, gitignoreUpdated }
login{ username, email }
create{ name, slug, configPath }
logout{ loggedOut: true }
generate{ type, path }
upgrade{ previous, current, updated }

shelve run inherits the child stdio. Startup errors are structured on stderr; with --json, a spawn event is also emitted on stderr: { "ok": true, "event": "child_spawned", "env", "variableCount", "keys", "command", "pid" }.

Exit codes

CodeMeaning
0Success
1CLI, API, or validation error
128 + nChild killed by signal (run)
129Parent process gone / stdin EIO
130 / 143SIGINT / SIGTERM (forwarded from run)

Examples

terminal
# Machine-readable config (token redacted)
shelve --json config

# CI push without prompts
shelve --non-interactive --yes push --env staging

# Agent-safe dev server
shelve run -- pnpm dev

# Debug API round-trip
shelve --debug run --env preview -- pnpm build

Install the agent skill

Shelve publishes a single Agent Skill at /.well-known/skills/ on shelve.cloud (shelve — CLI, platform, and sync policies):

terminal
npx skills add https://shelve.cloud

The skill teaches agents Shelve end-to-end: platform model (teams, tokens, UI), CLI workflows, sync policies, and security rules (prefer run, avoid disk writes, use SHELVE_* env vars). Reference files ship alongside SKILL.md (cli-commands.md, platform.md, sync-policies.md, agent-workflows.md).

Local testing (contributors)

From the Shelve monorepo, use the zero-network playground:

terminal
pnpm play
pnpm play -- --json config

See the playground README on GitHub.

Init

Scaffold AI-agent-safe ignore files in your project.

Troubleshooting

Symptom → cause → fix for the Shelve CLI and agent automation.