Setup Commands

Use these commands when you are standing up a Paperclip instance, repairing it, or changing the settings the server runs on. They touch the install and launch — config files, the local database, secrets, storage, host binding, and the bootstrap credential. They do not create companies, file issues, or wake agents. That work belongs to the control-plane commands documented under company, issue, agent, and the rest of the reference.

The mental split is simple: setup commands answer "is this instance configured and running?"; control-plane commands answer "what is the company doing?". The one command that lives in both worlds is run, and this page is careful to separate its two meanings.

When to reach for these

Reach for setup commands when you need to:

• create the initial config and local data directories (onboard)
• verify and repair an install before or after a config change (doctor)
• print the environment block a remote deployment will need (env)
• change deployment mode, database, storage, secrets, or logging (configure)
• take a one-off database snapshot (db:backup)
• trust a private hostname in authenticated mode (allowed-hostname)
• bootstrap and launch a local server in one step (run)
• mint the first board credential headlessly (auth bootstrap-ceo)
• trigger one agent heartbeat for debugging (heartbeat run)
• pause every routine in a company during an incident (routines disable-all)

Note: Examples use the installed binary paperclipai. Inside the monorepo you can substitute pnpm paperclipai; see Installation.

paperclipai run (local bootstrap)

Warning: paperclipai run with no subcommand is a setup command: it bootstraps and starts a local server. The run subcommands (run list, run get, run events, run log, run cancel, and friends) are a different feature — they inspect and control heartbeat runs over the API and are documented in Runs. Do not confuse the two.

The bare run is the shortest route from "nothing" to "a healthy local instance accepting requests". It is a thin orchestrator:

1. Resolves the instance id and config path, creates ~/.paperclip and the instance root if missing.
2. If no config exists and you are in a TTY, it hands off to onboard interactively. In a non-interactive shell it errors and tells you to run onboard first.
3. Runs doctor with repair enabled by default; if any check fails it stops without starting the server.
4. Starts the Paperclip server.
5. If the instance is in authenticated mode with the embedded database, it generates a bootstrap CEO invite after startup (see auth bootstrap-ceo).

paperclipai run
paperclipai run --instance dev
paperclipai run --data-dir ./tmp/paperclip-dev
paperclipai run --no-repair

Tip: --bind only matters on the very first run, when it forwards the preset to onboarding. Once a config exists, run reuses it; change binding later with configure --section server.

paperclipai onboard

Interactive first-run setup. Use it to create a brand-new local install or to rebuild the config from guided prompts. It writes the config (default ~/.paperclip/instances/<id>/config.json), provisions the PAPERCLIP_AGENT_JWT_SECRET into the adjacent .env file, and creates the local secrets key file.

paperclipai onboard
paperclipai onboard --yes
paperclipai onboard --run
paperclipai onboard --bind lan

The first prompt offers two paths:

Note: If a valid config already exists, onboard preserves it unchanged, ensures the agent JWT secret and secrets key exist, and prints next-step commands. Use configure to change settings on an existing install rather than re-onboarding.

When the instance is authenticated with the embedded database, the bootstrap CEO invite is deferred until the server is running — onboard reminds you to run paperclipai run then auth bootstrap-ceo.

paperclipai doctor

Diagnostic checks with optional repair. Run it before starting the server, after editing config, or any time the instance misbehaves. run invokes doctor for you; call it directly when you only want the report.

paperclipai doctor
paperclipai doctor --repair
paperclipai doctor --repair --yes

It loads the config's .env, then runs these checks in order, stopping early only if the config itself is invalid:

• config validity (must pass first)
• deployment / auth mode compatibility
• agent JWT secret
• secrets adapter
• storage
• database connectivity
• LLM provider
• log directory
• listen port

Each line reports ✓ pass, ! warn, or ✗ fail with a repair hint. The summary counts passed/warned/failed, and a clear "fix and re-run" message is printed when anything fails.

Warning: --repair can create or update local files (the JWT .env, the secrets key, the log directory) when a check knows how to fix the problem. Review the output before running it against a shared or production-like instance, and pair it with --yes only when you trust the repairs.

paperclipai env

Print the environment variables a deployment needs, with each value's source and a ready-to-paste export block. Use it to inspect what the instance actually resolves after config, defaults, and environment overrides are merged — and to seed the env of a remote/containerized deployment.

paperclipai env

It reads the config (warning, not failing, if the file is missing or unparseable), then prints two sections, Required and Optional, marking each variable as set, default, or missing. The required variables are PAPERCLIP_AGENT_JWT_SECRET and DATABASE_URL; optional entries cover PORT, PAPERCLIP_PUBLIC_URL, BETTER_AUTH_TRUSTED_ORIGINS, the agent-JWT and heartbeat-scheduler tunables, and the full secrets/storage provider set. Missing values appear in the export block as <set-this-value> so you can fill them in.

