docs/cli/setup-commands.md

metadata

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:

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:

penclip run --instance dev

penclip onboard

Interactive first-time setup:

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:

penclip onboard --run

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

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:

penclip doctor
penclip doctor --repair

Validates:

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

penclip configure

Update configuration sections:

penclip configure --section server
penclip configure --section secrets
penclip configure --section storage

penclip env

Show resolved environment configuration:

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:

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:

PAPERCLIP_HOME=/custom/home PAPERCLIP_INSTANCE_ID=dev penclip run

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

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