Push and Pull
push and pull sync secrets between your local .env file and Shelve. For day-to-day development — especially in AI agent shells — prefer shelve run instead of pull.
Push
Upload variables from your local env file to Shelve:
shelve push
shelve push --env staging
shelve --non-interactive --yes push --env staging
shelve --json push --env staging
Reads variables from envFileName in shelve.json (default .env).
Options
defaultEnv in shelve.json or SHELVE_DEFAULT_ENV.confirmChanges is true in config. Also respects global --yes.JSON output: { "env", "variableCount", "pushed" } (no secret values).
Pull
Download variables from Shelve to your local env file:
shelve pull
shelve pull --env production
shelve pull --env production --yes
AI-agent guard
When the CLI detects an AI agent shell (Cursor, Claude Code, Codex, …) or AI_AGENT is set, pull fails with AGENT_BLOCKED unless you pass --yes:
# Explicit opt-in only — secrets will be written to disk
shelve pull --yes --env development
Options
confirmChanges prompts.JSON output: { "env", "variableCount", "file", "keys[]", "pullMode", "preservedLocalKeys[]" } — values are never included.
Monorepos
Run from the workspace root and both commands visit every package that has its own shelve.json:
shelve pull
shelve pull --path apps/web
JSON output then becomes { "packages": [...] }, one entry per package with its path. See Monorepo support.
Default environment
Set defaultEnv to skip passing --env every time:
{
"defaultEnv": "development",
"slug": "my-team",
"project": "my-app"
}
confirmChanges
When confirmChanges: true in shelve.json, push and pull ask before writing. Skip with --yes or global --yes / --non-interactive automation flags.
Sync policies
Configure who wins when local and Shelve differ, block pushes to production, or merge on pull. See Sync policies.
shelve diff --env staging
shelve push --env staging
shelve sync --dry-run --env production