# Paperclip AI Onboard Command Configuration Options: Complete CLI and Environment Guide

> Master paperclipai onboard command configuration with our complete CLI and environment variable guide. Discover all six flags and 20+ env vars for database, auth, and server settings.

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

---

**The `paperclipai onboard` command supports six CLI flags (`--config`, `--run`, `--yes`, `--invokedByRun`, `--bind`, `--installService`) and over 20 environment variables that pre-populate database, storage, auth, and server settings.**

The `paperclipai onboard` command in the [paperclipai/paperclip](https://github.com/paperclipai/paperclip) repository is the entry point for first-time deployment setup. Understanding its configuration options lets you automate installations, customize bind modes, and pre-configure infrastructure without interactive prompts.

## CLI Flags for paperclipai Onboard

The command accepts options defined by the `OnboardOptions` interface in [`cli/src/commands/onboard.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/commands/onboard.ts) (lines 60–66).

### `--config`: Custom Configuration File Path

Specify an alternative location for the generated [`paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/paperclip.yaml) file instead of the default Paperclip home directory.

```bash
paperclipai onboard --config=/etc/paperclip/paperclip.yaml

```

### `--run`: Auto-Start After Configuration

Starts the Paperclip server immediately after writing the configuration file. Skipped if `--installService` is used (service installation implies background execution).

```bash
paperclipai onboard --run

```

### `--yes`: Skip Interactive Prompts

Forces **quick-start defaults** without user interaction. Also applies trusted-local defaults for bind mode when `--bind` is omitted.

```bash
paperclipai onboard --yes

```

### `--invokedByRun`: Internal Re-Entry Flag

Used internally when `paperclipai run` re-enters the onboarding flow. Suppresses the "Start Paperclip now?" confirmation prompt. Not intended for manual use.

### `--bind`: Select Network Bind Preset

Manually chooses the server bind mode. Valid values: `"loopback"`, `"lan"`, `"tailnet"`. Invalid values throw an error during early validation.

```bash

# Bind to LAN address for local network access

paperclipai onboard --bind=lan

# Bind to Tailnet interface for secure remote access

paperclipai onboard --bind=tailnet

```

If omitted, the bind mode is inferred from environment variables via `quickstartDefaultsFromEnv`.

### `--installService`: Install as System Service

Attempts to install Paperclip as a background service using systemd (Linux), launchd (macOS), or equivalent after configuration completes.

```bash
paperclipai onboard --installService --yes

```

## Environment Variables for paperclipai Onboard Configuration

When `--yes` is **not** used, the onboarding flow collects defaults from environment variables defined in `ONBOARD_ENV_KEYS`. The `quickstartDefaultsFromEnv` function (lines 42–46 and following) parses these and tracks which were applied versus ignored.

### Server and Authentication

| Variable | Purpose |
|----------|---------|
| `PAPERCLIP_PUBLIC_URL`, `PAPERCLIP_AUTH_PUBLIC_BASE_URL`, `BETTER_AUTH_URL`, `BETTER_AUTH_BASE_URL` | Public base URL for authentication service |
| `PAPERCLIP_DEPLOYMENT_MODE` | Deployment mode: `local_trusted`, `authenticated`, etc. |
| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | Exposure level: `private` or `public` |
| `PAPERCLIP_BIND`, `PAPERCLIP_BIND_HOST`, `PAPERCLIP_TAILNET_BIND_HOST`, `HOST` | Bind mode and host address selection |
| `PORT` | Override default port `3100` |
| `SERVE_UI` | Enable (`true`) or disable (`false`) UI serving |
| `PAPERCLIP_ALLOWED_HOSTNAMES` | Additional permitted hostnames |
| `PAPERCLIP_AUTH_BASE_URL_MODE` | Force auth URL mode: `auto` or `explicit` |

### Database Configuration

| Variable | Purpose |
|----------|---------|
| `DATABASE_URL` | Switch to **PostgreSQL** mode with connection string |
| `PAPERCLIP_DB_BACKUP_*` | Backup settings: enable/disable, interval (minutes), retention (days) |

### Storage Backend

| Variable | Purpose |
|----------|---------|
| `PAPERCLIP_STORAGE_PROVIDER` | Choose `local` or `s3` |
| `PAPERCLIP_STORAGE_LOCAL_DIR` | Local storage directory path |
| `PAPERCLIP_STORAGE_S3_*` | S3 bucket, region, credentials, and endpoint settings |

### Secrets Management

| Variable | Purpose |
|----------|---------|
| `PAPERCLIP_SECRETS_PROVIDER` | Select `local-encrypted`, `aws-secrets-manager`, etc. |
| `PAPERCLIP_SECRETS_STRICT_MODE` | Enable strict mode behavior |
| `PAPERCLIP_SECRETS_MASTER_KEY_FILE` | Path to master key file |

## How paperclipai Onboard Builds the Final Configuration

The `onboard` function in [`cli/src/commands/onboard.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/commands/onboard.ts) orchestrates an 8-step pipeline:

1. **Parse CLI flags** → `OnboardOptions`
2. **Read existing config** (if present) for preservation or repair
3. **Collect environment defaults** → `quickstartDefaultsFromEnv`
4. **Apply bind preset** → `buildPresetServerConfig` (from [`cli/src/config/server-bind.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/config/server-bind.ts))
5. **Interactive prompts** (only in `advanced` mode: `promptDatabase`, `promptLlm`, `promptLogging`, `promptServer`, `promptStorage`)
6. **Generate secrets** → `ensureAgentJwtSecret`, `ensureLocalSecretsKeyFile`
7. **Write configuration** → `writeConfig` (in [`cli/src/config/store.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/config/store.ts))
8. **Optional server start** based on `--run` flag or user confirmation

The `quickstartDefaultsFromEnv` return value includes:
- `defaults`: fully-populated `OnboardDefaults` with `database`, `logging`, `server`, `auth`, `storage`, `secrets`
- `usedEnvKeys`: variables that influenced the configuration
- `ignoredEnvKeys`: variables skipped (e.g., when `--yes` forces loopback defaults)

## Practical Examples

### Quick-Start with Defaults

```bash
paperclipai onboard --yes

```

Creates default config, generates JWT secret, prints next steps. No interaction required.

### LAN Deployment with Immediate Start

```bash
paperclipai onboard --bind=lan --run

```

Forces LAN binding, skips setup path prompt, writes config, starts server.

### Custom Config Path with Service Installation

```bash
paperclipai onboard \
  --config=/opt/paperclip/config.yaml \
  --installService \
  --yes

```

### Environment-Driven S3 + Tailnet Setup

```bash
export PAPERCLIP_STORAGE_PROVIDER=s3
export PAPERCLIP_STORAGE_S3_BUCKET=my-bucket
export PAPERCLIP_STORAGE_S3_REGION=us-east-1
export DATABASE_URL=postgres://user:pass@localhost/paperclip

paperclipai onboard --bind=tailnet

```

Environment variables configure Postgres database and S3 storage; CLI flag applies Tailnet bind preset on top.

## Key Source Files

| File | Purpose |
|------|---------|
| [`cli/src/commands/onboard.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/commands/onboard.ts) | Main onboarding implementation, `OnboardOptions` interface, `quickstartDefaultsFromEnv` |
| [`cli/src/config/store.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/config/store.ts) | Config read/write/backup utilities (`writeConfig`) |
| [`cli/src/config/schema.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/config/schema.ts) | `PaperclipConfig` type definitions and validation |
| [`cli/src/prompts/server.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/prompts/server.ts) | Advanced server setting prompts |
| [`cli/src/config/server-bind.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/config/server-bind.ts) | Preset server configs for loopback/LAN/Tailnet |

## Summary

- **Six CLI flags** control file paths, automation, bind modes, and service installation
- **20+ environment variables** pre-populate database, storage, auth, and server settings via `quickstartDefaultsFromEnv`
- **`--yes`** enables non-interactive quick-start with trusted-local defaults
- **`--bind`** manually selects `loopback`, `lan`, or `tailnet` network exposure
- **Environment variables are ignored** when they conflict with `--yes` forced defaults
- All configuration flows through [`cli/src/commands/onboard.ts`](https://github.com/paperclipai/paperclip/blob/main/cli/src/commands/onboard.ts) and persists to [`paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/paperclip.yaml)

## Frequently Asked Questions

### What happens if I use `--yes` and also set environment variables?

Environment variables that conflict with trusted-local defaults are **ignored**. The `quickstartDefaultsFromEnv` function tracks these in `ignoredEnvKeys`. For example, `PAPERCLIP_BIND` settings are overridden when `--yes` forces loopback mode without an explicit `--bind` argument.

### Can I automate paperclipai onboard in CI/CD pipelines?

Yes. Combine `--yes` with `--bind` and pre-set environment variables for non-interactive deployments. For containerized environments, use `DATABASE_URL` and storage provider variables to eliminate all prompts.

### How do I migrate from quick-start to advanced configuration later?

Run `paperclipai onboard` again without `--yes`. The existing [`paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/paperclip.yaml) is read and preserved; interactive prompts in advanced mode let you modify `database`, `llm`, `logging`, `server`, and `storage` sections via `promptDatabase`, `promptLlm`, `promptLogging`, `promptServer`, and `promptStorage`.