---
title: Setup Commands
summary: Onboard, run, doctor, and configure
---

Instance setup and diagnostics commands.

Examples on this page use the installed `penclip` command. If you are running without installing first, prefix the command with `npx`.

## `penclip run`

One-command bootstrap and start:

```sh
penclip run
```

Does:

1. Auto-onboards if config is missing
2. Runs `penclip doctor` with repair enabled
3. Starts the server when checks pass

Choose a specific instance:

```sh
penclip run --instance dev
```

## `penclip onboard`

Interactive first-time setup:

```sh
penclip onboard
```

If Paperclip is already configured, rerunning `onboard` keeps the existing config in place. Use `penclip configure` to change settings on an existing install.

First prompt:

1. `Quickstart` (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
2. `Advanced setup`: full interactive configuration

Start immediately after onboarding:

```sh
penclip onboard --run
```

Non-interactive defaults + immediate start (opens browser on server listen):

```sh
penclip onboard --yes
```

On an existing install, `--yes` now preserves the current config and just starts Paperclip with that setup.

## `penclip doctor`

Health checks with optional auto-repair:

```sh
penclip doctor
penclip doctor --repair
```

Validates:

- Server configuration
- Database connectivity
- Secrets adapter configuration
- Storage configuration
- Missing key files

## `penclip configure`

Update configuration sections:

```sh
penclip configure --section server
penclip configure --section secrets
penclip configure --section storage
```

## `penclip env`

Show resolved environment configuration:

```sh
penclip env
```

This now includes bind-oriented deployment settings such as `PAPERCLIP_BIND` and `PAPERCLIP_BIND_HOST` when configured.

## `penclip allowed-hostname`

Allow a private hostname for authenticated/private mode:

```sh
penclip allowed-hostname my-tailscale-host
```

## Local Storage Paths

| Data | Default Path |
|------|-------------|
| Config | `~/.paperclip/instances/default/config.json` |
| Database | `~/.paperclip/instances/default/db` |
| Logs | `~/.paperclip/instances/default/logs` |
| Storage | `~/.paperclip/instances/default/data/storage` |
| Secrets key | `~/.paperclip/instances/default/secrets/master.key` |

Override with:

```sh
PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev penclip run
```

Or pass `--data-dir` directly on any command:

```sh
penclip run --data-dir ./tmp/paperclip-dev
penclip doctor --data-dir ./tmp/paperclip-dev
```