paperclipai configure

Overview

The configure command allows you to update specific sections of your Paperclip configuration without going through the full onboarding process. It provides interactive prompts for each configuration area.

Syntax

paperclipai configure [options]

Options

`--config <path>`

Path to config file to update. Default: ~/.paperclip/instances/default/config.json

paperclipai configure --config /etc/paperclip/config.json

`--data-dir <path>`

Paperclip data directory root.

paperclipai configure --data-dir /custom/data

`--section <section>`

Specific section to configure. Skip section selection menu. Valid sections:

llm - LLM Provider
database - Database
logging - Logging
server - Server
storage - Storage
secrets - Secrets

paperclipai configure --section llm

Configuration Sections

LLM Provider

Configure AI model provider for agents. Options:

Provider: claude or openai
API Key: Your provider API key
Skip: Remove LLM configuration entirely

Interactive prompts:

◆  Configure LLM provider?
│  ● Yes
│  ○ No (remove existing LLM config)
│
◆  Select LLM provider
│  ● claude
│  ○ openai
│
◆  API key:
│  sk-ant-***

Example:

paperclipai configure --section llm

Resulting config:

{
  "llm": {
    "provider": "claude",
    "apiKey": "sk-ant-***"
  }
}

API keys are stored in the config file. For production, consider using environment variables or secret management.

Database

Configure database connection. Database modes:

Embedded PostgreSQL

Built-in PostgreSQL server (no external database required). Options:

Data directory: Where to store database files
Port: PostgreSQL listen port

Defaults:

Data dir: ~/.paperclip/instances/default/db
Port: 54329

Interactive prompts:

◆  Database mode
│  ● embedded-postgres (Recommended for local development)
│  ○ postgres (External PostgreSQL server)
│
◆  Embedded Postgres data directory:
│  /home/user/.paperclip/instances/default/db
│
◆  Embedded Postgres port:
│  54329

Resulting config:

{
  "database": {
    "mode": "embedded-postgres",
    "embeddedPostgresDataDir": "/home/user/.paperclip/instances/default/db",
    "embeddedPostgresPort": 54329
  }
}

External PostgreSQL

Connect to external PostgreSQL server. Options:

Connection string: Full PostgreSQL connection URL

Format:

postgres://username:password@host:port/database

Interactive prompts:

◆  Database mode
│  ○ embedded-postgres
│  ● postgres
│
◆  PostgreSQL connection string:
│  postgres://paperclip:***@db.example.com:5432/paperclip

Resulting config:

{
  "database": {
    "mode": "postgres",
    "connectionString": "postgres://paperclip:***@db.example.com:5432/paperclip"
  }
}

Example:

paperclipai configure --section database

Changing database mode requires restarting the server and may require data migration.

Logging

Configure where and how logs are written. Logging modes:

File Logging

Write logs to files on disk. Options:

Log directory: Where to store log files

Default: ~/.paperclip/instances/default/logs Interactive prompts:

◆  Logging mode
│  ● file (Write logs to files)
│  ○ console (Output to stdout/stderr)
│
◆  Log directory:
│  /home/user/.paperclip/instances/default/logs

Resulting config:

{
  "logging": {
    "mode": "file",
    "logDir": "/home/user/.paperclip/instances/default/logs"
  }
}

Console Logging

Output logs to stdout/stderr (useful for Docker/systemd). Interactive prompts:

◆  Logging mode
│  ○ file
│  ● console

Resulting config:

{
  "logging": {
    "mode": "console"
  }
}

Example:

paperclipai configure --section logging

Server

Configure server network and authentication settings. Options:

Deployment Mode

local_trusted:

No authentication required
Recommended for local development
All requests trusted

authenticated:

Full authentication required
Recommended for production
Requires user login

Exposure

private:

Only allowed hostnames can connect
Requires allowedHostnames configuration
Most secure

public:

Open access (within deployment mode constraints)
Use with caution

Network Settings

Host:

127.0.0.1 - Localhost only (most secure)
0.0.0.0 - All interfaces (network accessible)
Specific IP - Bind to specific interface

Port:

Default: 3100
Any available port

Additional Settings

Serve UI:

true - Serve web UI from API server
false - API only (UI hosted separately)

Allowed Hostnames:

List of hostnames allowed to connect (for authenticated/private mode)
Example: ["alice-laptop", "bob-desktop"]

Interactive prompts:

◆  Deployment mode
│  ● local_trusted (No authentication, for local development)
│  ○ authenticated (Full authentication required)
│
◆  Exposure
│  ● private (Only allowed hostnames)
│  ○ public (Open access)
│
◆  Host to bind:
│  127.0.0.1
│
◆  Port:
│  3100
│
◆  Serve UI from this server?
│  ● Yes
│  ○ No
│
◆  Add allowed hostnames? (for authenticated/private mode)
│  

