{"id":17862,"library":"paperclipai","title":"Paperclip CLI","description":"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.","status":"active","version":"2026.416.0","language":"javascript","source_language":"en","source_url":"https://github.com/paperclipai/paperclip","tags":["javascript","paperclip","ai","agents","orchestration","cli"],"install":[{"cmd":"npm install paperclipai","lang":"bash","label":"npm"},{"cmd":"yarn add paperclipai","lang":"bash","label":"yarn"},{"cmd":"pnpm add paperclipai","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import { PaperclipAgent } from 'paperclipai';","symbol":"PaperclipAgent","correct":"import { PaperclipAgent } from '@paperclip/sdk';"},{"note":"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.","symbol":"IssuePolicy","correct":"import type { IssuePolicy } from '@paperclip/sdk/types';"},{"note":"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.","symbol":"CompanyExporter","correct":"import { CompanyExporter } from '@paperclip/sdk/cli-utils';"}],"quickstart":{"code":"npx paperclipai company create --name \"MyAICompany\" --template \"default\"\nnpx paperclipai agent add --company \"MyAICompany\" --name \"ContentCreator\" --model \"gemini-pro\"\nnpx 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.\"\nnpx paperclipai dashboard","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2026.416.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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`).","cause":"The system's Node.js version is older than the minimum requirement specified in `package.json` (`>=20`).","error":"Error: Node.js version unsupported. Paperclip requires Node.js >=20."},{"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.","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.","error":"Error: Failed to authenticate with AI provider. Invalid API key or missing credentials."},{"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.","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.","error":"Command failed with exit code 1: paperclipai agent add --name \"...\" --model \"unknown-model\""}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}