Tip: Pipe the export block into your shell or a deployment manifest. Anything still marked missing must be supplied before the server will start cleanly.

paperclipai configure

Update one or more configuration sections on an existing install without rebuilding it. Each save rewrites the config and stamps its metadata. Run it interactively to pick sections from a menu, or target one directly with --section.

paperclipai configure
paperclipai configure --section server
paperclipai configure --section database
paperclipai configure --section storage
paperclipai configure --section secrets
paperclipai configure --section logging
paperclipai configure --section llm

Note: configure requires an existing config — it errors and tells you to run onboard first if none is found. When you pass --section, it configures that section once and exits; without it, it loops so you can edit several sections in a row.

paperclipai db:backup

Create a one-off snapshot of the instance database using the current config. This is a manual backup on top of (and independent of) the scheduled backups the server runs. It resolves the connection string in order: DATABASE_URL, then a configured postgres connection string, then the embedded-postgres default.

paperclipai db:backup
paperclipai db:backup --dir /backups/paperclip
paperclipai db:backup --retention-days 14
paperclipai db:backup --json

Tip: For the embedded database you can run a backup without the server up — db:backup connects on the embedded port directly. Verify where it landed with the printed Backup dir.

paperclipai allowed-hostname

Add a hostname to the instance's allowlist so it is accepted in authenticated/private mode. Use it when Paperclip rejects a host that should be trusted on a private network (for example a Tailscale machine name).

paperclipai allowed-hostname dotta-macbook-pro
paperclipai allowed-hostname my-host.ts.net

The command updates the local config in place. A new entry takes effect only after you restart the server. Allowed hostnames are enforced only in authenticated + private mode; in any other mode the command notes that the setting is inert.

paperclipai auth bootstrap-ceo

Mint the first board credential headlessly by inserting a one-time bootstrap invite into the database and printing its URL. This is how an authenticated instance gets its initial instance admin without a pre-existing login. On a local_trusted instance it is unnecessary — loopback is treated as implicit board authority — and the command says so and exits.

paperclipai auth bootstrap-ceo
paperclipai auth bootstrap-ceo --expires-hours 24
paperclipai auth bootstrap-ceo --force
paperclipai auth bootstrap-ceo --base-url https://paperclip.example.com

If an admin already exists it refuses unless you pass --force. Each run also revokes any outstanding, unaccepted bootstrap-CEO invites before issuing a fresh one. With the embedded database, the server must be running (or the embedded cluster started) for the insert to succeed; the command tells you to start the server and retry if it cannot connect.

Note: After this first credential exists, you no longer need bootstrap-ceo. A board token can mint further board tokens and agent keys non-interactively — see Authentication.

paperclipai heartbeat run

Trigger exactly one heartbeat for a single agent and stream its live logs to your terminal. This is a debugging and observation tool, not the normal way work happens — it POSTs to the server's wakeup endpoint and the server-side runtime runs the adapter. The CLI only triggers and tails; the model executes server-side.

paperclipai heartbeat run --agent-id <agent-id>
paperclipai heartbeat run --agent-id <agent-id> --source on_demand --trigger manual
paperclipai heartbeat run --agent-id <agent-id> --timeout-ms 120000 --debug

The command polls run events and logs until the run reaches a terminal status (succeeded, failed, cancelled, timed_out) and exits non-zero on anything but success, printing error and result details. To inspect runs you triggered elsewhere, use the run subcommands.

Tip: For routine agent wake-ups during normal operation, prefer agent wake and the prompt-handoff flow in prompt. Reach for heartbeat run when you specifically want to watch a single run unfold.

paperclipai routines disable-all

Pause every non-archived routine in one company on the configured local instance. This is an incident/maintenance switch: it stops scheduled automation from firing while you investigate, without deleting anything. It operates directly on the local database (starting the embedded cluster and applying pending migrations if needed), so it works even when the server is down.

paperclipai routines disable-all --company-id <company-id>
paperclipai routines disable-all --company-id <company-id> --json

It reports how many routines it paused, how many were already paused, and how many were archived (left untouched). Routines in any state other than paused/archived are flipped to paused. To create, edit, or resume individual routines through the API, use the routine commands.

Warning: This pauses all of a company's routines at once. Re-enabling is a per-routine operation via routine; there is no single "enable-all" counterpart, so use this deliberately.

Local paths

A local instance keeps its state under ~/.paperclip/instances/<instance-id> (default instance id default):

Use --data-dir (or --instance) to run an isolated instance — handy for clean test setups and worktrees — without disturbing your primary install.

See also

• Installation — install the CLI and pick a deployment shape
• Authentication — board tokens, agent keys, and the login flows after bootstrap
• Runs — inspecting and controlling heartbeat runs (the run subcommands)
• Routines — create, edit, and resume scheduled automation
• Agents — waking agents and agent local-cli for local execution
• Common options — shared flags and context/profile resolution