Resulting config:

{
  "server": {
    "deploymentMode": "local_trusted",
    "exposure": "private",
    "host": "127.0.0.1",
    "port": 3100,
    "allowedHostnames": [],
    "serveUi": true
  },
  "auth": {
    "baseUrlMode": "auto"
  }
}

Example:

paperclipai configure --section server

Security: Use authenticated mode and private exposure for production deployments.

Storage

Configure file storage backend. Storage providers:

Local Disk

Store files on local filesystem. Options:

Base directory: Where to store files

Default: ~/.paperclip/instances/default/data/storage Interactive prompts:

◆  Storage provider
│  ● local_disk (Store files on local filesystem)
│  ○ s3 (Use S3 or S3-compatible storage)
│
◆  Base directory for local storage:
│  /home/user/.paperclip/instances/default/data/storage

Resulting config:

{
  "storage": {
    "provider": "local_disk",
    "localDisk": {
      "baseDir": "/home/user/.paperclip/instances/default/data/storage"
    }
  }
}

S3 Storage

Use AWS S3 or S3-compatible storage (MinIO, DigitalOcean Spaces, etc.). Options:

Bucket: S3 bucket name
Region: AWS region (e.g., us-east-1)
Endpoint: Custom endpoint for S3-compatible services (optional)
Prefix: Object key prefix (optional)
Force path style: Enable for non-AWS S3 providers

Interactive prompts:

◆  Storage provider
│  ○ local_disk
│  ● s3
│
◆  S3 bucket name:
│  my-paperclip-bucket
│
◆  S3 region:
│  us-east-1
│
◆  S3 endpoint (optional, for S3-compatible providers):
│  https://nyc3.digitaloceanspaces.com
│
◆  S3 object key prefix (optional):
│  paperclip/
│
◆  Force path-style URLs? (required for some S3-compatible providers)
│  ● Yes
│  ○ No

Resulting config:

{
  "storage": {
    "provider": "s3",
    "s3": {
      "bucket": "my-paperclip-bucket",
      "region": "us-east-1",
      "endpoint": "https://nyc3.digitaloceanspaces.com",
      "prefix": "paperclip/",
      "forcePathStyle": true
    }
  }
}

S3 credentials are read from environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) or IAM roles.

Example:

paperclipai configure --section storage

Secrets

Configure secrets management and encryption. Options: Provider: (Currently only local_encrypted supported)

Encrypts secrets with a master key
Stores encrypted values in database

Strict Mode:

true - Require secret references for sensitive environment keys
false - Allow plain text values

Key File Path:

Path to master encryption key
Auto-generated if missing

Default: ~/.paperclip/instances/default/secrets/master.key Interactive prompts:

◆  Secrets strict mode (require secret refs for sensitive env keys)?
│  ○ Yes
│  ● No
│
◆  Secrets key file path:
│  /home/user/.paperclip/instances/default/secrets/master.key

Resulting config:

{
  "secrets": {
    "provider": "local_encrypted",
    "strictMode": false,
    "localEncrypted": {
      "keyFilePath": "/home/user/.paperclip/instances/default/secrets/master.key"
    }
  }
}

Key file creation: If the key file doesn’t exist:

✔  Created local secrets key file at /home/user/.paperclip/instances/default/secrets/master.key

Example:

paperclipai configure --section secrets

Backup your master key! Without it, encrypted secrets cannot be decrypted.

Interactive Workflow

Without `--section`

Shows section selection menu:

┌  paperclip configure
│
◆  Which section do you want to configure?
│  ○ LLM Provider
│  ○ Database
│  ○ Logging
│  ● Server
│  ○ Storage
│  ○ Secrets
│

After configuring:

✔  Server configuration updated.
│
◆  Configure another section?
│  ● Yes
│  ○ No
│
└  Configuration saved.

With `--section`

Directly configures specified section:

paperclipai configure --section llm

┌  paperclip configure
│
▲  LLM Provider
│
◆  Configure LLM provider?
  ...
│
✔  LLM Provider configuration updated.
│
└  Configuration saved.

No “configure another section” prompt - exits after updating.

Examples

Update LLM provider

paperclipai configure --section llm

Switch to external database

paperclipai configure --section database
# Select: postgres
# Enter connection string

Change server port

paperclipai configure --section server
# Update port to 8080

Switch to S3 storage

paperclipai configure --section storage
# Select: s3
# Enter bucket, region, etc.

Enable strict secrets mode

paperclipai configure --section secrets
# Enable strict mode

Interactive multi-section update

paperclipai configure
# Select sections one by one
# Configure multiple sections in one session

Custom config location

paperclipai configure --config /etc/paperclip/prod.json --section database

