Shelve

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)

1. Prefer shelve run -- <cmd> — secrets stay in the child process; no .env on disk.
2. Avoid shelve pull in agent shells — writes plaintext secrets agents can read. Use --yes only if the user explicitly needs a disk file; run shelve init first.
3. Never commit SHELVE_TOKEN, .env, or ~/.shelve/ cache.
4. Never print secret values in logs, JSON, or commits. CLI --json excludes values by design.
5. Run shelve init once per workspace before secret operations.
6. Protect production: use sync.protectedEnvironments in shelve.json and/or project Settings → Sync policy.

Platform (teams, tokens, UI)

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.

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

# Monorepo: from the root these four run once per package
shelve pull --path apps/web           # ...or target a single package

shelve create --name my-app --slug my-team
shelve generate --type env-example

shelve run flags

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

Monorepos

From a workspace root, push / pull / diff / sync run once per package that has its own shelve.json; the root itself and packages without one are skipped. --path <dir> targets a single package. run never fans out.

• Root shelve.json holds shared settings (slug, defaultEnv, …); project stays per-package and is never inherited.
• Give the root a project to opt out and treat it as one project.
• With --json, data becomes { "packages": [...] }, one entry per package with its path.
• A failing package stops the run; the error carries context: { failedPackage, completedPackages }.

Details: agent-workflows.md

Error codes

Reference files (read when needed)

Common mistakes