From 56a39fea3da009b12bc7d148b737143e390507d8 Mon Sep 17 00:00:00 2001 From: dotta Date: Mon, 23 Mar 2026 15:13:45 -0500 Subject: [PATCH] Add importing & exporting company guide Documents the `paperclipai company export` and `paperclipai company import` CLI commands, covering package format, all options, target modes, collision strategies, GitHub sources, interactive selection, and API endpoints. Co-Authored-By: Paperclip Co-Authored-By: Claude Opus 4.6 --- docs/docs.json | 3 +- .../board-operator/importing-and-exporting.md | 201 ++++++++++++++++++ 2 files changed, 203 insertions(+), 1 deletion(-) create mode 100644 docs/guides/board-operator/importing-and-exporting.md diff --git a/docs/docs.json b/docs/docs.json index 96b9f696..a13a1e77 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -48,7 +48,8 @@ "guides/board-operator/managing-tasks", "guides/board-operator/approvals", "guides/board-operator/costs-and-budgets", - "guides/board-operator/activity-log" + "guides/board-operator/activity-log", + "guides/board-operator/importing-and-exporting" ] }, { diff --git a/docs/guides/board-operator/importing-and-exporting.md b/docs/guides/board-operator/importing-and-exporting.md new file mode 100644 index 00000000..ae4f36a6 --- /dev/null +++ b/docs/guides/board-operator/importing-and-exporting.md @@ -0,0 +1,201 @@ +--- +title: Importing & Exporting Companies +summary: Export companies to portable packages and import them from local paths or GitHub +--- + +Paperclip companies can be exported to portable markdown packages and imported from local directories or GitHub repositories. This lets you share company configurations, duplicate setups, and version-control your agent teams. + +## Package Format + +Exported packages follow the [Agent Companies specification](/companies/companies-spec) and use a markdown-first structure: + +```text +my-company/ +├── COMPANY.md # Company metadata +├── agents/ +│ ├── ceo/AGENTS.md # Agent instructions + frontmatter +│ └── cto/AGENTS.md +├── projects/ +│ └── main/PROJECT.md +├── skills/ +│ └── review/SKILL.md +├── tasks/ +│ └── onboarding/TASK.md +└── .paperclip.yaml # Adapter config, env inputs, routines +``` + +- **COMPANY.md** defines company name, description, and metadata. +- **AGENTS.md** files contain agent identity, role, and instructions. +- **SKILL.md** files are compatible with the Agent Skills ecosystem. +- **.paperclip.yaml** holds Paperclip-specific config (adapter types, env inputs, budgets) as an optional sidecar. + +## Exporting a Company + +Export a company into a portable folder: + +```sh +paperclipai company export --out ./my-export +``` + +### Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--out ` | Output directory (required) | — | +| `--include ` | Comma-separated set: `company`, `agents`, `projects`, `issues`, `tasks`, `skills` | `company,agents` | +| `--skills ` | Export only specific skill slugs | all | +| `--projects ` | Export only specific project shortnames or IDs | all | +| `--issues ` | Export specific issue identifiers or IDs | none | +| `--project-issues ` | Export issues belonging to specific projects | none | +| `--expand-referenced-skills` | Vendor skill file contents instead of keeping upstream references | `false` | + +### Examples + +```sh +# Export company with agents and projects +paperclipai company export abc123 --out ./backup --include company,agents,projects + +# Export everything including tasks and skills +paperclipai company export abc123 --out ./full-export --include company,agents,projects,tasks,skills + +# Export only specific skills +paperclipai company export abc123 --out ./skills-only --include skills --skills review,deploy +``` + +### What Gets Exported + +- Company name, description, and metadata +- Agent names, roles, reporting structure, and instructions +- Project definitions and workspace config +- Task/issue descriptions (when included) +- Skill packages (as references or vendored content) +- Adapter type and env input declarations in `.paperclip.yaml` + +Secret values, machine-local paths, and database IDs are **never** exported. + +## Importing a Company + +Import from a local directory, GitHub URL, or GitHub shorthand: + +```sh +# From a local folder +paperclipai company import ./my-export + +# From a GitHub URL +paperclipai company import https://github.com/org/repo + +# From a GitHub subfolder +paperclipai company import https://github.com/org/repo/tree/main/companies/acme + +# From GitHub shorthand +paperclipai company import org/repo +paperclipai company import org/repo/companies/acme +``` + +### Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--target ` | `new` (create a new company) or `existing` (merge into existing) | inferred from context | +| `--company-id ` | Target company ID for `--target existing` | current context | +| `--new-company-name ` | Override company name for `--target new` | from package | +| `--include ` | Comma-separated set: `company`, `agents`, `projects`, `issues`, `tasks`, `skills` | auto-detected | +| `--agents ` | Comma-separated agent slugs to import, or `all` | `all` | +| `--collision ` | How to handle name conflicts: `rename`, `skip`, or `replace` | `rename` | +| `--ref ` | Git ref for GitHub imports (branch, tag, or commit) | default branch | +| `--dry-run` | Preview what would be imported without applying | `false` | +| `--yes` | Skip the interactive confirmation prompt | `false` | +| `--json` | Output result as JSON | `false` | + +### Target Modes + +- **`new`** — Creates a fresh company from the package. Good for duplicating a company template. +- **`existing`** — Merges the package into an existing company. Use `--company-id` to specify the target. + +If `--target` is not specified, Paperclip infers it: if a `--company-id` is provided (or one exists in context), it defaults to `existing`; otherwise `new`. + +### Collision Strategies + +When importing into an existing company, agent or project names may conflict with existing ones: + +- **`rename`** (default) — Appends a suffix to avoid conflicts (e.g., `ceo` becomes `ceo-2`). +- **`skip`** — Skips entities that already exist. +- **`replace`** — Overwrites existing entities. Only available for non-safe imports (not available through the CEO API). + +### Interactive Selection + +When running interactively (no `--yes` or `--json` flags), the import command shows a selection picker before applying. You can choose exactly which agents, projects, skills, and tasks to import using a checkbox interface. + +### Preview Before Applying + +Always preview first with `--dry-run`: + +```sh +paperclipai company import org/repo --target existing --company-id abc123 --dry-run +``` + +The preview shows: +- **Package contents** — How many agents, projects, tasks, and skills are in the source +- **Import plan** — What will be created, renamed, skipped, or replaced +- **Env inputs** — Environment variables that may need values after import +- **Warnings** — Potential issues like missing skills or unresolved references + +### Common Workflows + +**Clone a company template from GitHub:** + +```sh +paperclipai company import org/company-templates/engineering-team \ + --target new \ + --new-company-name "My Engineering Team" +``` + +**Add agents from a package into your existing company:** + +```sh +paperclipai company import ./shared-agents \ + --target existing \ + --company-id abc123 \ + --include agents \ + --collision rename +``` + +**Import a specific branch or tag:** + +```sh +paperclipai company import org/repo --ref v2.0.0 --dry-run +``` + +**Non-interactive import (CI/scripts):** + +```sh +paperclipai company import ./package \ + --target new \ + --yes \ + --json +``` + +## API Endpoints + +The CLI commands use these API endpoints under the hood: + +| Action | Endpoint | +|--------|----------| +| Export company | `POST /api/companies/{companyId}/export` | +| Preview import (existing company) | `POST /api/companies/{companyId}/imports/preview` | +| Apply import (existing company) | `POST /api/companies/{companyId}/imports/apply` | +| Preview import (new company) | `POST /api/companies/import/preview` | +| Apply import (new company) | `POST /api/companies/import` | + +CEO agents can also use the safe import routes (`/imports/preview` and `/imports/apply`) which enforce non-destructive rules: `replace` is rejected, collisions resolve with `rename` or `skip`, and issues are always created as new. + +## GitHub Sources + +Paperclip supports several GitHub URL formats: + +- Full URL: `https://github.com/org/repo` +- Subfolder URL: `https://github.com/org/repo/tree/main/path/to/company` +- Shorthand: `org/repo` +- Shorthand with path: `org/repo/path/to/company` + +Use `--ref` to pin to a specific branch, tag, or commit hash when importing from GitHub.