Shelve
Apps & AutomationshelveShelve is an Agent Skill for apps & automation published in the HugoRCD/shelve repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Complete guide to Shelve — team secrets platform, CLI (@shelve/cli), sync policies, scoped tokens, shelve run for agents/CI, push/pull/diff, and the web app. Install with npx skills add https://shelve.cloud
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/HugoRCD/shelve/blob/HEAD/apps/lp/skills/shelve/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/shelve, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Shelve
Shelve is an open-source team secrets platform: web app + CLI. Store variables per team, project, and environment; inject at runtime without committing .env files.
- Docs: https://shelve.cloud/docs
- CLI docs: https://shelve.cloud/docs/cli
- Install / update this skill:
npx skills add https://shelve.cloud - Catalog: https://shelve.cloud/.well-known/skills/index.json
Security rules (read first)
- Prefer
shelve run -- <cmd>— secrets stay in the child process; no.envon disk. - Avoid
shelve pullin agent shells — writes plaintext secrets agents can read. Use--yesonly if the user explicitly needs a disk file; runshelve initfirst. - Never commit
SHELVE_TOKEN,.env, or~/.shelve/cache. - Never print secret values in logs, JSON, or commits. CLI
--jsonexcludes values by design. - Run
shelve initonce per workspace before secret operations. - Protect production: use
sync.protectedEnvironmentsinshelve.jsonand/or project Settings → Sync policy.
Platform (teams, tokens, UI)
| Concept | CLI / config |
|---|---|
| Team | slug in shelve.json, SHELVE_TEAM_SLUG |
| Project | project, SHELVE_PROJECT |
| Environment | --env, defaultEnv, SHELVE_DEFAULT_ENV |
| API token | SHELVE_TOKEN — create at https://app.shelve.cloud/user/tokens (shown once; scope read/write + team/project/env) |
CLI vs UI: bulk edit and audit logs → UI; local dev and CI → CLI run. Details: platform.md.
Non-interactive / agents
Run shelve doctor --json first in automation.
| Variable | Purpose |
|---|---|
SHELVE_TOKEN | API token |
SHELVE_TEAM_SLUG | Team slug |
SHELVE_PROJECT | Project name |
SHELVE_DEFAULT_ENV | Default environment |
SHELVE_URL | Instance (default https://app.shelve.cloud) |
| Flag | Effect |
|---|---|
--json | Machine-readable stdout; JSON errors on stderr |
--quiet / -q | No spinners |
--yes / -y | Skip confirmations |
--non-interactive | Fail instead of prompt |
--debug | Verbose (SHELVE_DEBUG=1) |
Auto non-interactive when CI=true, agent shell detected, or AI_AGENT is set.
Command cheat sheet
# Preferred: inject secrets
shelve run -- pnpm dev
shelve run --env preview -- pnpm build
shelve run dev # package.json script shortcut
shelve init # agent ignores + .gitignore block
shelve login # browser device flow (humans)
shelve login --token "$SHELVE_TOKEN" # CI / automation
shelve doctor --json
shelve --json config
# Sync
shelve diff --env staging
shelve push --env development --yes
shelve pull --env development --yes # risky in agent shells
shelve sync --dry-run --env production
shelve create --name my-app --slug my-team
shelve generate --type env-example
shelve run flags
| Flag | Purpose |
|---|---|
--env | Environment |
--template | .env.template with shelve:// refs |
--offline | Encrypted cache only |
--no-cache | Disable cache |
--cache-ttl | e.g. 15m, 24h default |
--watch | Reload on remote changes |
--restart-on-change | Respawn child instead of SIGHUP |
Sync policies (shelve.json)
{
"$schema": "https://shelve.cloud/schema.json",
"slug": "my-team",
"project": "my-app",
"defaultEnv": "development",
"sync": {
"protectedEnvironments": ["production"],
"environments": {
"development": { "sourceOfTruth": "local" },
"production": { "sourceOfTruth": "remote", "allowPush": false, "pullMode": "merge" }
}
}
}
See sync-policies.md and https://shelve.cloud/docs/cli/sync-policies
Error codes
| Code | Meaning |
|---|---|
AGENT_BLOCKED | pull in agent shell without --yes |
AUTH_REQUIRED | Missing token |
MISSING_ENV | No --env / defaultEnv |
FETCH_FAILED | API/cache failure in run |
PUSH_BLOCKED / PULL_BLOCKED | Sync policy |
SYNC_CONFLICT | onPushConflict: fail or prompt in CI |
ENV_PROTECTED | Server blocked push to protected env |
Reference files (read when needed)
| File | Contents |
|---|---|
cli-commands.md | All commands, JSON shapes, config keys |
agent-workflows.md | CI, GitHub Actions, monorepo, templates, watch |
platform.md | Teams, tokens, encryption, UI flows |
sync-policies.md | Push/pull conflict rules, diff / sync |
Common mistakes
| Mistake | Fix |
|---|---|
shelve pull in Cursor/Claude | shelve run -- <cmd> |
| CLI hangs | SHELVE_* + --non-interactive |
| Push overwrites prod | protectedEnvironments + shelve diff first |
| Secrets in git | shelve init; never commit .env |