Test Drive Command

test-drive is the fastest way to see Paperclip working on your own machine. One command starts a fresh local instance, creates a company and a CEO agent for you, seeds the provider credential that agent needs, and opens the dashboard in your browser. It is built for kicking the tyres — a manual, throwaway environment you can create, poke at, and walk away from.

paperclipai test-drive

The command runs a local Paperclip instance the same way run does, then bootstraps starter content on top of it. Nothing here talks to a remote control plane you already operate; it stands up its own.

Note: Use test-drive for evaluation and demos, not for a company you intend to keep. It runs in local_trusted mode, bound to loopback, in a data directory it treats as disposable. For a durable local setup, reach for run or the setup commands.

What it does, step by step

When you run test-drive, it:

Isolates the environment first. Before the CLI's normal config and .env loading happens, test-drive clears every PAPERCLIP_* variable (and a handful of others like DATABASE_URL, HOST, and PORT) from the process so a stray shell export cannot point it at some other instance. The one thing it preserves is the environment variable you named with --api-key-env, if you used it.
Redacts your API key. If you pass --api-key, the value is scrubbed from the process argument list immediately, so it does not leak into logs, telemetry, diagnostics, or crash output.
Asserts database isolation. It refuses to run against a data directory wired to an external PostgreSQL database (DATABASE_URL, DATABASE_MIGRATION_URL, or a config database.mode of postgres), so the test drive always uses its own embedded database.
Starts the instance. It boots a local server on a free loopback port (starting at 3100), repairing the data directory and accepting defaults without prompting.
Bootstraps a company and agent. If the data directory is empty, it creates a company, defines and stores the provider secret, and creates a CEO agent wired to the matching adapter. If a company already exists there, it reuses it and tells you the bootstrap flags were ignored.
Opens the dashboard. It prints the URL and opens it in your browser (unless you pass --no-browser).

Note: The data directory is retained when Paperclip exits. If you did not pass --data-dir, test-drive creates a fresh temporary directory for you and prints its path — clean it up yourself when you are done.

Choosing a harness and model

The --harness flag decides which adapter your CEO agent is created against, and therefore which provider credential it expects:

Harness	Adapter	Credential it looks for
`claude` (default)	`claude_local`	`ANTHROPIC_API_KEY`
`codex`	`codex_local`	`OPENAI_API_KEY`
`opencode`	`opencode_local`	`OPENROUTER_API_KEY`

--model sets the agent's initial model and is optional for claude and codex. For opencode it is required and must be an openrouter/<model> identifier (for example openrouter/anthropic/claude-sonnet-4), with no empty path segments.

# Try it with Codex instead of Claude
paperclipai test-drive --harness codex

# OpenCode requires an openrouter/<model> id
paperclipai test-drive --harness opencode --model openrouter/anthropic/claude-sonnet-4

Supplying the credential

The agent needs a provider key. You have three ways to give test-drive one, in priority order:

--api-key <value> — pass the key directly. Convenient, but the value can briefly appear in your shell history and process arguments, so test-drive warns you and redacts it from its own argv.
--api-key-env <variable> — name an environment variable the key already lives in. This is preserved through the isolation step above.
Nothing — test-drive falls back to the harness's default variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY).

--api-key and --api-key-env are mutually exclusive. If no credential can be found, the command stops before creating anything and tells you exactly which variable to set.

# Key already exported in your shell
export ANTHROPIC_API_KEY=sk-ant-...
paperclipai test-drive

# Key in a differently named variable
paperclipai test-drive --api-key-env MY_TEAM_ANTHROPIC_KEY

Options

Flag	Default	Use
`-d, --data-dir <path>`	a fresh temp directory	Paperclip data directory to create or reuse. Omit it to get an isolated throwaway directory.
`--company-name <name>`	`Test Company`	Name for the company that gets created.
`--agent-name <name>`	`CEO`	Name for the CEO agent that gets created.
`--harness <harness>`	`claude`	Initial agent harness: `claude`, `codex`, or `opencode`.
`--model <model-id>`	(adapter default)	Initial agent model. Required for `opencode` as `openrouter/<model>`.
`--api-key-env <variable>`	(harness default var)	Read the provider key from this environment variable. Conflicts with `--api-key`.
`--api-key <value>`	(unset)	Provider API key passed directly. Conflicts with `--api-key-env`.
`--no-browser`	browser opens	Do not open the initialized instance in a browser; just print the URL.

Tip: The bootstrap flags — --company-name, --agent-name, --harness, --model, and the credential flags — only take effect when the data directory is empty. Point --data-dir at an existing test-drive directory and it reuses what is already there.