Configuration Updates

Each update:

Reads existing config
Shows current values (where applicable)
Prompts for new values
Writes updated config
Updates $meta.updatedAt and $meta.source

Metadata:

{
  "$meta": {
    "version": 1,
    "updatedAt": "2026-03-04T23:15:30.000Z",
    "source": "configure"
  }
}

Validations

Config File Must Exist

If no config found:

✖  No config file found. Run `paperclipai onboard` first.

Solution:

paperclipai onboard
paperclipai configure

Invalid Section Name

If using unknown section:

paperclipai configure --section invalid

✖  Unknown section: invalid. Choose from: llm, database, logging, server, storage, secrets

Invalid Config File

If existing config is corrupted:

⚠  Existing config is invalid. Loading defaults so you can repair it now.
   <error details>

You can proceed to fix the configuration.

After Configuration

Verify Changes

Check updated config:

cat ~/.paperclip/instances/default/config.json

Or view environment:

paperclipai env

Test Configuration

Run health checks:

paperclipai doctor --repair

Restart Server

Configuration changes require restart:

# Stop current server (Ctrl+C)
# Restart with new config
paperclipai run

Most configuration changes require a server restart to take effect.

Troubleshooting

Permission denied writing config

Check file permissions:

ls -la ~/.paperclip/instances/default/config.json

Fix ownership:

sudo chown $USER:$USER ~/.paperclip/instances/default/config.json

Changes not taking effect

Ensure server is restarted:

# Stop server
pkill -f paperclipai

# Restart
paperclipai run

Lost configuration

Config files are not backed up automatically. To restore:

# Re-run onboard
paperclipai onboard

# Or manually recreate
paperclipai configure

Invalid database connection

Test connection separately:

# For postgres mode
psql "postgres://user:pass@host:5432/db"

# Update if needed
paperclipai configure --section database

Best Practices

Backup Before Changes

cp ~/.paperclip/instances/default/config.json ~/.paperclip/instances/default/config.json.backup
paperclipai configure --section database

Use Version Control

For production configs:

cd /etc/paperclip
git init
git add config.json
git commit -m "Initial config"

# After changes
paperclipai configure --config /etc/paperclip/config.json
git diff config.json
git commit -am "Update database config"

Test in Staging First

# Staging
paperclipai configure --config staging.json --section database
paperclipai doctor --config staging.json
paperclipai run --config staging.json

# If successful, apply to production
cp staging.json production.json

Document Changes

Keep a changelog:

echo "$(date): Changed database to external postgres" >> /etc/paperclip/CHANGELOG

Next Steps

Verify configuration

Run health checks after configuration changes

Restart server

Apply configuration changes

Environment variables

See CLI environment variables

Commands

​Overview

​Syntax

​Options

​--config <path>

​--data-dir <path>

​--section <section>

​Configuration Sections

​LLM Provider

​Database

​Embedded PostgreSQL

​External PostgreSQL

​Logging

​File Logging

​Console Logging

​Server

​Deployment Mode

​Exposure

​Network Settings

​Additional Settings

​Storage

​Local Disk

​S3 Storage

​Secrets

​Interactive Workflow

​Without --section

​With --section

​Examples

​Update LLM provider

​Switch to external database

​Change server port

​Switch to S3 storage

​Enable strict secrets mode

​Interactive multi-section update

​Custom config location

​Configuration Updates

​Validations

​Config File Must Exist

​Invalid Section Name

​Invalid Config File

​After Configuration

​Verify Changes

​Test Configuration

​Restart Server

​Troubleshooting

​Permission denied writing config

​Changes not taking effect

​Lost configuration

​Invalid database connection

​Best Practices

​Backup Before Changes

​Use Version Control

​Test in Staging First

​Document Changes

​Next Steps

Verify configuration

Restart server

Environment variables

Overview

Syntax

Options

`--config <path>`

`--data-dir <path>`

`--section <section>`

Configuration Sections

LLM Provider

Database

Embedded PostgreSQL

External PostgreSQL

Logging

File Logging

Console Logging

Server

Deployment Mode

Exposure

Network Settings

Additional Settings

Storage

Local Disk

S3 Storage

Secrets

Interactive Workflow

Without `--section`

With `--section`

Examples

Update LLM provider

Switch to external database

Change server port

Switch to S3 storage

Enable strict secrets mode

Interactive multi-section update

Custom config location

Configuration Updates

Validations

Config File Must Exist

Invalid Section Name

Invalid Config File

After Configuration

Verify Changes

Test Configuration

Restart Server

Troubleshooting

Permission denied writing config

Changes not taking effect

Lost configuration

Invalid database connection

Best Practices

Backup Before Changes

Use Version Control

Test in Staging First

Document Changes

Next Steps