> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thinkingmach.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

The Paperclip CLI handles instance setup, diagnostics, and control-plane operations.

## Usage

```sh theme={null}
pnpm paperclipai --help
```

## Global Options

All commands support:

| Flag                | Description                                              |
| ------------------- | -------------------------------------------------------- |
| `--data-dir <path>` | Local Paperclip data root (isolates from `~/.paperclip`) |
| `--api-base <url>`  | API base URL                                             |
| `--api-key <token>` | API authentication token                                 |
| `--context <path>`  | Context file path                                        |
| `--profile <name>`  | Context profile name                                     |
| `--json`            | Output as JSON                                           |

Company-scoped commands also accept `--company-id <id>`.

For clean local instances, pass `--data-dir` on the command you run:

```sh theme={null}
npx paperclipai run --data-dir ./tmp/paperclip-dev
```

## Context Profiles

Store defaults to avoid repeating flags:

```sh theme={null}
# Set defaults
npx paperclipai context set --api-base http://localhost:3100 --company-id <id>

# View current context
pnpm paperclipai context show

# List profiles
pnpm paperclipai context list

# Switch profile
npx paperclipai context use default
```

To avoid storing secrets in context, use an env var:

```sh theme={null}
npx paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...
```

Secret operations are available under `paperclipai secrets`:

```sh theme={null}
npx paperclipai secrets declarations --company-id <company-id> --kind secret
npx paperclipai secrets create --company-id <company-id> --name anthropic-api-key --value-env ANTHROPIC_API_KEY
npx paperclipai secrets link --company-id <company-id> --name prod-stripe-key --provider aws_secrets_manager --external-ref <provider-ref>
npx paperclipai secrets doctor --company-id <company-id>
npx paperclipai secrets migrate-inline-env --company-id <company-id> --apply
```

Context is stored at `~/.paperclip/context.json`.

## Command Categories

The CLI has two categories:

1. **[Setup commands](/cli/setup-commands)** — instance bootstrap, diagnostics, configuration
2. **[Control-plane commands](/cli/control-plane-commands)** — issues, agents, approvals, activity