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

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 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 (lines 60–66).

--config: Custom Configuration File Path

Specify an alternative location for the generated paperclip.yaml file instead of the default Paperclip home directory.

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).

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.

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.

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

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 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)
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)
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

paperclipai onboard --yes

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

LAN Deployment with Immediate Start

paperclipai onboard --bind=lan --run

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

Custom Config Path with Service Installation

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

Environment-Driven S3 + Tailnet Setup

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	Main onboarding implementation, OnboardOptions interface, quickstartDefaultsFromEnv
cli/src/config/store.ts	Config read/write/backup utilities (writeConfig)
cli/src/config/schema.ts	PaperclipConfig type definitions and validation
cli/src/prompts/server.ts	Advanced server setting prompts
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 and persists to 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 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.

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