Skip to content

The open-source app everyone uses to manage agents at work

Make onboarding reruns preserve existing config

dotta54b05d6d68f1
diff --git a/README.md b/README.md
index f7ade1b389..42f24cd1a8 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,8 @@ Open source. Self-hosted. No Paperclip account required.
npx paperclipai onboard --yes
```
+If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.
+
Or manually:
```bash
diff --git a/cli/README.md b/cli/README.md
index c5a6ce1343..08f36ad49b 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -177,6 +177,8 @@ Open source. Self-hosted. No Paperclip account required.
npx paperclipai onboard --yes
```
+If you already have Paperclip configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to edit settings.
+
Or manually:
```bash
diff --git a/cli/src/__tests__/onboard.test.ts b/cli/src/__tests__/onboard.test.ts
new file mode 100644
index 0000000000..a5ffe44ad4
--- /dev/null
+++ b/cli/src/__tests__/onboard.test.ts
@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { onboard } from "../commands/onboard.js";
+import type { PaperclipConfig } from "../config/schema.js";
+
+const ORIGINAL_ENV = { ...process.env };
+
+function createExistingConfigFixture() {
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-"));
+ const runtimeRoot = path.join(root, "runtime");
+ const configPath = path.join(root, ".paperclip", "config.json");
+ const config: PaperclipConfig = {
+ $meta: {
+ version: 1,
+ updatedAt: "2026-03-29T00:00:00.000Z",
+ source: "configure",
+ },
+ database: {
+ mode: "embedded-postgres",
+ embeddedPostgresDataDir: path.join(runtimeRoot, "db"),
+ embeddedPostgresPort: 54329,
+ backup: {
+ enabled: true,
+ intervalMinutes: 60,
+ retentionDays: 30,
+ dir: path.join(runtimeRoot, "backups"),
+ },
+ },
+ logging: {
+ mode: "file",
+ logDir: path.join(runtimeRoot, "logs"),
+ },
+ server: {
+ deploymentMode: "local_trusted",
+ exposure: "private",
+ host: "127.0.0.1",
+ port: 3100,
+ allowedHostnames: [],
+ serveUi: true,
+ },
+ auth: {
+ baseUrlMode: "auto",
+ disableSignUp: false,
+ },
+ storage: {
+ provider: "local_disk",
+ localDisk: {
+ baseDir: path.join(runtimeRoot, "storage"),
+ },
+ s3: {
+ bucket: "paperclip",
+ region: "us-east-1",
+ prefix: "",
+ forcePathStyle: false,
+ },
+ },
+ secrets: {
+ provider: "local_encrypted",
+ strictMode: false,
+ localEncrypted: {
+ keyFilePath: path.join(runtimeRoot, "secrets", "master.key"),
+ },
+ },
+ };
+
+ fs.mkdirSync(path.dirname(configPath), { recursive: true });
+ fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+
+ return { configPath, configText: fs.readFileSync(configPath, "utf8") };
+}
+
+describe("onboard", () => {
+ beforeEach(() => {
+ process.env = { ...ORIGINAL_ENV };
+ delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
+ delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
+ delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
+ });
+
+ afterEach(() => {
+ process.env = { ...ORIGINAL_ENV };
+ });
+
+ it("preserves an existing config when rerun without flags", async () => {
+ const fixture = createExistingConfigFixture();
+
+ await onboard({ config: fixture.configPath });
+
+ expect(fs.readFileSync(fixture.configPath, "utf8")).toBe(fixture.configText);
+ expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);
+ expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
+ });
+
+ it("preserves an existing config when rerun with --yes", async () => {
+ const fixture = createExistingConfigFixture();
+
+ await onboard({ config: fixture.configPath, yes: true, invokedByRun: true });
+
+ expect(fs.readFileSync(fixture.configPath, "utf8")).toBe(fixture.configText);
+ expect(fs.existsSync(`${fixture.configPath}.backup`)).toBe(false);
+ expect(fs.existsSync(path.join(path.dirname(fixture.configPath), ".env"))).toBe(true);
+ });
+});
diff --git a/cli/src/commands/onboard.ts b/cli/src/commands/onboard.ts
index 523484f3c6..d470354f8d 100644
--- a/cli/src/commands/onboard.ts
+++ b/cli/src/commands/onboard.ts
@@ -244,11 +244,12 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
),
);
+ let existingConfig: PaperclipConfig | null = null;
if (configExists(opts.config)) {
- p.log.message(pc.dim(`${configPath} exists, updating config`));
+ p.log.message(pc.dim(`${configPath} exists`));
try {
- readConfig(opts.config);
+ existingConfig = readConfig(opts.config);
} catch (err) {
p.log.message(
pc.yellow(
@@ -258,6 +259,76 @@ export async function onboard(opts: OnboardOptions): Promise<void> {
}
}
+ if (existingConfig) {
+ p.log.message(
+ pc.dim("Existing Paperclip install detected; keeping the current configuration unchanged."),
+ );
+ p.log.message(pc.dim(`Use ${pc.cyan("paperclipai configure")} if you want to change settings.`));
+
+ const jwtSecret = ensureAgentJwtSecret(configPath);
+ const envFilePath = resolveAgentJwtEnvFile(configPath);
+ if (jwtSecret.created) {
+ p.log.success(`Created ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} in ${pc.dim(envFilePath)}`);
+ } else if (process.env.PAPERCLIP_AGENT_JWT_SECRET?.trim()) {
+ p.log.info(`Using existing ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} from environment`);
+ } else {
+ p.log.info(`Using existing ${pc.cyan("PAPERCLIP_AGENT_JWT_SECRET")} in ${pc.dim(envFilePath)}`);
+ }
+
+ const keyResult = ensureLocalSecretsKeyFile(existingConfig, configPath);
+ if (keyResult.status === "created") {
+ p.log.success(`Created local secrets key file at ${pc.dim(keyResult.path)}`);
+ } else if (keyResult.status === "existing") {
+ p.log.message(pc.dim(`Using existing local secrets key file at ${keyResult.path}`));
+ }
+
+ p.note(
+ [
+ "Existing config preserved",
+ `Database: ${existingConfig.database.mode}`,
+ existingConfig.llm ? `LLM: ${existingConfig.llm.provider}` : "LLM: not configured",
+ `Logging: ${existingConfig.logging.mode} -> ${existingConfig.logging.logDir}`,
+ `Server: ${existingConfig.server.deploymentMode}/${existingConfig.server.exposure} @ ${existingConfig.server.host}:${existingConfig.server.port}`,
+ `Allowed hosts: ${existingConfig.server.allowedHostnames.length > 0 ? existingConfig.server.allowedHostnames.join(", ") : "(loopback only)"}`,
+ `Auth URL mode: ${existingConfig.auth.baseUrlMode}${existingConfig.auth.publicBaseUrl ? ` (${existingConfig.auth.publicBaseUrl})` : ""}`,
+ `Storage: ${existingConfig.storage.provider}`,
+ `Secrets: ${existingConfig.secrets.provider} (strict mode ${existingConfig.secrets.strictMode ? "on" : "off"})`,
+ "Agent auth: PAPERCLIP_AGENT_JWT_SECRET configured",
+ ].join("\n"),
+ "Configuration ready",
+ );
+
+ p.note(
+ [
+ `Run: ${pc.cyan("paperclipai run")}`,
+ `Reconfigure later: ${pc.cyan("paperclipai configure")}`,
+ `Diagnose setup: ${pc.cyan("paperclipai doctor")}`,
+ ].join("\n"),
+ "Next commands",
+ );
+
+ let shouldRunNow = opts.run === true || opts.yes === true;
+ if (!shouldRunNow && !opts.invokedByRun && process.stdin.isTTY && process.stdout.isTTY) {
+ const answer = await p.confirm({
+ message: "Start Paperclip now?",
+ initialValue: true,
+ });
+ if (!p.isCancel(answer)) {
+ shouldRunNow = answer;
+ }
+ }
+
+ if (shouldRunNow && !opts.invokedByRun) {
+ process.env.PAPERCLIP_OPEN_ON_LISTEN = "true";
+ const { runCommand } = await import("./run.js");
+ await runCommand({ config: configPath, repair: true, yes: true });
+ return;
+ }
+
+ p.outro("Existing Paperclip setup is ready.");
+ return;
+ }
+
let setupMode: SetupMode = "quickstart";
if (opts.yes) {
p.log.message(pc.dim("`--yes` enabled: using Quickstart defaults."));
diff --git a/docs/cli/setup-commands.md b/docs/cli/setup-commands.md
index 7dc5cd6ad0..448ab7bbc4 100644
--- a/docs/cli/setup-commands.md
+++ b/docs/cli/setup-commands.md
@@ -33,6 +33,8 @@ Interactive first-time setup:
pnpm paperclipai onboard
```
+If Paperclip is already configured, rerunning `onboard` keeps the existing config in place. Use `paperclipai configure` to change settings on an existing install.
+
First prompt:
1. `Quickstart` (recommended): local defaults (embedded database, no LLM provider, local disk storage, default secrets)
@@ -50,6 +52,8 @@ Non-interactive defaults + immediate start (opens browser on server listen):
pnpm paperclipai onboard --yes
```
+On an existing install, `--yes` now preserves the current config and just starts Paperclip with that setup.
+
## `paperclipai doctor`
Health checks with optional auto-repair:
diff --git a/docs/start/quickstart.md b/docs/start/quickstart.md
index 1ad30fcdfa..2abe538b0e 100644
--- a/docs/start/quickstart.md
+++ b/docs/start/quickstart.md
@@ -13,6 +13,8 @@ npx paperclipai onboard --yes
This walks you through setup, configures your environment, and gets Paperclip running.
+If you already have a Paperclip install, rerunning `onboard` keeps your current config and data paths intact. Use `paperclipai configure` if you want to edit settings.
+
To start Paperclip again later:
```sh