CopilotKit CLI

The CopilotKit CLI scaffolds starter apps, connects project creation to a CopilotKit workspace through the Ops/Clerk platform, and manages local CLI authentication for CopilotKit Intelligence onboarding.

Install

Use the published package for normal onboarding:

npx copilotkit@latest init

For this workspace, build and run the local CLI with Nx:

pnpm nx build cli
node dist/apps/cli/index.js --help

Discover Commands

Run help first when exploring the CLI:

copilotkit --help
copilotkit docs
copilotkit version
copilotkit whoami

Use copilotkit docs to open https://docs.copilotkit.ai in your browser. In CI, or when the browser cannot be opened, the CLI prints the URL instead.

Use copilotkit login when you want to sign in before running workspace-gated commands. It stores the local CLI session used by whoami, license, and the init/create workspace connection; it does not scaffold a project or issue a license key by itself.

The onboarding commands are:

• copilotkit init
• copilotkit create

create is an alias for init. Both commands accept the same flags:

copilotkit init --name my-agent
copilotkit create --name my-agent --framework langgraph-py

Every supported framework ships with CopilotKit Intelligence (durable threads, persistence, insights), and init provisions a free license automatically — you sign in with your browser during scaffolding. The -i/--intelligence flag is retained as a deprecated no-op for backward compatibility.

Supported framework values include langgraph-py, langgraph-js, mastra, pydantic-ai, aws-strands-py, adk, a2a, microsoft-agent-framework-dotnet, microsoft-agent-framework-py, flows, llamaindex, agno, ag2, mcp-apps, agentcore-langgraph, agentcore-strands, a2ui, and opengenui.

init and create collect your starter choices, then connect project creation to your CopilotKit workspace through Ops/Clerk before scaffolding. If you already have a valid CLI session, the CLI reuses that workspace connection; otherwise it opens browser sign-in. This workspace connection is required for project creation and is separate from license issuance.

Skills And Agent-Assisted Onboarding

Use copilotkit create to start a new project. Use copilotkit skills onboard when you already have an app and want your coding agent to add CopilotKit for you.

copilotkit skills install
copilotkit skills install -y
copilotkit skills install --skill react-core,runtime --agent claude-code
copilotkit skills install --list
copilotkit skills onboard
copilotkit skills onboard --no-clipboard

copilotkit skills install installs CopilotKit agent skills for your coding agent (Claude Code, Codex, Cursor, Gemini, and others) by running the standalone skills installer under the hood.

By default it installs every skill and prompts you to choose which coding agents to install them to. Narrow or automate the install with these flags (they work on both install and onboard):

• -s, --skill <names> — comma-separated skills to install (default: all), e.g. --skill react-core,runtime.
• -a, --agent <names> — comma-separated coding agents to install to (default: choose interactively), e.g. --agent claude-code,cursor.
• -y, --yes — install everything (all skills to all agents) non-interactively.
• --global — install at the user level instead of the current project.
• --list — list the available skills and exit without installing (install only).

Choosing which coding agents to install to is interactive, so a non-interactive environment (CI, scripts) must make the choice deterministic: pass -y to install everything, or --agent <name> to target specific agents. Otherwise the command exits with guidance instead of hanging.

copilotkit skills onboard is a superset of install. It also:

• signs you in with your CopilotKit account, reusing your existing session and opening a browser sign-in only when you are not already signed in;
• stops before any repo-specific file changes — your coding agent performs the actual integration using the installed skills;
• copies a ready-to-paste agent prompt to your clipboard, and prints it instead when the clipboard is unavailable.

Pass --no-clipboard to always print the prompt instead of copying it. This is useful in headless or remote shells where clipboard access is unavailable. onboard requires an interactive terminal because it opens a browser to sign in; use skills install -y (or --agent <name>) for non-interactive environments.

When to use which:

• copilotkit create — scaffold a brand-new CopilotKit project.
• copilotkit skills onboard — add CopilotKit to an existing project with help from your coding agent.

Prerequisites

The CLI expects:

• Node.js and the package manager required by the selected template.
• git on PATH, because templates are downloaded with git sparse checkout and initialized as a new repository.
• uv for Python templates and the Intelligence sample app. Install it before running Python starters so their dependencies can sync cleanly.
• Python 3.10+ for the A2A template.
• The .NET SDK for the Microsoft Agent Framework .NET template.

Project creation requires a CopilotKit workspace connection through Ops/Clerk (browser sign-in when no session exists). Standard framework templates use that connection only to authorize creation; they do not request or write a license key. Threads-framework templates additionally issue a CopilotKit license key and write it into the generated project.

Environment Files

The scaffold step copies .env.example to .env when a template provides one. If the selected starter requires a license, the CLI also ensures COPILOTKIT_LICENSE_TOKEN is present in .env. Standard starters do not receive a license token.

After creation, add any provider secrets required by the template. Most templates use OpenAI:

OPENAI_API_KEY=your-key-here

(Replace your-key-here with your real key — placeholder-shaped values are rejected by the dev preflight described below.)

