How to Use the Paperclip CLI for Onboarding: Complete Setup Guide

The Paperclip CLI (paperclipai onboard) bootstraps a fresh Paperclip installation by generating configuration, running health checks, and optionally launching the server—all in a single command.

The Paperclip CLI is the official command-line tool for initializing and managing Paperclip instances. Whether you're running a quick local test or deploying an authenticated production instance, the onboard command handles the heavy lifting. This guide explains how to use the Paperclip CLI for onboarding based on the actual implementation in the paperclipai/paperclip repository.

What Happens During Paperclip CLI Onboarding

The paperclipai onboard command executes a three-stage workflow defined in the CLI source:

1. Configuration & Secrets Generation – Creates ~/.paperclip/instances/default/config.json with defaults for embedded PostgreSQL, local storage, and a generated master key. This mirrors the auto-onboarding step in the Quick-Start guide.

2. Health-Check & Repair – Runs the doctor command to validate server settings, database connectivity, secret-provider configuration, and required key files—automatically repairing detected issues as documented here.

3. Server Startup – Launches the Paperclip server (pnpm paperclipai run) which starts the Express API and React UI on http://localhost:3100. In trusted-local mode, this uses an embedded PostgreSQL instance with no external database required per the CLI README.

Installation and Basic Onboarding Commands

One-Command Onboarding (Non-Interactive)

For scripts or CI/CD pipelines, run a silent onboarding with all defaults:

npx paperclipai onboard --yes

This creates the instance directory at ~/.paperclip/instances/default/ and exits without prompts.

Interactive Onboarding with Immediate Server Start

To configure options manually and launch right away:

pnpm paperclipai onboard --run

The --run flag automatically executes paperclipai run after onboarding completes.

Network Binding Modes for Authenticated Deployment

The Paperclip CLI supports two primary deployment modes selected during onboarding:

Mode	Use Case	Flag
trusted-local	Local development on localhost	default (no flag)
authenticated/private	LAN or Tailscale access	--bind <mode>

Onboard for LAN Access

Make your instance reachable by other devices on your local network:

pnpm paperclipai onboard --yes --bind lan

Onboard for Tailnet Deployment

Deploy privately across your Tailscale network:

pnpm paperclipai onboard --yes --bind tailnet

These binding modes are defined in [cli/README.md](https://github.com/paperclipai/paperclip/blob/master/cli/README.md#L87-L93).

Essential Paperclip CLI Onboarding Flags

Flag	Effect	Source Reference
--yes	Non-interactive mode with all defaults	[docs/cli/setup-commands.md](https://github.com/paperclipai/paperclip/blob/master/docs/cli/setup-commands.md)
--run	Start server immediately after onboarding	[cli/README.md](https://github.com/paperclipai/paperclip/blob/master/cli/README.md)
--bind <mode>	Network binding: lan, tailnet, etc.	[cli/README.md](https://github.com/paperclipai/paperclip/blob/master/cli/README.md#L87-L93)
--data-dir <path>	Override default data directory	docs/cli/setup-commands.md#L22-L30

Instance Data Directory Structure

All runtime data is organized under ~/.paperclip/instances/<instance-id>/ as shown here:

~/.paperclip/
└── instances/
    └── default/
        ├── config.json      # Server configuration

        ├── db/              # Embedded PostgreSQL data

        ├── logs/            # Application logs

        ├── storage/         # Local file storage

        └── .secret_key      # Master encryption key

Customizing the Instance Location

Override defaults using environment variables or CLI options:

# Use environment variables

export PAPERCLIP_HOME=/opt/paperclip
export PAPERCLIP_INSTANCE_ID=production
pnpm paperclipai onboard

# Or use CLI flag

pnpm paperclipai onboard --data-dir /opt/paperclip/instances/production

Starting Paperclip After Onboarding

If you onboarded without --run, start the server later with:

pnpm paperclipai run

This command reads the configuration from ~/.paperclip/instances/default/config.json and launches both the Express API backend and React frontend.

Onboarding Templates and Default Assets

Fresh instances receive default configuration from server/src/onboarding-assets/, which contains:

• Default agent templates
• Initial company/organization structure

These assets are applied automatically when paperclipai onboard creates a new instance.

Summary

• Run npx paperclipai onboard --yes for automated, non-interactive setup with embedded PostgreSQL.
• Use --run to launch the server immediately after configuration.
• Specify --bind lan or --bind tailnet for authenticated network access beyond localhost.
• All instance data lives in ~/.paperclip/instances/<instance-id>/ and is customizable via PAPERCLIP_HOME, PAPERCLIP_INSTANCE_ID, or --data-dir.
• The doctor command runs automatically during onboarding to validate and repair your installation.

Frequently Asked Questions

What is the fastest way to onboard Paperclip?

Run npx paperclipai onboard --yes. This single command downloads the CLI if needed, generates default configuration with embedded PostgreSQL, validates the installation, and completes setup without any prompts.

Do I need an external PostgreSQL database for onboarding?

No. By default, the Paperclip CLI uses an embedded PostgreSQL instance stored in your data directory (~/.paperclip/instances/default/db/). External databases are only required for production deployments with specific infrastructure requirements.

How do I move my Paperclip instance to a different directory?

Set the PAPERCLIP_HOME environment variable before running any command, or use the --data-dir flag during onboarding. For example: PAPERCLIP_HOME=/mnt/paperclip pnpm paperclipai onboard.

What should I do if onboarding fails or reports errors?

The onboard command automatically runs the doctor diagnostic tool, which checks database connectivity, secret-provider configuration, and required key files. Most issues are repaired automatically; for persistent problems, run pnpm paperclipai doctor manually and review the logs in ~/.paperclip/instances/<instance-id>/logs/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}