# 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? [#what-is-this]

The CopilotKit CLI helps you create CopilotKit apps connected to CopilotKit Intelligence, whether cloud-hosted or [self-hosted](/react-native/claude-sdk-python/intelligence/self-hosting). 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.

<OpsPlatformCTA
  variant="inline"
  title="Start cloud-hosted Intelligence onboarding"
  body="Sign up or sign in, finish organization onboarding when required, then return to the CLI to select a project and connect your app."
  ctaLabel="Start cloud-hosted setup"
  href="https://intelligence.copilotkit.ai/"
  surface="docs_cli_intro_signup"
/>

## Prerequisites [#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

<Callout type="info" title="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.
</Callout>

## Start a new app [#start-a-new-app]

<Callout type="info" title="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](/react-native/claude-sdk-python/quickstart) instead.
</Callout>

<Steps>
  <Step>
    ### Run create [#run-create]

    ```bash title="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.
  </Step>

  <Step>
    ### Sign up or sign in [#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.
  </Step>

  <Step>
    ### Select or create an organization [#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](/react-native/claude-sdk-python/intelligence/plans) when you want to change that choice.
  </Step>

  <Step>
    ### Return to the terminal [#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.
  </Step>

  <Step>
    ### 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](/react-native/claude-sdk-python/intelligence/managed-intelligence-platform).

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

    ```json title=".copilotkit/project.json"
    {
      "projectId": "proj_...",
      "projectSlug": "support-assistant",
      "clerkOrgId": "org_..."
    }
    ```
  </Step>

  <Step>
    ### Use the generated environment [#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`.

    ```bash title=".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.
  </Step>

  <Step>
    ### Start development [#start-development]

    ```bash title="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](/prebuilt-components/copilot-threads-drawer),
    or build your own with [Headless Threads](/headless-threads).
  </Step>
</Steps>

## Evaluate Intelligence locally [#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](/react-native/claude-sdk-python/intelligence/self-hosting-local) for the supported preview scope. From your app's folder:

```bash title="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](/react-native/claude-sdk-python/intelligence/self-hosting-local) 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 [#import-and-synchronize-historical-conversations]

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

<Tabs groupId="cli-import-source" items={["ADK", "LangGraph"]}>
  <Tab value="ADK">

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

  </Tab>
  <Tab value="LangGraph">

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

  </Tab>
</Tabs>

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](/react-native/claude-sdk-python/threads-import). Source-specific setup lives in [Add AG-UI streams to ADK sessions](/google-adk/threads-import) and [Add AG-UI streams to LangGraph threads](/langgraph-python/threads-import).

## Verify your setup [#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.

```bash
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.

<Callout type="warn" title="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.
</Callout>

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:

```bash
npx copilotkit@latest verify --round-trip
```

<Callout type="warn" title="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.
</Callout>

| 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 [#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 [#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 [#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. |
