CopilotKit CLI

Use the CopilotKit CLI to create apps, sign in to cloud-hosted CopilotKit Intelligence, select projects, provision runtime API keys, import historical conversations, and install agent skills.

What is this?#

The CopilotKit CLI helps you create CopilotKit apps connected to CopilotKit Intelligence, whether cloud-hosted or self-hosted. It handles browser sign-in, project selection, project-scoped runtime API keys, historical thread import, and local project configuration so your app can use durable threads and conversation history.

Use the CLI when you want to start a new app, import historical ADK or LangGraph conversations, or install CopilotKit agent skills for your coding agent.

Start managed Intelligence onboarding

Sign up or sign in, finish organization onboarding when required, then return to the CLI to select a project and connect your app.

Start managed onboarding

Prerequisites#

Node.js 20+
A CopilotKit account for cloud-hosted CopilotKit Intelligence
An OpenAI API key or another model provider key for the starter app you choose

Team Self-hosted is a plan, not a deployment login

A Team Self-hosted purchase uses a Clerk-backed hosted organization. A customer-run self-hosted deployment uses the customer's identity provider and never sees the Clerk admission flow or hosted organization plan gate.

Start a new app#

Creating vs. adding to an existing app

create (aliased as init) scaffolds a brand-new project in its own directory — it prompts for an app name and does not detect or bootstrap an app you already have. To add CopilotKit to an existing app, follow the manual installation in the Quickstart instead.

Run create#

Terminal

npx copilotkit@latest create

The CLI prompts for the app name and framework, opens browser sign-in when needed, scaffolds the starter, and connects the app to a cloud-hosted CopilotKit Intelligence project.

If you are not already signed in, the CLI opens a browser login flow. During Clerk signup, new users accept the CopilotKit Self-Service Agreement. Existing accounts do not re-consent.

If the browser does not open, the CLI prints a login URL and supports a manual paste fallback.

Select or create an organization#

Select or create an organization in the browser. Existing hosted organizations created before the rollout cutoff continue without a plan prompt. Every new hosted organization created at or after the rollout cutoff must explicitly choose Developer or a paid plan. Developer is the no-cost choice. Clerk's automatic Free assignment does not count as the required Developer-or-paid choice.

Return to the terminal#

After organization onboarding, return to the terminal. The original CLI command resumes and prompts you to select or create a project.

Select or create a project#

Choose an existing cloud-hosted project or create a new one. A project is where your app's threads, messages, and platform metadata are stored.

The CLI writes the selected project to .copilotkit/project.json:

.copilotkit/project.json

{
  "projectId": "proj_...",
  "projectSlug": "support-assistant",
  "clerkOrgId": "org_..."
}

Use the generated environment#

The CLI writes the hosted platform URLs and project-scoped runtime API key to .env.

.env

INTELLIGENCE_API_URL=https://...
INTELLIGENCE_GATEWAY_WS_URL=wss://...
INTELLIGENCE_API_KEY=cpk_...

Keep INTELLIGENCE_API_KEY on the server side. It is a runtime key for the selected project, not a frontend token.

Start development#

Terminal

npm run dev

The starter runs your local app and runtime while storing durable threads in the cloud-hosted project selected by the CLI.

Import and synchronize historical conversations#

Use import from a CopilotKit app created with the CLI and CopilotKit Intelligence enabled. The importer targets the CopilotKit Intelligence project already selected for the current directory.

npx copilotkit@latest import --source adk --dry-run

npx copilotkit@latest import --source langgraph --dry-run

The command runs interactively by default. Start with --dry-run to discover source agent keys, conversation counts, skips, and the estimated upload size without opening an import batch.

If you need to import into a different project, select it before continuing with the real import:

Terminal

npx copilotkit@latest project select

This changes the project selected for the current directory and writes its project-scoped runtime key to the starter's generated .env.

Before the real import, export the destination values from that .env:

Terminal

export INTELLIGENCE_API_URL="https://..."
export INTELLIGENCE_API_KEY="cpk_..."

The importer reads --api-url and --api-key or the current process environment. It does not load .env or .copilotkit/project.json automatically. COPILOTKIT_API_KEY is also accepted for the key.

