Paperclip CLI

2026.416.0 verified Thu Apr 23 auth: no javascript

Paperclip CLI is a robust command-line interface designed for orchestrating and managing teams of AI agents to automate and run business operations. Currently at version 2026.416.0, the project demonstrates a rapid development and release cadence, with multiple significant updates often occurring within weeks. Its key differentiators include a modern chat-style interface for managing agent issues, flexible multi-stage execution policies, comprehensive features for importing and exporting entire 'agent companies,' and a powerful plugin framework with an accompanying SDK for extensibility. Paperclip CLI integrates seamlessly with a wide array of popular AI models and CLIs, such as Google Gemini, Cursor, OpenCode, Pi, Claude Code, and Codex, providing a unified platform for deploying and overseeing diverse AI-driven workflows.

Common errors

error Error: Node.js version unsupported. Paperclip requires Node.js >=20. ↓

cause The system's Node.js version is older than the minimum requirement specified in `package.json` (`>=20`).

fix

Upgrade your Node.js installation to version 20 or higher. Using a version manager like nvm is recommended (e.g., nvm install 20 && nvm use 20).

error Error: Failed to authenticate with AI provider. Invalid API key or missing credentials. ↓

cause The API key for an integrated AI model (e.g., Gemini, Claude) is either missing from environment variables/configuration, or the provided key is invalid/expired.

fix

Ensure the correct API key is set for the specific AI model. This often involves setting an environment variable (e.g., export GEMINI_API_KEY='your_key_here') or configuring it via paperclipai config or the web dashboard.

error Command failed with exit code 1: paperclipai agent add --name "..." --model "unknown-model" ↓

cause Attempting to add an agent using an AI model name that Paperclip does not recognize or support, or if a required local adapter for that model is not installed/configured.

fix

Verify the exact model name with npx paperclipai help agent add. Ensure any necessary local AI CLIs (e.g., Google Gemini CLI for its adapter) are installed and properly set up on your system as per Paperclip's integration guide.

Warnings

gotcha Paperclip CLI integrates with various external AI models (e.g., Gemini, Claude). It's crucial to correctly configure your API keys for these services, either through environment variables or Paperclip's internal settings. Incorrectly configured or missing API keys are a primary cause of agent operational failures and authentication errors. ↓

fix Consult the Paperclip documentation for the specific AI model you are using to ensure proper API key setup. Typically, this involves setting environment variables like `GEMINI_API_KEY` or using Paperclip's `config` command.

breaking With version 2026.416.0, the traditional comment timeline for issues was replaced by a full chat-style thread powered by `assistant-ui`. Any custom tools, scripts, or integrations that programmatically interacted with the old comment structure for issues will require updates to align with the new conversational model. ↓

fix Review and update any automation that reads from or writes to issue comments. The new interaction paradigm may require different parsing or interaction methods if you were previously scraping or injecting directly into the comment timeline.

gotcha AI agent operations can incur substantial costs due to frequent API calls to underlying language models. Users are responsible for monitoring their usage with AI service providers. While Paperclip might offer some local execution modes or cost tracking, it does not inherently prevent external billing. ↓

fix Set up budget alerts with your AI model providers. Actively monitor agent activity and optimize prompts to reduce token consumption. Utilize local adapters and sandbox modes when available to minimize production costs during development and testing.

gotcha Paperclip has a very aggressive release schedule. While this brings rapid innovation, it means the API and CLI options can evolve quickly. Although major breaking changes are usually highlighted, minor behavioral shifts or new flags can appear frequently. ↓

fix Before major deployments or significant feature utilization, it is recommended to review the latest GitHub release notes. Consider testing in a staging environment to catch any unexpected changes or new requirements. Use `npx paperclipai --version` to confirm your installed version.

Install

npm install paperclipai

yarn add paperclipai

pnpm add paperclipai

Imports

PaperclipAgent
wrong
```
import { PaperclipAgent } from 'paperclipai';
```
correct
```
import { PaperclipAgent } from '@paperclip/sdk';
```
The `paperclipai` package is primarily a command-line interface (CLI) and is not intended for direct programmatic imports into end-user applications. Programmatic interaction, such as defining custom agents or extending functionality, is typically achieved through a dedicated Plugin SDK, which is usually found under a separate package name like `@paperclip/sdk`.
IssuePolicy
```
import type { IssuePolicy } from '@paperclip/sdk/types';
```
When developing plugins or extensions for Paperclip, type definitions for core concepts like `IssuePolicy` are generally imported from a dedicated types module within the Plugin SDK. This ensures type safety and consistency when interacting with Paperclip's internal structures.
CompanyExporter
```
import { CompanyExporter } from '@paperclip/sdk/cli-utils';
```
Utility functions that mirror or assist with CLI operations, such as company import/export, might be exposed via specialized modules within the Plugin SDK (e.g., `@paperclip/sdk/cli-utils`). This is primarily for advanced plugin developers or those extending Paperclip's CLI itself, rather than general application development.

Quickstart

This quickstart demonstrates how to initialize a new AI agent company, add a 'ContentCreator' agent utilizing the 'gemini-pro' model, assign it a task (creating a blog post), and then launch the Paperclip dashboard to monitor its progress and interactions.

npx paperclipai company create --name "MyAICompany" --template "default"
npx paperclipai agent add --company "MyAICompany" --name "ContentCreator" --model "gemini-pro"
npx paperclipai issue create --company "MyAICompany" --agent "ContentCreator" --title "Draft Blog Post on AI Trends" --description "Generate a 1000-word blog post about the latest trends in AI, focusing on LLMs and ethical considerations. Include relevant keywords and a call to action."
npx paperclipai dashboard