paperclipai/paperclip-docs
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-07 06:16:07 -10:00
Code Issues Packages Projects Releases Wiki Activity

Release docs for paperclip v2026.609.0

Browse Source 
Publish accumulated nightly drafts to main and document the new surfaces
shipped between v2026.529.0 and v2026.609.0 (130 parent commits).

New pages (gaps not covered by nightly drafts):
- docs/reference/cli/token.md — `token agent` / `token board` API-key commands
- docs/reference/cli/connect.md — interactive `connect` setup wizard
- docs/reference/api/teams-catalog.md — teams catalog REST API

Also:
- Stamp paperclip_version: v2026.609.0 on 49 release doc pages
- Register the 3 new pages in site/content.json nav
- Bump .sync-state.json base_release_tag to v2026.609.0

Verification: 49 pages checked against v2026.609.0; 11 verifier flags,
all confirmed false-positives (flagged flags/env-vars exist in parent).
Drift: 0. Reconciliation: 0.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
Aron PrinsandClaude Opus 4.8 committed 2026-06-10 12:08:31 +02:00
1 parent 0d50f1424e
commit b243dfe70d
52 files changed
+613 -64
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.sync-state.json
+6 -6
View File
@@ -1,9 +1,9 @@
{
"branch_mode": "nightly",
"base_release_tag": "v2026.529.0",
"base_release_sha": "911a1e8b0d24205acd5006e837a5c5e8c4bfb447",
"last_seen_parent_sha": "0a2230b2ec509fe514a45298ed75d3987cf69f5c",
"last_applied_manifest_hash": "49b43b0e34aa30e255dac12cd9a3ba12b747e0951ddb8a2787b7090d4a2bb608",
"last_run_at": "2026-06-09T09:55:00Z",
"branch_mode": "release",
"base_release_tag": "v2026.609.0",
"base_release_sha": "a0f7d3dabaf5308ade45cae0c64ebd133948dca2",
"last_seen_parent_sha": "a0f7d3dabaf5308ade45cae0c64ebd133948dca2",
"last_applied_manifest_hash": "313c4fc9a3db09ded3cdfb9ec191d0d4e3e8f7e1e8b5d68ae39b96cc492ac25d",
"last_run_at": "2026-06-10T10:08:07Z",
"last_run_outcome": "applied"
}
SCREENSHOTS_PENDING.md
+33 -25
View File
@@ -1,29 +1,37 @@
# Screenshots — pending recapture
# Screenshots pending refresh
> Regenerated by `/sync-docs` each nightly run. Lists screenshots whose `depends_on` parent paths changed in the current settled diff window.
Window: v2026.529.0 → v2026.609.0 (parent a0f7d3d)
- **Window:** `v2026.529.0` → parent `master` HEAD `0a2230b` (effective HEAD `76c88e5` after 24h quarantine)
- **Stale entries:** 18
**182 of 276** registry screenshots are stale (their `depends_on` UI source changed).
The settings screenshots are stale because instance settings moved under company settings (paperclip #7680) and the adapter manager gained override controls (paperclip #7394). Recapture with `npm run screenshots:refresh` (PNGs land in a PR for human review — never auto-pushed).
Refresh with `npm run screenshots:refresh` (captures stale entries into a review PR — never auto-pushed).
| Screenshot | Route | Changed dependency |
|---|---|---|
| `dark/adapters/detail.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `dark/adapters/health.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `dark/adapters/install.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `dark/adapters/list.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `dark/settings/experimental.png` | `/instance/settings/experimental` | `ui/src/pages/InstanceExperimentalSettings.tsx` |
| `dark/settings/instance-access.png` | `/instance/settings/access` | `ui/src/pages/InstanceAccess.tsx` |
| `dark/settings/instance-adapters.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `dark/settings/instance-general.png` | `/instance/settings/general` | `ui/src/pages/InstanceGeneralSettings.tsx` |
| `dark/settings/scheduler-heartbeats.png` | `/instance/settings/heartbeats` | `ui/src/pages/InstanceSettings.tsx` |
| `light/adapters/detail.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `light/adapters/health.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `light/adapters/install.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `light/adapters/list.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `light/settings/experimental.png` | `/instance/settings/experimental` | `ui/src/pages/InstanceExperimentalSettings.tsx` |
| `light/settings/instance-access.png` | `/instance/settings/access` | `ui/src/pages/InstanceAccess.tsx` |
| `light/settings/instance-adapters.png` | `/instance/settings/adapters` | `ui/src/pages/AdapterManager.tsx` |
| `light/settings/instance-general.png` | `/instance/settings/general` | `ui/src/pages/InstanceGeneralSettings.tsx` |
| `light/settings/scheduler-heartbeats.png` | `/instance/settings/heartbeats` | `ui/src/pages/InstanceSettings.tsx` |
## Stale by changed UI source
- `ui/src/components/AgentConfigForm.tsx` → 20 screenshot(s)
- `ui/src/components/OnboardingWizard.tsx` → 4 screenshot(s)
- `ui/src/components/SidebarCompanyMenu.tsx` → 4 screenshot(s)
- `ui/src/pages/AdapterManager.tsx` → 10 screenshot(s)
- `ui/src/pages/AgentDetail.tsx` → 24 screenshot(s)
- `ui/src/pages/Agents.tsx` → 6 screenshot(s)
- `ui/src/pages/ApprovalDetail.tsx` → 12 screenshot(s)
- `ui/src/pages/CompanyAccess.tsx` → 2 screenshot(s)
- `ui/src/pages/CompanyExport.tsx` → 2 screenshot(s)
- `ui/src/pages/Costs.tsx` → 16 screenshot(s)
- `ui/src/pages/Dashboard.tsx` → 10 screenshot(s)
- `ui/src/pages/ExecutionWorkspaceDetail.tsx` → 6 screenshot(s)
- `ui/src/pages/Inbox.tsx` → 14 screenshot(s)
- `ui/src/pages/InstanceAccess.tsx` → 2 screenshot(s)
- `ui/src/pages/InstanceExperimentalSettings.tsx` → 2 screenshot(s)
- `ui/src/pages/InstanceGeneralSettings.tsx` → 2 screenshot(s)
- `ui/src/pages/InstanceSettings.tsx` → 2 screenshot(s)
- `ui/src/pages/IssueDetail.tsx` → 10 screenshot(s)
- `ui/src/pages/NewAgent.tsx` → 4 screenshot(s)
- `ui/src/pages/PluginManager.tsx` → 4 screenshot(s)
- `ui/src/pages/PluginPage.tsx` → 2 screenshot(s)
- `ui/src/pages/PluginSettings.tsx` → 4 screenshot(s)
- `ui/src/pages/ProfileSettings.tsx` → 2 screenshot(s)
- `ui/src/pages/ProjectDetail.tsx` → 10 screenshot(s)
- `ui/src/pages/Projects.tsx` → 2 screenshot(s)
- `ui/src/pages/RoutineDetail.tsx` → 6 screenshot(s)
- `ui/src/pages/Routines.tsx` → 2 screenshot(s)
docs/administration/company.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Company Administration
Every Paperclip company has a small cluster of surfaces that control its identity, its membership, and its portability. These pages are where you, as a board user (or a member with the right grants), set the company's name and logo, decide who else can sign in, hand out invite links, review join requests, and move the whole company in and out of a portable package. The CEO agent never touches most of this — it is deliberately human territory.
docs/administration/trust-and-low-trust-review.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Trust & Low-Trust Review
Some work in a Paperclip company is born from input you cannot vouch for: an untrusted pull request, an external ticket, a dependency diff, or output an agent generated from any of those. The goal of trust presets is simple — keep that kind of work *contained* while it runs, and make sure nothing it produces is silently fed into a more trusted agent before a human (or a trusted reviewer) has looked at it.
docs/guides/day-to-day/artifacts.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Artifacts
As your agents work, they don't just leave comments — they produce things. A drafted document, a generated image, a rendered video, a CSV export, a file they attached to an issue. Those tangible outputs are **artifacts**, and the **Artifacts** page is the one place where you can see every one of them across your whole company, without opening each issue to go hunting.
docs/guides/day-to-day/issues.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Issues
docs/guides/org/skills.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Skills
docs/guides/org/team-catalog.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Team Catalog
Setting up a company from an empty page is a lot of decisions: which agents to hire, who reports to whom, what projects to open, what recurring work to schedule, and which skills each agent needs. The **Team Catalog** skips that blank-page problem. It's a set of ready-made starter teams — small, working groups of agents, projects, tasks, and skills — that you can browse and install into a company in one step.
docs/how-to/sync-to-cloud-upstream.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.525.0
paperclip_version: v2026.609.0
---
# Sync a local company to a Paperclip Cloud upstream
docs/reference/adapters/external-adapters.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# External Adapters
External adapters let you ship a Paperclip adapter as its own npm package or local directory. Use them when you want independent versioning, separate distribution, or a runtime that should not live inside the Paperclip repo.
docs/reference/adapters/gemini-local.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Gemini Local
`gemini_local` runs Google's Gemini CLI on the same machine as Paperclip. Use it when you want a local agent with session resume, configurable sandboxing, and Paperclip skills injected into Gemini's skills directory.
docs/reference/api/companies.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Companies
Companies are the top-level tenant boundary in Paperclip. Every agent, project, issue, approval, cost event, and asset belongs to exactly one company, and the API enforces that boundary on every company-scoped route.
docs/reference/api/issues.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Issues
docs/reference/api/overview.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# API Overview
Paperclip exposes a JSON API for company control-plane work: companies, agents, issues, approvals, costs, routines, secrets, activity, and dashboard state. This page is the shared reference for how the API is structured before you jump into a specific resource.
docs/reference/api/routines.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Routines
Routines are Paperclip's recurring execution layer. Use them when you want an agent to run on a schedule, respond to a webhook, or be kicked off manually through the API.
docs/reference/api/teams-catalog.md
+231
View File
@@ -0,0 +1,231 @@
---
paperclip_version: v2026.609.0
---
# Teams Catalog API
The teams catalog API is the control-plane surface behind catalog *teams* — the ready-made starter groups Paperclip ships with the app. A catalog team bundles a small set of agents, projects, tasks, and the skills they need, so you can drop a whole working unit into a company in one step. These endpoints let you browse the catalog, inspect a single team and its files, see what is already installed in a company, preview an import, and install a team.
For the user-facing concept and CLI workflow, see [Teams Commands](../cli/teams.md) and the [Team Catalog guide](../../guides/org/team-catalog.md). This page documents the raw HTTP endpoints that those tools call.
> All routes here are mounted under `/api`. The browsing routes need only an authenticated caller and no company context; the `installed`, `preview`, and `install` routes are company-scoped and check company access.
There are two kinds of catalog teams. **Bundled** teams ship inside the app and are the everyday starting points. **Optional** teams are extras, some of which pull in skills from external sources. The `kind` filter switches between the two.
---
## Browse the catalog
```
GET /api/teams/catalog
```
Returns the catalog teams the caller can see. Browsing reads the catalog without writing anything and requires no company context.
### Query parameters
| Parameter | Values | Description |
|---|---|---|
| `kind` | `bundled`, `optional` | Filter by catalog kind. |
| `category` | string | Filter by catalog category slug. |
| `q` | string | Free-text search over the catalog. |
Each catalog team in the response carries `id`, `key`, `kind`, `category`, `slug`, `name`, `description`, `path`, `entrypoint`, `schema`, `defaultInstall`, `recommendedForCompanyTypes`, `tags`, a `counts` object (`agents`, `projects`, `tasks`, `routines`, `localSkills`, `catalogSkills`, `externalSkillSources`), `rootAgentSlugs`, `agentSlugs`, `projectSlugs`, `requiredSkills`, `envInputs`, `sourceRefs`, `files`, `trustLevel`, `compatibility`, and `contentHash`. Optional teams sourced from a package also include `packageName` and `packageVersion`.
---
## Inspect one catalog team
```
GET /api/teams/catalog/{catalogId}
```
Returns the full record for a single catalog team — the same shape as a list entry, including its agents, projects, tasks, required skills, and file manifest. Inspecting a team before you install it is the clearest way to see exactly what will land in the company.
The path segment `{catalogId}` is a catalog reference: a catalog team ID, key, or unique slug. You can also pass the reference explicitly with the `ref` query parameter, which takes precedence over the path segment.
### Query parameters
| Parameter | Description |
|---|---|
| `ref` | Catalog reference (ID, key, or slug). Overrides the `{catalogId}` path segment when present. |
---
## Read a catalog team file
```
GET /api/teams/catalog/{catalogId}/files
```
Returns one file out of the catalog team package — for example `TEAM.md`. Use this to read a team's manifest or any referenced file without installing it.
### Query parameters
| Parameter | Description |
|---|---|
| `ref` | Catalog reference (ID, key, or slug). Overrides the `{catalogId}` path segment when present. |
| `path` | Relative path of the file to read inside the team package. Defaults to `TEAM.md`. |
The response carries `catalogTeamId`, `path`, `kind`, `content`, `language`, and `markdown`.
---
## List installed catalog teams
```
GET /api/companies/{companyId}/teams/catalog/installed
```
Returns the catalog teams already installed in the given company. This is the company-lensed view: it tells you which teams are present and lets a client flag teams that have drifted out of date from the current catalog version. Company access is checked before the listing runs.
---
## Preview an install
```
POST /api/companies/{companyId}/teams/catalog/{catalogId}/preview
```
Runs the import on the server and returns the plan without writing anything to the company. The preview reports what would be created, which skills the team needs and how they would be prepared, and any warnings or errors. Company access is checked before the preview runs.
All body fields are optional:
| Field | Type | Description |
|---|---|---|
| `targetManagerAgentId` | string or `null` | Existing agent ID that the catalog's root agents should report to. |
| `targetManagerSlug` | string or `null` | Portable manager slug that the catalog's root agents should report to. |
| `include` | object | Portability include block selecting which entity kinds to import. |
| `agents` | `"all"` or array of slugs | Restrict the import to selected agent slugs. |
| `collisionStrategy` | `rename`, `skip`, `replace` | How to handle entities that already exist. |
| `nameOverrides` | object (`slug` → `name`) | Override imported entity names. |
| `selectedFiles` | array of strings | Restrict the import to selected portable files. |
| `sourcePolicy` | object | Gate external skill sources. Accepts `allowExternalSources`, `allowUnpinnedOptionalSources`, and `allowLocalPathSources` booleans. |
The `{catalogId}` path segment is a catalog reference, and the `ref` query parameter overrides it when present, exactly as on the browse routes.
<!-- tabs: cURL, JavaScript, Python -->
<!-- tab: cURL -->
```bash
curl -X POST "http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"targetManagerSlug": "cto",
"collisionStrategy": "rename"
}'
```
<!-- tab: JavaScript -->
```js
const res = await fetch(
"http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview",
{
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
targetManagerSlug: "cto",
collisionStrategy: "rename",
}),
},
);
const plan = await res.json();
```
<!-- tab: Python -->
```py
import requests
res = requests.post(
"http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview",
headers={"Authorization": f"Bearer {token}"},
json={
"targetManagerSlug": "cto",
"collisionStrategy": "rename",
},
)
plan = res.json()
```
<!-- /tabs -->
---
## Install a team
```
POST /api/companies/{companyId}/teams/catalog/{catalogId}/install
```
Does what `preview` shows: imports the team into the company, creating its agents, projects, and tasks, and preparing its required skills. On success the route responds with `201`. Because installing a team creates agents, the caller must be able to create agents in the company — board callers need the `agents:create` permission (local implicit and instance-admin board callers are exempt), and agent callers need an `agents:create` grant or the equivalent agent permission.
The install body accepts everything `preview` accepts, plus:
| Field | Type | Description |
|---|---|---|
| `adapterOverrides` | object (`slug` → override) | Pin an imported agent to an adapter. Each override is an object with `adapterType` (string) and an optional `adapterConfig` object. |
| `secretValues` | object (`key` → `value`) | Provide values for the secret env inputs the team declares. |
As with preview, `{catalogId}` is a catalog reference and the `ref` query parameter overrides it when present.
<!-- tabs: cURL, JavaScript, Python -->
<!-- tab: cURL -->
```bash
curl -X POST "http://localhost:3100/api/companies/company-1/teams/catalog/product-engineering/install" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"targetManagerSlug": "cto",
"adapterOverrides": {
"senior-coder": { "adapterType": "claude_local" }
}
}'
```
<!-- tab: JavaScript -->
```js
const res = await fetch(
"http://localhost:3100/api/companies/company-1/teams/catalog/product-engineering/install",
{
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
targetManagerSlug: "cto",
adapterOverrides: {
"senior-coder": { adapterType: "claude_local" },
},
}),
},
);
const result = await res.json();
```
<!-- tab: Python -->
```py
import requests
res = requests.post(
"http://localhost:3100/api/companies/company-1/teams/catalog/product-engineering/install",
headers={"Authorization": f"Bearer {token}"},
json={
"targetManagerSlug": "cto",
"adapterOverrides": {
"senior-coder": {"adapterType": "claude_local"},
},
},
)
result = res.json()
```
<!-- /tabs -->
---
## Practical notes
- Catalog teams ship without a fixed adapter per agent on purpose. Use `adapterOverrides` to pin a specific agent to a runtime such as `claude_local` or `codex_local`; agents you do not override are resolved at import time.
- Browse, inspect, and file reads require only an authenticated caller. The `installed`, `preview`, and `install` routes check company access first.
- Preview writes nothing. Run it before `install` to confirm what will be created and how the team's skills will be prepared.
- The install route enforces the `agents:create` permission. If you lack it, the install is rejected before anything is created.
docs/reference/cli/access.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Access, Profile & Instance Admin
docs/reference/cli/activity.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Activity Commands
docs/reference/cli/adapter.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Adapter Commands
docs/reference/cli/agent.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Agent Commands
docs/reference/cli/approval.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Approval Commands
docs/reference/cli/asset.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Asset Commands
docs/reference/cli/authentication.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Authentication & Tokens
docs/reference/cli/cloud.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Cloud Sync Commands
docs/reference/cli/commands.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Command Reference
> **This page has moved.** The single-page command reference has been split into one page per command family. Start at the [CLI Overview](./overview.md) for the full reference map, or jump straight to a command family:
docs/reference/cli/common-options.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Common Options & Connection
docs/reference/cli/company.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Company Commands
docs/reference/cli/connect.md
+106
View File
@@ -0,0 +1,106 @@
---
paperclip_version: v2026.609.0
---
# Connect Command
When you sit down at a fresh terminal and want the Paperclip CLI to start talking to a running instance, `connect` is the friendly front door. It walks you through one short conversation — which server, which persona, which company and agent — and at the end it has minted a token, saved a reusable profile, and printed the environment exports you need. You do not have to know any IDs up front or hand-craft a context file; the wizard discovers what is available and lets you pick.
Reach for `paperclipai connect` the very first time you set up the CLI, whenever you want to add another saved profile (a second instance, a different company, a new agent), or any time you would rather click through choices than type out `context set` and `auth login` by hand.
> **Note:** `connect` is interactive by design. It needs a real terminal (a TTY) on both input and output. In scripts and CI it will refuse to run and tell you to pass `--api-base`/`--api-key` or use the `context` and token commands instead. See [Common Options](./common-options.md) for the non-interactive path.
---
## What it does, end to end
`connect` is a wizard, not a group of subcommands. You run the single command and answer a handful of prompts:
```sh
paperclipai connect
```
Under the hood it walks through these steps:
1. **Confirm the API base.** It pre-fills the API base it would otherwise resolve (see [Common Options](./common-options.md) for that resolution order) and lets you accept or change it. The placeholder is `http://localhost:3100`.
2. **Health-check the server.** It calls `GET /api/health` against the base you chose and stops early if the instance is not reachable — so you find connection problems now, not three commands later.
3. **Log you in as a board operator.** It runs the interactive board login to obtain a board credential, which it uses to discover the companies you can see.
4. **Pick a persona.** You choose whether this profile connects as a **board operator** or as an **agent in a company**.
5. **Name the profile.** It suggests the current profile name (or `default`) and lets you keep or rename it.
6. **Choose company (and agent).** A board profile can optionally pin a default company; an agent profile must pick a company and then an agent within it.
7. **Mint a token, save the profile, print exports.** It creates the right kind of token, writes a persona-aware profile into your context file, makes that profile current, and prints the shell exports you can paste to use the new credential immediately.
---
## The two personas
The one decision that shapes everything else is **persona**. You can skip the prompt by passing `--persona board` or `--persona agent`; otherwise the wizard asks.
| Persona | What it creates | Company & agent |
|---|---|---|
| `board` | A board API token, scoped to the instance. | Company is **optional** — you may pin a default for the profile or choose `(none)`. No agent. |
| `agent` | An agent API key, scoped to one company and one agent. | Company is **required**, and you then pick one of that company's agents. The company must have at least one agent. |
A board profile carries board authority across the instance; an agent profile is bound to exactly one company and one agent. This is the same persona split described under [Context profiles](./common-options.md). For how each credential type is minted and what it can do, see [Authentication](./authentication.md).
```sh
# Connect straight as a board operator, skipping the persona prompt
paperclipai connect --persona board
# Connect as an agent (you'll still pick the company and agent interactively)
paperclipai connect --persona agent
```
---
## Naming the token and the env var
Two flags let you control how the resulting credential is labelled and stored, so you do not have to accept the defaults.
```sh
paperclipai connect --token-name "laptop-board" --api-key-env-var-name PAPERCLIP_API_KEY
```
| Flag | Default | Use |
|---|---|---|
| `--persona <persona>` | _(prompted)_ | The persona to configure: `board` or `agent`. Pass it to skip the persona question. |
| `--api-key-env-var-name <name>` | `PAPERCLIP_API_KEY` | The name of the environment variable the profile will read its key from at call time. The profile stores this **name**, never the token itself. |
| `--token-name <name>` | A timestamped label | The label to give the created token. Defaults to `cli-board-<timestamp>` for a board token or `cli-agent-<timestamp>` for an agent key. |
> **Tip:** The profile records the *name* of the env var, not the secret. After connecting, keep the token in your environment (the printed exports do exactly this) so your context file stays safe to share. This is the same `apiKeyEnvVarName` mechanism explained in [Common Options](./common-options.md).
---
## What you get back
When the wizard finishes it confirms the connection (`Connected profile '<name>' as board.` or `... as <agent name>.`) and returns a result you can read or script against. Pass `--json` for the machine-readable form.
The result includes the profile name, the persona, the resolved `apiBase`, the `companyId` (and `agentId`/`agentName` for an agent profile), the created `key` (its `id`, `name`, `createdAt`, `token`, and — for a board token — `expiresAt`), and a ready-to-paste **`exports`** block:
```sh
export PAPERCLIP_API_URL='http://localhost:3100'
export PAPERCLIP_COMPANY_ID='<company-id>'
export PAPERCLIP_AGENT_ID='<agent-id>'
export PAPERCLIP_API_KEY='<token>'
```
The `PAPERCLIP_COMPANY_ID` and `PAPERCLIP_AGENT_ID` lines appear only when they apply, and the last line uses whatever name you set with `--api-key-env-var-name`. Paste the block into your shell and the rest of the CLI will pick up the new profile and credential immediately.
> **Warning:** The plaintext `token` is shown once, in the wizard output and in the `exports` block. Capture it now — store it in your secret manager or export it into your environment. The saved profile only references the env var by name; it never holds the token for you to recover later.
---
## Common Options
`connect` accepts the standard client options — `--data-dir <path>`, `--api-base <url>`, `--api-key <token>`, `--context <path>`, `--profile <name>`, `-C, --company-id <id>`, and `--json`. Of these, `--api-base`, `--context`, `--profile`, and `--company-id` seed the wizard's starting values (the API base it pre-fills, the context file it writes, the profile name it suggests, and the company it pre-selects). See [Common Options](./common-options.md) for how API base, context, and company scope are resolved, and [Output and Scripting](./output-and-scripting.md) for `--json` usage.
> **Note:** `connect` performs an interactive board login as part of its flow, so passing `--api-key` is not the way to drive it non-interactively. If you need a scripted setup, mint a token another way and configure the profile with `context set` — the path `connect` itself points you to when there is no TTY.
---
## See also
- [Authentication](./authentication.md) — how board tokens and agent keys are minted and what each can do
- [Common Options](./common-options.md) — shared client flags, context profiles, and API base resolution
- [Output and Scripting](./output-and-scripting.md) — working with `--json` output
- [Overview](./overview.md) — the CLI's place in the operating model
docs/reference/cli/control-plane-commands.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Control-Plane Commands
> **This page has moved.** Operating a company from the terminal is now documented per command family. Start at the [CLI Overview](./overview.md), or go straight to what you need:
docs/reference/cli/cost.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Cost, Finance & Budget Commands
docs/reference/cli/dashboard.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Dashboard Commands
docs/reference/cli/dev-environments.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Worktree & Environment Lab
docs/reference/cli/feedback.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Feedback Commands
docs/reference/cli/goal.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Goal Commands
docs/reference/cli/installation.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Installing the CLI
docs/reference/cli/issue.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Issue Commands
docs/reference/cli/output-and-scripting.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Output & Scripting
docs/reference/cli/overview.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# CLI Overview
docs/reference/cli/plugin.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Plugin Commands
docs/reference/cli/project.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Project Commands
docs/reference/cli/prompt.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Prompt Handoff
docs/reference/cli/routine.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Routine Commands
docs/reference/cli/run.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Run (Heartbeat) Commands
docs/reference/cli/secrets.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Secrets Commands
docs/reference/cli/setup-commands.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Setup Commands
docs/reference/cli/skills.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Skills Commands
docs/reference/cli/teams.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Teams Commands
A *team* in the catalog is a ready-made starter group — a small set of agents, projects, tasks, and the skills they need — that Paperclip ships with the app. Use `paperclipai teams` when you want to browse those team templates, inspect what one would create, preview the import against a real company, and then install it. Think of it as the team-shaped equivalent of the skills catalog: instead of one reusable procedure, you get a whole working unit you can drop into a company in one step.
docs/reference/cli/token.md
+140
View File
@@ -0,0 +1,140 @@
---
paperclip_version: v2026.609.0
---
# Token Commands
Use these commands when you need to mint, list, or revoke the API keys that let agents and board operators talk to a Paperclip instance from outside the browser — CI jobs, scripts, headless agent runners, or your own terminal. The `token` group has two halves: `token agent`, which manages the keys an individual agent uses to act on the instance, and `token board`, which manages the keys your board-operator identity uses to drive companies and the control plane.
Every command here accepts the [common client options](./common-options.md) (`--data-dir`, `--api-base`, `--api-key`, `--context`, `--profile`, `--json`). The `agent` subcommands are company-scoped and require `-C, --company-id <id>`; on the `board` side, `--company-id` is optional and only sets the audit context for the key you create.
> **Warning:** Creating a token returns the secret `token` value exactly once, at creation time. Paperclip does not store it in a way you can read back — `token agent list` and `token board list` return metadata only (id, name, timestamps), never the token. Capture the value when you create the key, and treat it as a credential: anyone holding it can act as that agent or board user.
---
## When to reach for each command
| Command | Use |
|---|---|
| `token agent create` | Mint a new API key for a specific agent. |
| `token agent list` | List an agent's existing API keys (metadata only). |
| `token agent revoke` | Revoke one of an agent's API keys by ID. |
| `token board create` | Mint a named API key for your board-operator identity. |
| `token board list` | List the board API keys for the current board user. |
| `token board revoke` | Revoke a board API key by ID. |
---
## Agent API keys
An agent API key is the credential an agent presents when it acts on the instance — the same kind of key a join request mints when it is approved. Use `token agent` when you are provisioning an agent runner yourself and want to create, audit, or retire its keys directly.
Every `token agent` command is company-scoped and identifies the agent with `--agent`, which accepts an agent ID, shortname, or unambiguous name. The CLI resolves that reference to a concrete agent inside the company before it does anything else, so a typo or an agent in the wrong company fails fast with `Agent not found`.
### Create an agent key
`token agent create` mints a new key for the named agent and prints the agent, its company, and the created `key` — including the one-time `token` value.
```sh
paperclipai token agent create --company-id <company-id> --agent <agent> --name ci-runner
```
| Flag | Use |
|---|---|
| `-C, --company-id <id>` | Required. Company the agent belongs to. |
| `--agent <agent>` | Required. Agent ID, shortname, or unambiguous name. |
| `--name <name>` | API key label. Defaults to `cli-agent`. |
> **Tip:** Capture the `token` from the output immediately — it is the only time you will see it. Give each key a descriptive `--name` (for example the host or pipeline it runs on) so a later `token agent list` tells you what each key is for.
### List agent keys
`token agent list` returns the keys defined for an agent. The human-readable output shows each key's `id`, `name`, `createdAt`, and `revokedAt` — never the token itself.
```sh
paperclipai token agent list --company-id <company-id> --agent <agent>
paperclipai token agent list --company-id <company-id> --agent <agent> --json
```
| Flag | Use |
|---|---|
| `-C, --company-id <id>` | Required. Company the agent belongs to. |
| `--agent <agent>` | Required. Agent ID, shortname, or unambiguous name. |
### Revoke an agent key
`token agent revoke` takes the key ID as a positional argument and revokes it. Once revoked, the key can no longer authenticate.
```sh
paperclipai token agent revoke <keyId> --company-id <company-id> --agent <agent>
```
| Argument / Flag | Use |
|---|---|
| `<keyId>` | Required. The agent API key ID to revoke. |
| `-C, --company-id <id>` | Required. Company the agent belongs to. |
| `--agent <agent>` | Required. Agent ID, shortname, or unambiguous name. |
---
## Board API keys
A board API key is the credential your board-operator identity uses to drive the instance from a script — the headless equivalent of being signed in on the board. Use `token board` to mint a long-lived key for automation, see which keys exist for your board user, and revoke one when it is no longer needed.
Unlike the agent commands, `token board` does not require a company. The optional `-C, --company-id <id>` only records the company used for audit context on the key you create.
### Create a board key
`token board create` mints a named key for the current board user and prints the created `key`, including its one-time `token`. By default a board key inherits the server's expiry policy; you can control expiry with exactly one of the expiry flags below.
```sh
# A key that expires 90 days from now
paperclipai token board create --name ci-deploy --ttl-days 90
# A key with an explicit expiry timestamp
paperclipai token board create --name nightly --expires-at 2026-12-31T00:00:00Z
# A non-expiring key
paperclipai token board create --name long-lived --never-expires
```
| Flag | Use |
|---|---|
| `-C, --company-id <id>` | Optional. Company ID recorded for audit context. |
| `--name <name>` | API key label. Defaults to `cli-board`. |
| `--expires-at <iso8601>` | Expiration timestamp. Rejected if it is not a valid date. |
| `--ttl-days <days>` | Expiration in days from now. Must be a positive number. |
| `--never-expires` | Create a non-expiring key. |
> **Note:** The expiry flags are alternatives — `--never-expires` wins, then `--expires-at`, then `--ttl-days`. If you pass none of them, the key takes whatever expiry the server assigns by default.
### List board keys
`token board list` returns the board API keys for the current board user. The human-readable output shows each key's `id`, `name`, `createdAt`, `lastUsedAt`, `expiresAt`, and `revokedAt` — metadata only.
```sh
paperclipai token board list
paperclipai token board list --json
```
### Revoke a board key
`token board revoke` takes the key ID as a positional argument and revokes it.
```sh
paperclipai token board revoke <keyId>
```
| Argument | Use |
|---|---|
| `<keyId>` | Required. The board API key ID to revoke. |
---
## See also
- [Common Options](./common-options.md) — the shared client flags every token command accepts.
- [Authentication](./authentication.md) — `connect`, `auth login`, board claim, and the broader credential bootstrap flow.
- [Access, Profile & Instance Admin](./access.md) — join requests, which mint agent API keys on approval, and `whoami` for confirming the identity a key resolves to.
- [Agent Commands](./agent.md) — create and configure the agents whose keys you mint here.
- [Output and Scripting](./output-and-scripting.md) — using `--json` to capture a freshly minted token in a script.
docs/reference/cli/workspace.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Workspace, Org & Environment Commands
docs/reference/deploy/docker.md
+4
View File
@@ -1,3 +1,7 @@
---
paperclip_version: v2026.609.0
---
# Docker
Use Docker when you want a self-contained Paperclip instance without installing Node or pnpm on the host machine.
docs/reference/skills.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
paperclip_version: v2026.529.0
paperclip_version: v2026.609.0
---
# Skills Reference
site/content.json
+12
View File
@@ -326,6 +326,10 @@
"title": "Adapters",
"file": "../docs/reference/api/adapters.md"
},
{
"title": "Teams Catalog",
"file": "../docs/reference/api/teams-catalog.md"
},
{
"title": "Plugins",
"file": "../docs/reference/api/plugins.md"
@@ -370,6 +374,14 @@
"title": "Authentication & Tokens",
"file": "../docs/reference/cli/authentication.md"
},
{
"title": "Connect",
"file": "../docs/reference/cli/connect.md"
},
{
"title": "Token",
"file": "../docs/reference/cli/token.md"
},
{
"title": "Company",
"file": "../docs/reference/cli/company.md"