---
title: "CLI"
description: "Shelve CLI is a command-line interface designed for the Shelve app."
canonical_url: "https://shelve.cloud/docs/cli"
---
# CLI

> Shelve CLI is a command-line interface designed for the Shelve app.

The CLI is the primary way to sync secrets between your terminal and [Shelve](https://shelve.cloud). 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.

<callout type="tip">

New to AI agents or CI? Start with [Agents & automation](https://shelve.cloud/docs/cli/agents-automation) and install the published skill: `npx skills add https://shelve.cloud`

</callout>

## Installation

Install `@shelve/cli` in your project or globally. See the [Quickstart](https://shelve.cloud/docs/getting-started/quickstart) guide.

```bash [terminal]
pnpm add -D @shelve/cli
```

## Command overview

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/run">
        <code>
          run
        </code>
      </a>
    </td>
    
    <td>
      Inject secrets into a child process (preferred)
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/init">
        <code>
          init
        </code>
      </a>
    </td>
    
    <td>
      Agent-safe ignore files + <code>
        .gitignore
      </code>
      
       block
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/login-logout">
        <code>
          login
        </code>
      </a>
      
       / <a href="https://shelve.cloud/docs/cli/login-logout">
        <code>
          logout
        </code>
      </a>
    </td>
    
    <td>
      Manage stored credentials
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/login-logout">
        <code>
          me
        </code>
      </a>
    </td>
    
    <td>
      Show the logged-in user
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/push-pull">
        <code>
          push
        </code>
      </a>
      
       / <a href="https://shelve.cloud/docs/cli/push-pull">
        <code>
          pull
        </code>
      </a>
    </td>
    
    <td>
      Sync secrets with Shelve
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/sync-policies">
        <code>
          diff
        </code>
      </a>
      
       / <a href="https://shelve.cloud/docs/cli/sync-policies">
        <code>
          sync
        </code>
      </a>
    </td>
    
    <td>
      Compare or apply sync policy
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/create">
        <code>
          create
        </code>
      </a>
    </td>
    
    <td>
      Create a project + <code>
        shelve.json
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/config">
        <code>
          config
        </code>
      </a>
    </td>
    
    <td>
      Show merged configuration
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/generate">
        <code>
          generate
        </code>
      </a>
    </td>
    
    <td>
      Generate <code>
        .env.example
      </code>
      
       or ESLint config
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/upgrade">
        <code>
          upgrade
        </code>
      </a>
    </td>
    
    <td>
      Update the CLI package
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/troubleshooting">
        <code>
          doctor
        </code>
      </a>
    </td>
    
    <td>
      Validate config, auth, API, and cache
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/agents-automation">
        <code>
          agents-automation
        </code>
      </a>
    </td>
    
    <td>
      Global flags, JSON output, CI & agents
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://shelve.cloud/docs/cli/troubleshooting">
        <code>
          troubleshooting
        </code>
      </a>
    </td>
    
    <td>
      Error codes and common fixes
    </td>
  </tr>
</tbody>
</table>

## Global flags

Available on **every** command (before or after the subcommand):

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Alias
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Machine-readable stdout; structured errors on stderr
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quiet
      </code>
    </td>
    
    <td>
      <code>
        -q
      </code>
    </td>
    
    <td>
      No spinners or clack UI
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --yes
      </code>
    </td>
    
    <td>
      <code>
        -y
      </code>
    </td>
    
    <td>
      Skip confirmation prompts
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --non-interactive
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Fail instead of prompting
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --debug
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Verbose logs (<code>
        SHELVE_DEBUG=1
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

## 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](https://shelve.cloud/schema.json)

```json [shelve.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. Put the settings every package shares in the root file and the `project` in each package:

<code-tree default-value="shelve.json">

```json [apps/app/shelve.json]
{
  "project": "@nuxt/app"
}
```

```json [apps/api/shelve.json]
{
  "project": "@nuxt/api"
}
```

```json [shelve.json]
{
  "slug": "nuxtlabs",
  "defaultEnv": "development"
}
```

</code-tree>

The package config wins wherever the two disagree.

#### Running from the root

`push`, `pull`, `diff` and `sync` run once per package that has its own config file:

```bash [terminal]
shelve pull
```

That writes `apps/app/.env` and `apps/api/.env`. Packages without a config file are skipped, as is the root itself.

Target a single package with `--path`:

```bash [terminal]
shelve pull --path apps/app
```

To treat the root as a project of its own instead, give it a `project` in the root `shelve.json`. A bare command then runs in the root instead of fanning out. `--path` still targets a single package.

Inside a package, commands behave as they always have and only touch that package:

```bash [apps/app/terminal]
shelve pull
```

`run` is the exception: it executes your command in the current directory and never fans out.

## Configuration options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        project
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        SHELVE_PROJECT
      </code>
      
       or nearest <code>
        package.json
      </code>
      
       name
    </td>
    
    <td>
      Project name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        slug
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        SHELVE_TEAM_SLUG
      </code>
    </td>
    
    <td>
      Team slug
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        token
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Keychain / <code>
        $XDG_CONFIG_HOME/.shelve
      </code>
      
       / <code>
        SHELVE_TOKEN
      </code>
    </td>
    
    <td>
      API token
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        https://app.shelve.cloud
      </code>
    </td>
    
    <td>
      Shelve instance URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        defaultEnv
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Default environment for <code>
        run
      </code>
      
      , <code>
        push
      </code>
      
      , <code>
        pull
      </code>
      
      , <code>
        diff
      </code>
      
      , <code>
        sync
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        confirmChanges
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
    
    <td>
      Confirm before push/pull writes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        envFileName
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <code>
        .env
      </code>
    </td>
    
    <td>
      Local env file name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        autoUppercase
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Uppercase keys on push
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        autoCreateProject
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Create project if missing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sync
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      <a href="https://shelve.cloud/docs/cli/sync-policies">
        Sync policies
      </a>
      
       (per-env push/pull rules)
    </td>
  </tr>
</tbody>
</table>

## Environment variables

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        SHELVE_PROJECT
      </code>
    </td>
    
    <td>
      Project name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SHELVE_TEAM_SLUG
      </code>
    </td>
    
    <td>
      Team slug
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SHELVE_TOKEN
      </code>
    </td>
    
    <td>
      Authentication token
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SHELVE_URL
      </code>
    </td>
    
    <td>
      Shelve instance URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SHELVE_DEFAULT_ENV
      </code>
    </td>
    
    <td>
      Default environment
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SHELVE_DEBUG=1
      </code>
    </td>
    
    <td>
      Enable debug logging
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AI_AGENT
      </code>
    </td>
    
    <td>
      Force AI-agent shell detection
    </td>
  </tr>
</tbody>
</table>

Credentials are stored in the **OS keychain** when available, with an XDG file fallback (`~/.config/.shelve`, mode `0600`).


## Sitemap

See the full [sitemap](https://shelve.cloud/sitemap.md) for all pages.
