# Paperclip Company Portability Workflow: Import/Export with Secret Scrubbing

> Securely migrate your entire company data with Paperclip's import/export workflow. Effortlessly transfer agents, projects, tasks, and skills while automatically stripping secrets.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Paperclip enables secure migration of entire companies—including agents, projects, tasks, and skills—across environments through a three-stage export, preview, and apply workflow that automatically strips all secrets, local paths, and database IDs.**

The `paperclipai/paperclip` repository implements a robust company portability system that allows board operators to version-control and transfer AI agent configurations without exposing sensitive data. This workflow ensures that secret values never leave the originating instance while maintaining full structural integrity of the company definition.

## The Three-Stage Portability Workflow

The portability system follows a strict three-stage pipeline defined in [`server/src/routes/company-import-paths.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/company-import-paths.ts) to prevent accidental data leakage and provide full transparency before any changes are committed.

### Stage 1: Export Package Generation

During the export phase, the server constructs a portable markdown package conforming to the Agent Companies specification. The system gathers structural files including [`COMPANY.md`](https://github.com/paperclipai/paperclip/blob/main/COMPANY.md), `agents/`, `projects/`, `skills/`, `tasks/`, and [`.paperclip.yaml`](https://github.com/paperclipai/paperclip/blob/main/.paperclip.yaml) directories.

Critical security filtering occurs in [`server/src/services/company-import-transfers.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/company-import-transfers.ts), where the export service explicitly removes secret values, machine-local paths, and database identifiers before writing to the zip archive. This ensures the generated package contains only structural definitions without sensitive runtime data.

The export endpoint is defined as:

```

POST /api/companies/{companyId}/export

```

### Stage 2: Import Preview and Validation

Before any data modification occurs, the system generates an import plan through the preview endpoints. These endpoints return a detailed analysis of which entities will be created, renamed, skipped, or replaced, along with required environment inputs and warnings for missing dependencies.

The preview respects identical secret-scrubbing rules as the export phase, ensuring no secrets are introduced during the validation step. Available endpoints include:

- `POST /api/companies/{companyId}/imports/preview` (for existing companies)
- `POST /api/companies/import/preview` (for new company creation)

### Stage 3: Apply with Safety Controls

The final stage commits the import to the target company. By default, imported agents and routines are created in a **paused** state (`pauseAutomations: true`) to prevent immediate execution until explicitly activated by a board operator.

The apply endpoints enforce collision strategies (`rename`, `skip`, `replace`) and never persist secret values from the source package:

- `POST /api/companies/{companyId}/imports/apply`
- `POST /api/companies/import`

## How Secret Scrubbing Works

Secret scrubbing is enforced at the service layer rather than the client side. According to the implementation in [`server/src/services/company-import-transfers.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/company-import-transfers.ts), the system filters fields marked as secret during export, ensuring that "secret values, machine-local paths, and database IDs are never exported."

This server-side enforcement guarantees that downstream imports cannot accidentally acquire secrets from the source company, even if the export package is shared via public version control.

## CLI Commands for Company Import/Export

The Paperclip CLI provides direct interfaces to the portability API endpoints. All commands automatically respect the secret-scrubbing policy.

Export a company to a local directory:

```bash
paperclipai company export abc123 --out ./my-export \
  --include company,agents,projects

```

Preview an import without applying changes:

```bash
paperclipai company import ./my-export \
  --target existing --company-id abc123 \
  --dry-run

```

Apply an import to create a new company with paused automations:

```bash
paperclipai company import ./my-export \
  --target new \
  --new-company-name "Cloned Company" \
  --yes --json

```

Import from a remote GitHub repository with version pinning:

```bash
paperclipai company import org/repo \
  --ref v2.0.0 --target existing --company-id abc123 \
  --collision rename

```

## Key Implementation Files

The portability workflow is implemented across the following critical paths in the `paperclipai/paperclip` repository:

- **[`server/src/routes/company-import-paths.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/routes/company-import-paths.ts)**: Defines REST endpoints for export, preview, and apply operations.
- **[`server/src/services/company-import-transfers.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/company-import-transfers.ts)**: Core logic for building export packages and performing import writes, including secret filtering.
- **[`packages/shared/src/company-import-transfer.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/shared/src/company-import-transfer.ts)**: Shared TypeScript interfaces used by both server and UI layers.
- **[`ui/src/lib/import-transfer.ts`](https://github.com/paperclipai/paperclip/blob/main/ui/src/lib/import-transfer.ts)**: Client-side helper functions that interface with the import/export API from the web interface.
- **[`docs/guides/board-operator/importing-and-exporting.md`](https://github.com/paperclipai/paperclip/blob/main/docs/guides/board-operator/importing-and-exporting.md)**: Comprehensive documentation covering workflow options and security guarantees.

## Summary

- The Paperclip company portability workflow uses a three-stage pipeline: **Export**, **Preview**, and **Apply** to ensure safe cross-environment transfers.
- **Secret scrubbing** is enforced server-side in [`server/src/services/company-import-transfers.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/company-import-transfers.ts), automatically stripping sensitive values, local paths, and database IDs.
- The **preview stage** provides a dry-run import plan showing entity collisions and required inputs before any changes occur.
- Imported agents default to a **paused state** (`pauseAutomations: true`) to prevent unintended execution in new environments.
- The system supports **collision strategies** (`rename`, `skip`, `replace`) for handling naming conflicts during import.

## Frequently Asked Questions

### Does Paperclip export include API keys or environment secrets?

No. The export service explicitly filters out all secret values, machine-local paths, and database identifiers before generating the portable package. This scrubbing occurs in [`server/src/services/company-import-transfers.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/services/company-import-transfers.ts) and is enforced server-side, ensuring sensitive data never leaves the originating instance.

### Can I import a company without immediately activating its agents?

Yes. By default, the import process creates agents and routines in a paused state using `pauseAutomations: true`. This prevents imported automations from running until a board operator explicitly activates them through the UI or API.

### What happens if imported entities have the same names as existing ones?

The import workflow supports three collision strategies: `rename` (creates new entities with modified names), `skip` (preserves existing entities), and `replace` (overwrites existing entities). You specify the desired behavior using the `--collision` flag in the CLI or the corresponding API parameter.

### Is the company portability format compatible with version control?

Yes. The export generates a markdown-based package following the Agent Companies specification, including files like [`COMPANY.md`](https://github.com/paperclipai/paperclip/blob/main/COMPANY.md) and directories for `agents/`, `projects/`, and `skills/`. Because secret scrubbing removes all sensitive runtime data, these packages are safe to commit to Git repositories for versioning and sharing.