The ADK template uses GOOGLE_API_KEY. The A2A template uses both OPENAI_API_KEY and GOOGLE_API_KEY.

For threads-enabled scaffolds, npm run dev verifies the required key(s) before starting anything: if a key is unset, empty, or still an obvious placeholder (wrapped in <...>, starting with your-/your_, or ending in ... like the printed examples), the run exits with instructions naming the key, the vendor console URL to create one, and the exact .env line to add. A real key exported in your shell environment satisfies the check too. An exported empty or whitespace value falls back to the .env value, while an exported placeholder-shaped value fails the gate outright.

The Microsoft Agent Framework .NET template uses GitHub Models. Set its C# agent token with dotnet user-secrets set GitHubToken "<your-token>" from the generated agent/ directory.

Do not commit generated .env files or personal secrets.

Run A Generated Project

After scaffolding, the CLI prompts you to install dependencies:

Install dependencies now? (npm install) [Y/n]

Press Enter (or y) to let the CLI run the install command for you. Press n to skip and run it yourself later. Either way, the CLI then prints the exact next steps.

When a required LLM vendor API key is missing from .env — unset, empty, or still a placeholder — the next-step block names the key, links to the vendor console, and shows the exact .env line to add before you run the dev server:

Set OPENAI_API_KEY before running: Required by the agent runtime.
  Get a key:  https://platform.openai.com/api-keys
  Add to .env:  OPENAI_API_KEY=sk-...

This is the same key the npm run dev preflight gate enforces (see Environment Files), so the two are always in agreement.

The CLI also prints cd <project> because it cannot change your shell's working directory. npm run dev is always left for you to run:

cd my-agent
npm run dev

For Python-based templates, install uv first. Current Python, .NET, and threads templates are still installed and run from the scaffold root with npm install and npm run dev; their package scripts handle framework setup as needed.

For the A2A template, create the Python agent environment before starting dev:

python3 -m venv agents/.venv
agents/.venv/bin/pip install -r agents/requirements.txt

For the Intelligence threads template, keep Docker Desktop running before npm run dev. The root dev script starts the required Docker Compose services automatically when a license token is present in .env (without one it prints a "threads locked" hint and skips Docker), so a separate docker compose up step is only needed when you intentionally want to manage infrastructure by hand.

Diagnostics

Use copilotkit logs when onboarding fails or support needs local CLI diagnostics:

copilotkit logs
copilotkit logs --tail
copilotkit logs --tail --lines 100

With no flags, copilotkit logs prints the log file path. --tail prints recent structured log lines. Add --verbose to a CLI command when you need high-signal diagnostics mirrored to stderr during the run.

Project creation (init/create) connects to and revalidates the live Clerk workspace before scaffolding. License commands, including license list, revalidate the live Clerk organization before using local auth as needed. If a workspace or organization check fails because the cached session is stale, the CLI may clear local auth and rerun browser login before continuing.

Telemetry

The CLI collects anonymous usage data (command names, success/failure, timing — no project contents, no PII) to help improve the product. Collection is enabled by default; the first interactive run prints a one-time notice explaining what is collected and how to opt out.

Manage the preference at any time:

copilotkit telemetry status
copilotkit telemetry disable
copilotkit telemetry enable
copilotkit telemetry reset

Per-invocation environment overrides:

• DO_NOT_TRACK=1 — disable telemetry (consoledonottrack.com standard).
• COPILOTKIT_TELEMETRY_DISABLED=1 — disable telemetry.
• COPILOTKIT_TELEMETRY_OPT_IN=1 — enable telemetry without persisting a decision.

A previously persisted denial (copilotkit telemetry disable or the old first-run prompt) is always respected; no events are sent until telemetry is explicitly re-enabled. copilotkit telemetry reset restores the full fresh-install state: the decision is forgotten and the one-time notice shows again on the next interactive run.

Prerelease builds

Tester-facing prerelease builds are produced by CI via workflow_dispatch on the pkg-pr-new (cli) workflow — never built locally (the repo root .env targets local services, and CI is the reproducible path).

gh workflow run "pkg-pr-new (cli)" --ref <feature-branch> \
  -f cli_env=production \
  -f template_ref=<copilotkit-branch>   # optional; omit to use main

• cli_env — endpoint set baked into the binary (local, dev, staging, production; defaults to production).
• template_ref — CopilotKit/CopilotKit branch or tag that init templates and the _intelligence overlay are pinned to (the workflow validates it exists before building). Empty means main. The ag2 template comes from the third-party ag2ai/ag2-copilotkit-starter repo and is never repinned.

Open the workflow run and copy the npx https://pkg.pr.new/... command from the job summary; hand that one-liner to testers. Prerelease binaries report <version>-pre.<shortsha> from copilotkit --version, so a tester's build is always identifiable.

Pushes and PRs continue to publish CLI_ENV=local builds automatically, as before.

Note: workflow_dispatch only works against refs that contain the dispatch trigger — branches cut before this workflow landed need a merge from main first.