copilotkit 3.0.2 → 3.0.4

package/README.md

@@ -1,6 +1,8 @@
 # CopilotKit CLI
 
-The CopilotKit CLI scaffolds starter apps and manages local CLI authentication for CopilotKit Intelligence onboarding.
+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
 
@@ -30,6 +32,11 @@ 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`
@@ -47,7 +54,13 @@ 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`.
+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
 
@@ -56,13 +69,34 @@ when you already have an app and want your coding agent to add CopilotKit for yo
 
 ```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 all CopilotKit agent skills for your coding
+`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. It runs without a TTY, so it is safe in CI.
+`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:
 
@@ -76,7 +110,8 @@ agent (Claude Code, Codex, Cursor, Gemini, and others) by running the standalone
 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.
+in; use `skills install -y` (or `--agent <name>`) for non-interactive
+environments.
 
 When to use which:
 
@@ -94,11 +129,18 @@ The CLI expects:
 - 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.
+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 template requires a license, the CLI also ensures `COPILOTKIT_LICENSE_TOKEN` is present in `.env`.
+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:
 
@@ -106,7 +148,19 @@ After creation, add any provider secrets required by the template. Most template
 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`.
+(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.
 
@@ -114,11 +168,28 @@ Do not commit generated `.env` files or personal secrets.
 
 ## Run A Generated Project
 
-After scaffolding:
+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 <project>` because it cannot change your shell's working directory. `npm run dev` is always left for you to run:
 
 ```bash
 cd my-agent
-npm install
 npm run dev
 ```
 
@@ -131,7 +202,7 @@ 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.
+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
 
@@ -145,10 +216,11 @@ 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.
+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
 
@@ -177,3 +249,35 @@ 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 <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.