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 setupPrerequisites
- 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
npx copilotkit@latest createThe 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:
{
"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.
INTELLIGENCE_API_URL=https://...
INTELLIGENCE_GATEWAY_WS_URL=wss://...
CPK_INTELLIGENCE_API_KEY=cpk-...
CPK_TELEMETRY_ID=...
SL_ENABLED=trueKeep 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
npm run devThe 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:
npx copilotkit@latest local setup
npx copilotkit@latest local connect --approve-connectionThe 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.
| Command | What it does |
|---|---|
npx copilotkit@latest local status | Shows service health, URLs, and any failed setup step. |
npx copilotkit@latest local start | Starts the app's local stack. |
npx copilotkit@latest local stop | Stops the stack and keeps its data. |
npx copilotkit@latest local login | Opens the local dashboard and signs you in. |
npx copilotkit@latest local setup | Installs the stack, configures the Automatic Learning model, or resumes setup. |
npx copilotkit@latest local update | Updates the stack to the latest release and keeps its data. |
npx copilotkit@latest local renew | Renews the evaluation license. |
npx copilotkit@latest local delete | Asks, 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-runThe 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 verifyIt 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-tripWhat --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 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. |
--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 still 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. |
How is this guide?