copilotkit 2.1.2 → 3.0.1

package/README.md

@@ -0,0 +1,179 @@
+# CopilotKit CLI
+
+The CopilotKit CLI scaffolds starter apps 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 <https://docs.copilotkit.ai> in your browser. In CI, or when the browser cannot be opened, the CLI prints the URL instead.
+
+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`, and `agno`.
+
+## 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 onboard
+copilotkit skills onboard --no-clipboard
+```
+
+`copilotkit skills install` installs all CopilotKit agent skills for your coding
+agent (Claude Code, Codex, Cursor, Gemini, and others) by running the standalone
+`skills` installer under the hood. It runs without a TTY, so it is safe in CI.
+
+`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` 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.
+
+Every `init` authenticates with your CopilotKit account before scaffolding (browser sign-in when no session exists). 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 template requires a license, the CLI also ensures `COPILOTKIT_LICENSE_TOKEN` is present in `.env`.
+
+After creation, add any provider secrets required by the template. Most templates use OpenAI:
+
+```bash
+OPENAI_API_KEY=your-key-here
+```
+
+The ADK template uses `GOOGLE_API_KEY`. The A2A template uses both `GOOGLE_API_KEY` and `OPENAI_API_KEY`.
+
+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:
+
+```bash
+cd my-agent
+npm install
+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, 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.
+
+License, license list, and Intelligence init flows revalidate the live Clerk
+organization before using local auth. If that 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.