paperclip_cli

paperclip_cli is a small Bash wrapper repo for running a self-contained local Paperclip instance.

It is not the upstream Paperclip project. It is an operator-friendly wrapper around upstream paperclipai/paperclip that:

• bootstraps a local Paperclip checkout into vendor/paperclip
• manages a repo-local runtime under .paperclip-runtime/
• starts and stops Paperclip as a background launchd service on macOS
• exposes the instance through Tailscale Serve when available
• falls back to local-only mode when Tailscale is not installed
• adds a few direct agent-control commands for listing agents and updating heartbeat / reasoning settings against the managed embedded Postgres instance

Quick Start

Prerequisites:

• macOS
• git
• node 20+
• pnpm 9.x
• python3
• curl
• lsof
• optional: tailscale
• optional for agent ... commands: psql

Clone the repo and run:

git clone git@github.com:funcountry/paperclip_cli.git
cd paperclip_cli
chmod +x paperclip
./paperclip doctor
./paperclip start
./paperclip status

If you do not want Tailscale exposure, force local-only mode:

PAPERCLIP_ENABLE_TAILSCALE=never ./paperclip start

The bootstrap invite for the first CEO login is written to:

.paperclip-runtime/bootstrap-invite.txt

What Gets Created

This repo stays small. The first start clones upstream Paperclip into:

vendor/paperclip

Runtime state stays local to this repo:

.paperclip-runtime/
  paperclip.env
  logs/
  home/
  bootstrap-invite.txt

Nothing under .paperclip-runtime/ or vendor/ is committed by default.

Commands

./paperclip start
./paperclip stop
./paperclip status
./paperclip doctor
./paperclip agent list [--tree]
./paperclip agent heartbeat set <agent-name-or-id> <seconds|Ns|Nm|Nh> [--self|--self-and-reports] [--dry-run]
./paperclip agent thinking set <agent-name-or-id> <minimal|low|medium|high|xhigh> [--self|--self-and-reports] [--dry-run]

Examples:

./paperclip doctor
./paperclip start
./paperclip agent list --tree
./paperclip agent heartbeat set CEO 10m --self
./paperclip agent thinking set CEO xhigh --dry-run

Configuration

The wrapper is driven by environment variables. The most useful ones are:

• PAPERCLIP_ENABLE_TAILSCALE=auto|always|never
• PAPERCLIP_PUBLIC_URL=https://example.com:8443
• PAPERCLIP_PUBLIC_HOST=<hostname>
• PAPERCLIP_PUBLIC_PORT=8443
• PAPERCLIP_DB_PORT=54329
• PAPERCLIP_APP_DIR=/path/to/paperclip
• PAPERCLIP_UPSTREAM_REPO=https://github.com/paperclipai/paperclip.git
• PAPERCLIP_RUNTIME_DIR=/path/to/runtime
• HOST=127.0.0.1
• PORT=3100

Default networking behavior:

• auto: use Tailscale if it is installed and the machine has a tailnet identity; otherwise run local-only on http://127.0.0.1:<PORT>
• always: require Tailscale and expose through https://<tailnet-host>:8443
• never: do not configure Tailscale; keep the instance local

Default database behavior:

• the embedded Postgres port defaults to 54329 + (PORT - 3100)
• if you run multiple local wrappers, giving each instance a different PORT automatically gives it a different embedded DB port too
• you can still override it directly with PAPERCLIP_DB_PORT
• if Paperclip still has to bump to the next free DB port at runtime, the wrapper follows the live port from Postgres runtime state for agent ... commands

Notes

• The wrapper currently supports macOS only because it manages the server with launchd.
• The agent ... commands are intentionally narrow. They assume the managed instance is using the embedded Postgres mode generated by this wrapper.
• Upstream Paperclip still owns the actual server, UI, schema, and official CLI. This repo is just a thin operator shell around it.

License

MIT