Announcing Shelve 3

Shelve 3: built for teams, agents, and production

Shelve 3 is here. If you have been using Shelve since 2.0, you already know the pitch. Centralize your environment variables, inject them at runtime with shelve run, sync to GitHub Secrets, and keep your team aligned from the app or the CLI. Version 2 delivered on that promise with a polished UI, a capable CLI, and a workflow that made .env files optional on your laptop.

Version 3 builds on that solid foundation. The theme is more control, more visibility, and a CLI that matches how we work today, whether you are in a team, in CI, or working alongside AI coding agents. Same product you already trust, with a deeper toolkit underneath.

What's new at a glance

Before you upgrade

• API tokens need to be re-issued after upgrading. The token format and storage model changed. Plaintext is now shown only at creation, and tokens are stored as hashes. Create new tokens in the UI and update your CI secrets.
• The CLI now sends Authorization: Bearer <token>. Cookie-based auth still works for one release window with Deprecation and Sunset response headers.
• Upgrade the CLI: npm i -g @shelve/cli@latest (or your package manager equivalent).

See the CLI upgrade guide and API tokens docs for details.

Sign in from the browser

The biggest day-to-day CLI change: shelve login no longer asks you to paste an API token.

Instead, Shelve uses the RFC 8628 device authorization flow, the same pattern as the GitHub CLI or Vercel.

1. Run shelve login in your terminal.
2. Your browser opens to Shelve (or the CLI prints a URL and a short code).
3. Sign in if needed, review the request, and click Authorize CLI.
4. Shelve creates a revocable API token named CLI — <hostname> (90-day expiry, read/write) and stores it in your OS keychain.

No dashboard tab hunting. No copy-paste into the terminal. The token shows up in your tokens list like any other. Revoke it anytime.

shelve login              # opens browser (default)
shelve login --no-browser # print URL + code only (SSH, remote machines)
shelve login --with-token # paste a token manually (optional)

CI and agents stay the same. Set SHELVE_TOKEN or pass --token. No browser required. Scoped, expiring tokens from the dashboard remain the right choice for pipelines. See login and logout docs.

More control over API tokens

Shelve has always encrypted secrets at rest. With 3.0, API tokens get the same level of care, plus a set of features teams have been asking for:

• 256 bits of entropy, encoded in Crockford base32.
• Hashed at rest. Only sha256(token) and a display prefix (she_…) are stored. The full value is shown exactly once at creation.
• Granular scopes to restrict a token to specific teams, projects, environments, and read / write permissions, enforced server-side.
• Optional expiry, CIDR allowlists, and lastUsedAt / lastUsedIp on every request so you always know which token did what.

The token UI at /user/tokens shows scopes, expiry, and last-used info at a glance. The creation flow uses a roomier modal with cascading multi-select pickers, inline CIDR validation, and a helpful nudge when a token has no restrictions applied.

Standard Bearer authentication

The CLI sends Authorization: Bearer she_…, the same pattern used by most APIs and CI systems. Cookie-based auth remains available during the transition, with clear deprecation headers.

Envelope encryption, per project

Shelve already sealed every variable with AES-256-GCM before it hit the database. Version 3 adds envelope encryption, an extra layer for finer-grained key management:

value ──seal──▶ ciphertext     (key = DEK, per-project)
DEK   ──seal──▶ encryptedDek   (key = KEK, platform-wide)

Each project gets its own Data Encryption Key (DEK), sealed by the platform Key Encryption Key (KEK). You get per-project key rotation without touching application code, and a smaller blast radius if a single project key is ever rotated or replaced.

Existing projects upgrade seamlessly. Decryption tries the project DEK first, then transparently falls back to the previous scheme. No data migration required. Read the full scheme in the encryption docs.

Audit logs

One of the most requested features: a full audit trail for your team.

Every sensitive action (token create/delete, variable read/write, environment and project mutations) is recorded with actor, action, resource, IP, user agent, and metadata. Team admins get an Audit logs tab in team settings with cursor pagination and action filters.

The UI includes color-coded action badges, resource icons, parsed user-agent labels (e.g. Shelve CLI 5.0.0, Chrome · macOS), and a per-row metadata popover to inspect the full JSON payload. You can query the feed via API too. See audit logs docs.

shelve run grows up

