# 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: ```bash npx copilotkit@latest init ``` For this workspace, build and run the local CLI with Nx: ```bash pnpm nx build cli node dist/apps/cli/index.js --help ``` ## Discover Commands Run help first when exploring the CLI: ```bash copilotkit --help copilotkit docs copilotkit version copilotkit whoami ``` Use `copilotkit docs` to open 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: ```bash 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. ```bash 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 ` — comma-separated skills to install (default: all), e.g. `--skill react-core,runtime`. - `-a, --agent ` — 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 ` 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 `) 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: ```bash 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 ""` 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](#environment-files)), so the two are always in agreement. The CLI also prints `cd ` because it cannot change your shell's working directory. `npm run dev` is always left for you to run: ```bash 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: ```bash 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: ```bash 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: ```bash 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). ```bash gh workflow run "pkg-pr-new (cli)" --ref \ -f cli_env=production \ -f template_ref= # 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 `-pre.` 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.