docs/cli/setup-commands.md

metadata

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

Instance setup and diagnostics commands.

paperclipai run

One-command bootstrap and start:

pnpm paperclipai run

Does:

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

Choose a specific instance:

pnpm paperclipai run --instance dev

paperclipai onboard

Interactive first-time setup:

pnpm paperclipai onboard

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:

pnpm paperclipai onboard --run

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

pnpm paperclipai onboard --yes

paperclipai doctor

Health checks with optional auto-repair:

pnpm paperclipai doctor
pnpm paperclipai doctor --repair

Validates:

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

paperclipai configure

Update configuration sections:

pnpm paperclipai configure --section server
pnpm paperclipai configure --section secrets
pnpm paperclipai configure --section storage

paperclipai env

Show resolved environment configuration:

pnpm paperclipai env

paperclipai allowed-hostname

Allow a private hostname for authenticated/private mode:

pnpm paperclipai 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:

PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev pnpm paperclipai run

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

pnpm paperclipai run --data-dir ./tmp/paperclip-dev
pnpm paperclipai doctor --data-dir ./tmp/paperclip-dev