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

> Master the Paperclip CLI for seamless onboarding. Generate configs, run health checks, and launch your server with a single command. Get your Paperclip setup guide now.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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](https://github.com/paperclipai/paperclip/blob/master/docs/start/quickstart.md#L11-L16).

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](https://github.com/paperclipai/paperclip/blob/master/docs/cli/setup-commands.md#L57-L64).

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](https://github.com/paperclipai/paperclip/blob/master/cli/README.md#L83-L94).

## Installation and Basic Onboarding Commands

### One-Command Onboarding (Non-Interactive)

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

```bash
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:

```bash
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:

```bash
pnpm paperclipai onboard --yes --bind lan

```

### Onboard for Tailnet Deployment

Deploy privately across your Tailscale network:

```bash
pnpm paperclipai onboard --yes --bind tailnet

```

These binding modes are defined in [[`cli/README.md`](https://github.com/paperclipai/paperclip/blob/main/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/main/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/main/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/main/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`](https://github.com/paperclipai/paperclip/blob/master/docs/cli/setup-commands.md#L22-L30) |

## Instance Data Directory Structure

All runtime data is organized under `~/.paperclip/instances/<instance-id>/` [as shown here](https://github.com/paperclipai/paperclip/blob/master/docs/cli/setup-commands.md#L110-L118):

```

~/.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:

```bash

# 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:

```bash
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/`](https://github.com/paperclipai/paperclip/tree/master/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/`.