Project selection updates the app configuration; the importer still receives its destination through flags or exported environment variables.

For the full adoption flow, see Import & Synchronize Thread History. Source-specific setup lives in Synchronize ADK threads and Synchronize LangGraph threads.

Verify your setup#

verify answers the question every integration reaches: is this actually working? It checks the wiring from outside the browser, so it is the proof to reach for on a surface that has no browser at all — React Native, or a runtime on a remote host.

npx copilotkit@latest verify

It checks that a hosted project is selected, that a project API key authenticates, that the runtime responds, and that the runtime declares at least one agent — then reports the runtime version, the agent framework, gateway wiring, and license state.

Read the individual checks, not the summary

Every check reports PASS, FAIL, or UNKNOWN. UNKNOWN means the check could not run. It never means the check passed.

To prove the agent actually runs rather than that it is configured, add --round-trip. It sends one real request through the runtime and reads the answer back off the thread:

npx copilotkit@latest verify --round-trip

What --round-trip does not prove

It sends a fixed prompt and records the answer's character count and any tool-call names — never the answer's text. It proves an answer came back; it can never tell you what the answer said, so it is no substitute for checking a response against the data your project actually holds.

It also proves an agent answered under the declared id, not which deployment answered — a runtime pointed at another project's agent responds identically.

Because it runs the agent, it costs a model call and records a thread. That is why it is opt-in rather than the default.

Option	What it does
`--runtime-url <url>`	The runtime endpoint to probe. Default `http://localhost:3000/api/copilotkit` — pass this whenever your runtime is elsewhere.
`--round-trip`	Also run the agent and read its answer back.
`--agent <id>`	Which declared agent to run, when the runtime declares several.
`--expect-runtime <mode>`	`intelligence` (default) or `oss`. With `oss`, hosted-project and credential checks do not apply.
`--timeout <seconds>`	How long to wait for the answer. Default `90`.
`--header "<name>: <value>"`	Extra request header, repeatable. Use it when your `identifyUser` reads a session the CLI does not carry.
`--json`	Emit a machine-readable payload alone on stdout.

verify exits non-zero unless every check passed, so it works as a CI gate.

Auth commands#

Command	What it does
`npx copilotkit@latest login`	Opens the browser sign-in flow and stores a local CLI session.
`npx copilotkit@latest whoami`	Shows the signed-in user and active organization.
`npx copilotkit@latest logout`	Clears the local CLI session.

Project commands#

Command	What it does
`npx copilotkit@latest project select`	Selects or creates a cloud-hosted CopilotKit Intelligence project for the current directory.
`npx copilotkit@latest import --source adk --dry-run`	Previews historical Google ADK conversation threads before import.
`npx copilotkit@latest import --source langgraph --dry-run`	Previews historical LangGraph conversation threads before import.
`npx copilotkit@latest license create`	Issues a CopilotKit license token for flows that require one.
`npx copilotkit@latest license list`	Lists license metadata for the current user or organization.

Re-running project select is safe when you need to move a CLI-created app to a different cloud-hosted project. The command updates .copilotkit/project.json and provisions a project-scoped API key for the selected project.

Skills commands#

Command	What it does
`npx copilotkit@latest skills install`	Installs CopilotKit agent skills for supported coding agents.
`npx copilotkit@latest skills onboard`	Installs skills, then starts agent-assisted onboarding for an existing app.

Next steps#

Cloud-hosted platform: Cloud-hosted CopilotKit Intelligence — login, projects, API keys, threads, and plans in the hosted web app
Add threads: use the Threads Drawer for a drop-in thread switcher, or Headless Threads to build your own thread UI
Synchronize thread history: Import & Synchronize Thread History — import existing ADK or LangGraph conversations and keep future CopilotKit runs synchronized
Self-hosting: Self-host CopilotKit Intelligence — run CopilotKit Intelligence in your own Kubernetes cluster

CopilotKit CLI

What is this?#

Prerequisites#

Start a new app#

Run create#

Sign up or sign in#

Select or create an organization#

Return to the terminal#

Select or create a project#

Use the generated environment#

Start development#

Import and synchronize historical conversations#

Verify your setup#

Auth commands#

Project commands#

Skills commands#

Next steps#

On this page