CLI
The CLI is the primary way to sync secrets between your terminal and Shelve. Use it to inject variables at runtime (shelve run), push local changes upstream, or pull secrets to disk when you really need a .env file.
npx skills add https://shelve.cloudInstallation
Install @shelve/cli in your project or globally. See the Quickstart guide.
pnpm add -D @shelve/cli
Command overview
| Command | Description |
|---|---|
run | Inject secrets into a child process (preferred) |
init | Agent-safe ignore files + .gitignore block |
login / logout | Manage stored credentials |
me | Show the logged-in user |
push / pull | Sync secrets with Shelve |
diff / sync | Compare or apply sync policy |
create | Create a project + shelve.json |
config | Show merged configuration |
generate | Generate .env.example or ESLint config |
upgrade | Update the CLI package |
doctor | Validate config, auth, API, and cache |
agents-automation | Global flags, JSON output, CI & agents |
troubleshooting | Error codes and common fixes |
Global flags
Available on every command (before or after the subcommand):
| Flag | Alias | Description |
|---|---|---|
--json | Machine-readable stdout; structured errors on stderr | |
--quiet | -q | No spinners or clack UI |
--yes | -y | Skip confirmation prompts |
--non-interactive | Fail instead of prompting | |
--debug | Verbose logs (SHELVE_DEBUG=1) |
Configuration
Configuration is loaded from the current working directory. Supported filenames: shelve.json, shelve.config.json, .shelverc.json. If none exists and a command requires config, the CLI can create shelve.json interactively (or fail in non-interactive mode).
JSON Schema: shelve.cloud/schema.json
{
"$schema": "https://shelve.cloud/schema.json",
"slug": "nuxtlabs",
"project": "@nuxt/ui",
"defaultEnv": "development",
"confirmChanges": false,
"autoCreateProject": true
}
Monorepo support
Shelve detects monorepo roots and merges the root shelve.json with the local one (shared team slug, per-package project, etc.):
{
"slug": "nuxtlabs"
}
Commands always run in the current directory — they do not automatically execute across every package in the monorepo.
Configuration options
| Option | Type | Default | Description |
|---|---|---|---|
project | string | SHELVE_PROJECT or nearest package.json name | Project name |
slug | string | SHELVE_TEAM_SLUG | Team slug |
token | string | Keychain / $XDG_CONFIG_HOME/.shelve / SHELVE_TOKEN | API token |
url | string | https://app.shelve.cloud | Shelve instance URL |
defaultEnv | string | — | Default environment for run, push, pull |
confirmChanges | boolean | false | Confirm before push/pull writes |
envFileName | string | .env | Local env file name |
autoUppercase | boolean | true | Uppercase keys on push |
autoCreateProject | boolean | true | Create project if missing |
sync | object | — | Sync policies (per-env push/pull rules) |
Environment variables
| Variable | Description |
|---|---|
SHELVE_PROJECT | Project name |
SHELVE_TEAM_SLUG | Team slug |
SHELVE_TOKEN | Authentication token |
SHELVE_URL | Shelve instance URL |
SHELVE_DEFAULT_ENV | Default environment |
SHELVE_DEBUG=1 | Enable debug logging |
AI_AGENT | Force AI-agent shell detection |
Credentials are stored in the OS keychain when available, with an XDG file fallback (~/.config/.shelve, mode 0600).