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 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 cloud-hosted Intelligence onboardingSign up or sign in, finish organization onboarding when required, then return to the CLI to select a project and connect your app.Start cloud-hosted setup

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

Team Self-hosted is the plan for a self-hosted deployment. You choose it on the cloud-hosted account. The deployment uses your identity provider.

Start a new app

Creating vs. adding to an existing app

init (aliased as create) 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.

Sign up or sign in

If you are not already signed in, the CLI opens a browser login flow. A new account accepts the CopilotKit Self-Service Agreement. An account that already accepted it does not accept it again.

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. A new organization chooses the Developer plan or a paid plan. Developer is the no-cost plan. Read Plans when you want to change that 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. To manage projects and API keys in the web app, see Cloud-hosted CopilotKit Intelligence.

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

.copilotkit/project.json
{
  "projectId": "proj_...",
  "projectSlug": "support-assistant",
  "clerkOrgId": "org_..."
}

Use the generated environment

init and its create alias write the cloud-hosted platform URLs, SL_ENABLED, and project-scoped runtime API key to .env.

.env
INTELLIGENCE_API_URL=https://...
INTELLIGENCE_GATEWAY_WS_URL=wss://...
CPK_INTELLIGENCE_API_KEY=cpk-...
CPK_TELEMETRY_ID=...
SL_ENABLED=true

Keep CPK_INTELLIGENCE_API_KEY on the server side. The project key connects the Runtime to Intelligence. CPK_TELEMETRY_ID is an optional, non-secret analytics identity.

Cloud-hosted setup does not issue COPILOTKIT_LICENSE_TOKEN. That token is only for offline or self-hosted licensing and does not replace the cloud-hosted project API key.

Start development

Terminal
npm run dev

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

Open the app and send a message. The agent answers in the chat. Then run npx copilotkit@latest verify. When the app is wired correctly, every check reports PASS.

To show the threads in your UI, use the Threads Drawer, or build your own with Headless Threads.

Evaluate Intelligence locally

To try Intelligence without a cloud-hosted project, run it in Docker on your own machine. Local evaluation is a preview supported on macOS with Docker Desktop. Read Evaluate Intelligence locally for the supported preview scope. From your app's folder:

Terminal
npx copilotkit@latest local setup
npx copilotkit@latest local connect --approve-connection

The CLI checks Docker, gets an evaluation license for your organization, installs the latest release, and connects the app to it. Read Evaluate Intelligence locally for requirements, dashboard sign-in, and model setup.

CommandWhat it does
npx copilotkit@latest local statusShows service health, URLs, and any failed setup step.
npx copilotkit@latest local startStarts the app's local stack.
npx copilotkit@latest local stopStops the stack and keeps its data.
npx copilotkit@latest local loginOpens the local dashboard and signs you in.
npx copilotkit@latest local setupInstalls the stack, configures the Automatic Learning model, or resumes setup.
npx copilotkit@latest local updateUpdates the stack to the latest release and keeps its data.
npx copilotkit@latest local renewRenews the evaluation license.
npx copilotkit@latest local deleteAsks, then deletes the stack and its data.

Import and synchronize historical conversations

To import ADK or LangGraph history into your project, run a dry run first:

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

The dry run shows the source agent keys, conversation counts, skips, and the estimated upload size. It does not open an import batch. For the full import flow, see Add AG-UI Streams to Existing Threads. Source-specific setup lives in Add AG-UI streams to ADK sessions and Add AG-UI streams to LangGraph threads.

Verify your setup

verify checks that your app is wired correctly. It runs from the terminal, so it also works when there is no browser, for example React Native or a runtime on a remote host.

npx copilotkit@latest verify

It checks that:

  • A cloud-hosted project is selected.
  • A project API key authenticates.
  • The runtime responds.
  • The runtime declares at least one agent.

It reports the runtime version, the agent framework, the gateway wiring, and the 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.

OptionWhat it does
--runtime-url <url>The runtime endpoint to probe. Default http://localhost:3000/api/copilotkit. Pass this whenever your runtime is elsewhere.
--round-tripAlso run the agent and read its answer back.
--agent <id>Which declared agent to run, when the runtime declares several.
--expect-runtime <mode>intelligence or oss. Without it, an app with no project, no Intelligence key, and no Intelligence client is checked as oss. With oss, cloud-hosted project and credential checks do not apply, and the command passes only with --round-trip --agent <id>.
--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.
--jsonEmit a machine-readable payload alone on stdout.

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

Auth commands

CommandWhat it does
npx copilotkit@latest loginOpens the browser sign-in flow and stores a local CLI session.
npx copilotkit@latest whoamiShows the signed-in user and active organization.
npx copilotkit@latest logoutClears the local CLI session.

Project commands

CommandWhat it does
npx copilotkit@latest project selectSelects or creates a cloud-hosted CopilotKit Intelligence project for the current directory.
npx copilotkit@latest import --source adk --dry-runPreviews historical Google ADK conversation threads before import.
npx copilotkit@latest import --source langgraph --dry-runPreviews historical LangGraph conversation threads before import.
npx copilotkit@latest license createIssues a CopilotKit license token for flows that still require one.
npx copilotkit@latest license listLists 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

CommandWhat it does
npx copilotkit@latest skills installInstalls CopilotKit agent skills for supported coding agents.
npx copilotkit@latest skills onboardInstalls skills, then starts agent-assisted onboarding for an existing app.

How is this guide?