paperclipai/paperclip-docs
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-09 17:41:56 -10:00
Code Issues Packages Projects Releases Wiki Activity
Files
codex/https-setup-guide
paperclip-docs/docs/reference/cli/test-drive.md
T
Aron PrinsClaude Opus 4.8DevRel GeminiPaperclipDottaClaudeCoder
 c65bc9a9bf Release docs for paperclip v2026.916.0 (#125) 
Brings **paperclip-docs** in line with paperclip **v2026.916.0**,
shipping the `v2026.831.1 → v2026.916.0` cycle drafted on `nightly`,
stamped to the release tag, with a documentation changelog entry.

This branch was cut from `nightly` **after** merging `origin/main` into
it, so it sits on top of the operator-first connectors catalog (#124)
rather than reverting it.

## Manifest

**New pages (4)**
- `docs/reference/api/connection-intents.md` — Connection Intents API
- `docs/reference/cli/connections.md` — `connections` command
- `docs/reference/cli/managed-agent.md` — `managed-agent` command
- `docs/reference/cli/test-drive.md` — `test-drive` command

**Updated pages (17)**
- Roles & Permissions + Company Administration — `tools:*` role-default
changes
- Connect an Agent to GitHub — managed GitHub connection (Connectors),
Option C
- Agents API — Managed/Remote Agent Profiles, `***REDACTED***` env
serialization
- Tool Gateway API — agent self-authorization (`start-authorization`,
`token`)
- Instance Admin API — instance-settings + task-drain routes
- Plugin SDK — `ctx.access` + `ctx.authorization` clients,
login-PTY/duplex streaming
- Environment Variables — Paperclip ID Connector block + HTTP adapter
allowlist var
- Adapters: Codex (`gpt-5.6-sol` default, Fast mode, auth cache), Claude
Code (Fable 5.1 + CLI floor), Grok Local (SuperGrok subscription auth),
HTTP (SSRF guard), Sandbox Providers (Daytona warm runner), OpenCode
(model pre-flight)
- CLI: `adapter detect-model`, `onboard` tool-action signing secret
- Command palette — recent tasks in sidebar
- `docs/reference/changelog.md` — new `v2026.916.0` accordion entry

All 21 touched pages stamped `paperclip_version: v2026.916.0`.

## Verification

**Tag-accuracy gate (Phase 5.7)** — `check-tag-accuracy.mjs --tag
v2026.916.0 --base main --head nightly` flagged 5 pages, **every one
verified present in the code at the release tag** and cleared as known
`verify-edit` false-positive classes. No content was quarantined; **no
post-tag leaks**:

| Page | Flagged claim(s) | Verified at tag |
|---|---|---|
| `cli/connections.md` | `PAPERCLIP_RUNTIME_TOOLS_*` (3) | present in
`cli/src/commands/client/connections.ts` (runtime-injected env) |
| `cli/managed-agent.md` | `--profile-key`, `--api-key-secret-id` |
present in `cli/src/commands/managed-agent.ts`
(`.requiredOption`/`.option`) |
| `cli/test-drive.md` | `--harness` | present in
`cli/src/commands/test-drive.ts` (`new Option`) |
| `deploy/environment-variables.md` | `PAPERCLIP_ID_CONNECTOR_*` (5) |
present in `.env.example` at tag |
| `plugins/sdk.md` | `PLUGIN_*` (6) | present in
`packages/plugins/sdk/src/index.ts` (exported constants) |

Rationale: nightly's drafts were authored from parent `af8439a`, **226
commits inside the tag**, so they document in-tag surfaces by
construction.

### ⚠ Drift
`check-drift.mjs --against v2026.916.0` returned 14 records — **all
verified present at the tag** (checker false positives), listed here for
the reviewer to confirm:

- **env-var (9, high-confidence in the tool, verified present):**
`PAPERCLIP_WORKSPACE_GIT_SCAN_{CONCURRENCY,QUEUE_CAPACITY,TIMEOUT_MS,CACHE_TTL_MS}`
and
`PAPERCLIP_ID_CONNECTOR_{BASE_URL,ENVIRONMENT,INSTANCE_ID,SIGN_PRIVATE_KEY,SEAL_PRIVATE_KEY}`
— all present in `.env.example` at the tag; the drift scanner's scoped
file scan missed them.
- **Verify: rest-route (5, medium-confidence):** `POST/PUT/GET
/api/companies/import/transfers*` — present at the tag in
`server/src/routes/companies.ts`, registered via the
`COMPANY_IMPORT_TRANSFERS_ROUTE_PATH` prefix constant (the documented
prefix/dynamic-registration blind spot).

### ⚠ Verification Failures
None. All tag-accuracy and drift flags above were verified present at
the tag.

### ↻ Renames detected
None. The connectors catalog (`docs/connectors/**`) arrived via the
`main` merge (#124), not as a renamed surface; no new top-level draft
directories were introduced this cycle.

## Screenshots
**238 of 342 screenshots** flagged stale across 50 routes (see
`SCREENSHOTS_PENDING.md`). This is a wide 16-day window touching ~921 UI
files, so most are dependency-touch flags rather than confirmed visual
changes. Recommend `npm run screenshots:refresh` on this release branch
as a dedicated follow-up before merge; PNGs go to a separate PR for
human review.

## Build gates (all green on this branch)
- `npm run docs:build` — 257 pages
- `npm run docs:test` — SEO metadata, crawlable-links (71,749 links
resolve), doc-link-resolution, skill-source-blocks, static-routes,
hierarchical-nav

## Post-merge checklist (Phase 9 — do NOT skip)
- [ ] Squash-merge this PR (repo is squash-only)
- [ ] `git checkout main && git pull`
- [ ] `git tag docs/v2026.916.0 && git push --tags`
- [ ] `node scripts/sync/realign-nightly.mjs release/v2026.916.0 --push`
(restore ancestry; keep nightly post-tag drafts)
- [ ] Flip `nightly` `.sync-state.json` back to `"branch_mode":
"nightly"` (leave `base_release_tag` at `v2026.916.0`)
- [ ] Verify `docs.paperclip.ing` serves the release: a new page
(`/reference/cli/test-drive/`), a changed page, and the changelog top
entry reads `Docs for v2026.916.0`
- [ ] If production is stale, republish: `npm run docs:build && npx
wrangler pages deploy .site --project-name paperclip-docs --branch main`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Co-authored-by: Dotta <[email protected]>
Co-authored-by: ClaudeCoder <[email protected]>
2026-09-17 11:15:48 +02:00

102 lines
6.2 KiB
Markdown
Raw Permalink Blame History

---
paperclip_version: v2026.916.0
seo_title: The test-drive Command
seo_description: Spin up an isolated, self-initialized Paperclip instance with a ready-made company and CEO agent so you can try the product locally.
---
# 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.
```sh
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`](./run.md) or the [setup commands](./setup-commands.md).
---
## What it does, step by step
When you run `test-drive`, it:
1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **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.
```sh
# 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.
```sh
# 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.
---
## See also
- [Run Command](./run.md) — start a local instance without the throwaway bootstrap.
- [Setup Commands](./setup-commands.md) — the durable first-run setup path.
- [Adapter Commands](./adapter.md) — the `claude_local`, `codex_local`, and `opencode_local` adapters behind each harness.
- [Common Options](./common-options.md) — shared client flags and resolution order.
Reference in new issue View Git Blame Copy Permalink