shelve run was the headline feature of 2.0. Run any script with secrets injected at runtime, no .env on disk. In Shelve 3 it became significantly more capable and reliable.

Credentials in the OS keychain

Whether you signed in via the browser flow or set a token for CI, credentials live in the OS keychain (macOS Keychain, Windows Credential Manager, libsecret), with a hardened XDG fallback at ~/.config/.shelve. Legacy ~/.shelve files migrate automatically on first read.

Offline cache, watch mode, and secret references

Working on a plane? API briefly down? After every successful fetch, shelve run keeps an encrypted offline cache (AES-256-GCM, keyed from your token via HKDF). Revoke the token and the cache becomes unreadable.

New flags and modes:

• --offline: use cache only
• --no-cache: always fetch fresh
• --cache-ttl 24h: control freshness
• --watch: poll for variable changes and forward SIGHUP to the child (Vite/Nuxt/Next hot-reload)
• --restart-on-change: respawn the process instead
• --template .env.template: resolve shelve://<team>/<project>/<env>/<KEY> references and commit the template safely to Git

Signal forwarding, watch mode, and cross-platform spawn were hardened across the 3.x CLI releases, including Windows .cmd shims, parent-death watchdogs, and cleaner exit-code propagation.

shelve init
shelve run -- pnpm dev
shelve run --watch -- pnpm dev
shelve run --template .env.template -- pnpm build

Built for the AI-agent era

AI coding agents (Cursor, Claude Code, Codex, Aider, Continue, and more) are part of many workflows now. Shelve 3 meets that with practical guardrails:

• shelve init: one command to add .cursorignore, .aiderignore, .codeiumignore, .continueignore, and a # shelve-managed-block in .gitignore.
• shelve pull: detects agent environments and asks before writing plaintext to disk (--yes to skip).
• shelve run: secrets stay in the child process memory, never on disk.

If you use agents, shelve run -- <cmd> is the recommended path.

Platform improvements

Alongside the security and CLI work, the platform itself got a lot of love:

• Variable groups and descriptions to organize variables in the UI. pull outputs section headers (# ---- Group ----) and inline description comments, and auto-generates a .env.example.
• OTP auth and bot-id protection on the login surface.
• Documentation migrated to Docus for clearer structure, better search, and a full CLI reference on shelve.cloud.
• Vercel self-hosting docs and updated terms/privacy pages.
• Test infrastructure with unit and E2E coverage across push/pull, tokens, auth, audit logs, offline cache, and secret references.
• Navigation and members table refactors, single-team auto-redirect, Nuxt 4 and Nuxt UI upgrades.

Sync policies and agent automation

Shelve 3 also ships team-grade sync controls and automation-first CLI flags.

Global flags and structured output

Every command supports flags built for CI and agent shells:

shelve doctor validates your setup and reports health checks. See Agents & automation for JSON output shapes per command.

Sync policies, diff, and protected environments

Sync policies define what happens when local and remote diverge:

• shelve diff: compare local .env with Shelve (no writes, safe with --json)
• shelve sync: reconcile according to sourceOfTruth (remote vs local)
• onPushConflict: overwrite, skip, fail, or prompt
• pullMode: replace or merge (local-only keys kept)
• protectedEnvironments: mark production (or any env) as push-protected on the server

Server policies are the source of truth. If production is protected, the CLI respects that. See sync policies docs.

Agent skill and CI tooling

Install the published agent skill so Cursor, Claude, and other agents know how to use Shelve:

npx skills add https://shelve.cloud

The skill covers shelve run, shelve init, scoped tokens, sync policies, and the --json / --non-interactive flags. A GitHub Action is available for CI. Full CLI documentation and troubleshooting guides live on shelve.cloud/docs/cli.

What this means for you

Shelve 2.x made environment management a pleasure. Shelve 3 adds depth: browser login, observability, fine-grained access control, and a CLI that fits how teams and agents work today.

Try Shelve 3 today

• Get started: app.shelve.cloud
• Read the docs: shelve.cloud/docs/getting-started
• Install the CLI: npm i -g @shelve/cli@latest
• Contribute: github.com/HugoRCD/shelve

Thank you

This release spans dozens of pull requests and months of work. Thank you to everyone in the community who contributed code, opened issues, tried early builds, and shared feedback along the way.

Open-source, built in public, shaped by the people who use it.

💚 Hugo