release: prepare Agora CLI v0.2.9

.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@v7
         with:
           go-version-file: go.mod
           cache: true
@@ -365,6 +365,24 @@ jobs:
             Remove-Item Env:VERSION, Env:AGORA_INSTALL_SOURCE, Env:RELEASES_DOWNLOAD_BASE_URL, Env:RELEASES_PAGE_URL -ErrorAction SilentlyContinue
           }
 
+      - name: Reject Windows PowerShell 5.1 installer runs
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $previousNativePreference = $PSNativeCommandUseErrorActionPreference
+          $PSNativeCommandUseErrorActionPreference = $false
+          $output = & powershell.exe -NoProfile -ExecutionPolicy Bypass -File ./install.ps1 2>&1 | Out-String
+          $exitCode = $LASTEXITCODE
+          $PSNativeCommandUseErrorActionPreference = $previousNativePreference
+          $global:LASTEXITCODE = 0
+
+          if ($exitCode -eq 0) {
+            throw 'Expected install.ps1 to reject Windows PowerShell 5.1.'
+          }
+          if ($output -notmatch 'requires PowerShell 7 or newer') {
+            throw "Expected an actionable PowerShell 7 requirement, got: $output"
+          }
+
       - name: Smoke test PowerShell installer S3 fallback
         if: runner.os == 'Windows'
         shell: pwsh

.github/workflows/govulncheck.yml

@@ -22,7 +22,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@v7
         with:
           go-version-file: go.mod
           cache: true

.github/workflows/pages.yml

@@ -34,7 +34,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@v7
         with:
           go-version-file: go.mod
           cache: true

.github/workflows/release.yml

@@ -33,7 +33,7 @@ jobs:
           fetch-depth: 0   # GoReleaser needs full history for changelog
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@v7
         with:
           go-version-file: go.mod
           cache: true
@@ -112,7 +112,7 @@ jobs:
         uses: actions/checkout@v7
 
       - name: Set up Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7
         with:
           node-version: "24"
           registry-url: "https://registry.npmjs.org"

CHANGELOG.md

@@ -15,10 +15,31 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ## [Unreleased]
 
+## [0.2.9] - 2026-08-21
+
+Quickstart project and environment consistency, Android onboarding, Windows installer compatibility, and release workflow maintenance.
+
 ### Added
 
 - Add the Android conversational AI client/server quickstart to `agora init` and `agora quickstart`, writing credentials only to the included Python server and returning setup steps for the server, HTTPS tunnel, and Android client ([#55](https://github.com/AgoraIO/cli/pull/55)).
 
+### Changed
+
+- Expand installation guidance with the canonical Agora CDN, GitHub-hosted fallbacks, the S3 mirror option, and a PowerShell 7 guard with an actionable process-scoped execution-policy workaround ([03f46af](https://github.com/AgoraIO/cli/commit/03f46af), [#61](https://github.com/AgoraIO/cli/pull/61)).
+- Update GitHub Actions dependencies to `actions/setup-node@v7` and `actions/setup-go@v7` ([#57](https://github.com/AgoraIO/cli/pull/57), [#58](https://github.com/AgoraIO/cli/pull/58)).
+- Align the Python quickstart `nextSteps` install command with the upstream template (`bun run setup` instead of `bun install`) ([#60](https://github.com/AgoraIO/cli/pull/60)).
+- Make clone-only quickstart creation explicit with `--template-only`; interactive runs prompt for an existing project when none resolves, while JSON, CI, and non-TTY runs fail before cloning with `QUICKSTART_PROJECT_REQUIRED` ([91cb8f7](https://github.com/AgoraIO/cli/commit/91cb8f7)).
+
+### Fixed
+
+- Bump the pinned Go toolchain to 1.26.6 to address reachable standard-library vulnerabilities reported by `govulncheck` in Go 1.26.5 ([09fcba8](https://github.com/AgoraIO/cli/commit/09fcba8)).
+- Ensure `agora init` and quickstart env writes create `server/.env` with `AGORA_APP_ID` and `AGORA_APP_CERTIFICATE` for Python and Go, including older directory layouts that previously emitted unsupported unprefixed names; align with the upstream Python and Go env-file migrations ([91cb8f7](https://github.com/AgoraIO/cli/commit/91cb8f7), [Python #26](https://github.com/AgoraIO-Conversational-AI/agent-quickstart-python/pull/26), [Go #8](https://github.com/AgoraIO-Conversational-AI/agent-quickstart-go/pull/8)).
+
+### Documentation
+
+- Add `docs/env-local.md` explaining that Quickstart env files are created by the CLI from the template example plus the selected project's App ID and App Certificate (not downloaded from Console); link it from `README.md`, `docs/llms.txt`, and `docs/sitemap.xml` ([#59](https://github.com/AgoraIO/cli/pull/59)).
+- Clarify the README Quick Start around `agora init` project selection (including `Default Project` reuse vs interactive picker), `--project` / `--new-project`, `.agora/project.json` vs `project use`, and that env files are written by the CLI rather than downloaded from Console ([#60](https://github.com/AgoraIO/cli/pull/60)).
+
 ## [0.2.8] - 2026-07-28
 
 Region-aware authentication, OAuth UX, quickstart compatibility, and installer and documentation delivery improvements.
@@ -363,7 +384,8 @@ Set `AGORA_ALLOW_UPGRADE_IN_CI=1` only when a CI job intentionally needs to muta
 - Support machine-readable JSON output for automation and agent workflows.
 - Ship automated release packaging through GoReleaser, including cross-platform archives, Linux packages, Homebrew, Scoop, npm wrapper packages, Docker images, and install scripts.
 
-[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.8...HEAD
+[Unreleased]: https://github.com/AgoraIO/cli/compare/v0.2.9...HEAD
+[0.2.9]: https://github.com/AgoraIO/cli/compare/v0.2.8...v0.2.9
 [0.2.8]: https://github.com/AgoraIO/cli/compare/v0.2.7...v0.2.8
 [0.2.7]: https://github.com/AgoraIO/cli/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/AgoraIO/cli/compare/v0.2.5...v0.2.6

CONTRIBUTING.md

@@ -37,7 +37,7 @@ For end-user behavior and machine-readable contracts, see:
 
 Requirements:
 
-- **Go** 1.26.2+ (see `go.mod`). Release builds intentionally track the current stable Go toolchain; this distributed CLI does not target older Go compiler support.
+- **Go** 1.26.6+ (see `go.mod`). Release builds intentionally track the current stable Go toolchain; this distributed CLI does not target older Go compiler support.
 - **Git**.
 - (Optional) `golangci-lint` v1.64.8 — install matches CI; instructions in
   the next section.

README.md

@@ -10,6 +10,7 @@ Native Agora CLI for authentication, project management, quickstart setup, and d
 
 - macOS 12+, Linux (glibc 2.31+ or musl), or Windows 10+ for the prebuilt binaries.
 - `git` on `PATH` for `agora init` and `agora quickstart create` (they shell out to `git clone`).
+- PowerShell 7+ (`pwsh`) for the native Windows installer.
 - For the source build, the Go toolchain pinned in [`go.mod`](go.mod).
 
 ### Install the CLI
@@ -26,19 +27,21 @@ agora --help
 
 The script is served from the Agora CDN (`dl.agora.io`, CloudFront). Binaries download from GitHub by default and automatically fall back to the CDN mirror if GitHub is unreachable; downloads are verified against `checksums.txt` regardless of source.
 
-Windows PowerShell:
+Windows PowerShell 7+:
 
 ```powershell
 irm https://dl.agora.io/cli/install.ps1 | iex
 ```
 
-If your PowerShell execution policy blocks inline scripts (the default on most Windows clients), download the installer to disk and run it with `-ExecutionPolicy Bypass`. The `Invoke-WebRequest` form works on both Windows PowerShell 5.1 and PowerShell 7+:
+If execution policy blocks the installer, download it to disk and launch it in a new PowerShell 7 process with a process-scoped bypass:
 
 ```powershell
 Invoke-WebRequest -Uri https://dl.agora.io/cli/install.ps1 -OutFile .\install.ps1
-powershell -ExecutionPolicy Bypass -File .\install.ps1
+pwsh -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
 ```
 
+An organization-level `MachinePolicy` or `UserPolicy` can override the process setting. In that case, ask an administrator to allow the script or use a verified release archive instead.
+
 Alternative install paths (GitHub-hosted; use `install.ps1` for PowerShell):
 
 ```bash
@@ -83,26 +86,61 @@ Requires the Go toolchain pinned in [go.mod](go.mod). For direct installer optio
 
 ## Quick Start
 
+Recommended path: install the CLI, log in, then run `agora init`. The CLI binds a project, clones an official quickstart, writes the runtime env file (App ID and App Certificate), and creates `.agora/project.json`. You do **not** need to download an env file from Agora Console for this flow.
+
 ```bash
+# 1) Log in
 agora login
+
+# 2) Create a local demo bound to a project
+# Interactive (TTY): reuses "Default Project" if present; otherwise prompts to pick or create
 agora init my-nextjs-demo --template nextjs
+# For deterministic non-interactive / --json / CI runs, select or create explicitly
+# agora init my-nextjs-demo --template nextjs --project <project-id-or-name>
+# agora init my-nextjs-demo --template nextjs --new-project
+
+# 3) Install deps and start the app (follow nextSteps from init; Next.js example:)
+cd my-nextjs-demo
+pnpm install
+# Newer pnpm may block dependency build scripts (ERR_PNPM_IGNORED_BUILDS). If so:
+# pnpm approve-builds --all
+# pnpm rebuild
+pnpm dev
+# Other templates print their own commands, e.g. python: bun run setup && bun run dev
+# go: make setup && make dev
+
+# 4) Open the app in a browser (Next.js default: http://localhost:3000)
+open http://localhost:3000
+# Linux: xdg-open http://localhost:3000
+# Windows: start http://localhost:3000
+
+# 5) Optional: check project/workspace readiness
 agora project doctor --json
 ```
 
+`init` also prints template-specific next steps in its output. Refresh credentials or rebind the repo later with:
+
+```bash
+cd my-nextjs-demo
+agora quickstart env write . --project <project-id-or-name>
+```
+
+If an env or project command reports `No project selected`, pass `--project`, run `agora project use <project>`, or work inside a directory that already has `.agora/project.json`. That is expected when none of those contexts exist—not a missing Console env download. `agora init` uses the onboarding selection flow described above instead.
+
 Command examples use `agora` for the installed CLI. Local source builds use `./agora` from the repo root.
 
 ## What You Can Build Quickly
 
 | Goal | Command | What You Get |
 |------|---------|--------------|
-| Next.js video app | `agora init my-nextjs-demo --template nextjs` | A cloned Next.js quickstart, project binding, and `.env.local` |
-| Python voice agent | `agora init my-python-demo --template python` | A Python quickstart with Agora credentials written for the backend |
-| Go voice agent | `agora init my-go-demo --template go` | A Go quickstart with Agora credentials written for the backend |
+| Next.js video app | `agora init my-nextjs-demo --template nextjs` | A cloned Next.js quickstart, `.agora` binding, and `.env.local` |
+| Python voice agent | `agora init my-python-demo --template python` | A Python quickstart with `server/.env` credentials |
+| Go voice agent | `agora init my-go-demo --template go` | A Go quickstart with `server/.env` credentials |
 | Android voice AI app | `agora init my-android-demo --template android` | An Android client with credentials written only to the included Python server |
 
 Android follows the same project binding and env-writing flow as the web quickstarts. Its `nextSteps` additionally cover starting the Python server, opening a temporary HTTPS tunnel, writing that public URL to `local.properties`, and assembling the Android client. The App Certificate remains only in `server/.env.local`.
 
-Run `agora quickstart list` to see all available templates.
+By default `init` reuses a project named `Default Project` when present. In an interactive TTY without that project, it prompts you to pick an existing project or create a new one. Non-interactive/`--json`/CI runs fall back to the most recent project (or create one when none exist). Pass `--project <id-or-name>` or `--new-project` to control selection explicitly. Run `agora quickstart list` to see all available templates.
 
 ## Command Model
 
@@ -126,13 +164,14 @@ The command model is intentionally layered:
 
 | Goal | Command |
 |------|---------|
-| New user, one shot | `agora init <name> --template <id>` |
+| New user, one shot | `agora init <name> --template <id>` (reuses `Default Project` / interactive picker; or `--project` / `--new-project`) |
 | List available templates | `agora quickstart list` |
-| Clone a starter only | `agora quickstart create ...` |
-| Re-sync env in a cloned quickstart | `agora quickstart env write [dir]` |
+| Clone a starter only | `agora quickstart create ... --template-only` |
+| Re-sync / rebind env in a cloned quickstart | `agora quickstart env write [dir]` (optional `--project` to rebind) |
 | Write env to an arbitrary path / non-quickstart repo | `agora project env write <path>` |
+| Set global CLI project context | `agora project use <project>` |
 | Install self-test | `agora doctor --json` |
-| Project/workspace readiness | `agora project doctor --json` |
+| Project/workspace readiness | `agora project doctor --json` (add `--deep` in a bound repo) |
 | Manage feature webhooks | `agora project webhook ... --json` |
 
 ### Env-related commands
@@ -156,7 +195,7 @@ agora introspect --json
 
 ### `init`
 
-Recommended onboarding command. It creates or binds a project, clones a quickstart, writes env, persists context, and prints next steps.
+Recommended onboarding command. By default it reuses a project named `Default Project` when present. In an interactive TTY without that project, it prompts you to pick or create one. Non-interactive/`--json`/CI runs fall back to the most recent project (or create one when none exist). Prefer `--project <id-or-name>` or `--new-project` for explicit selection. It clones a quickstart, writes the template env file from the project API, writes `.agora/project.json`, updates global context, and prints next steps.
 
 ### `quickstart`
 
@@ -208,7 +247,9 @@ Prints build metadata. Release binaries include version, commit, and build date.
 
 ## Env Files and Project Binding
 
-`quickstart env write` and `project env write` both keep dotenv files limited to runtime credentials, but they target different workflows:
+Env files hold runtime credentials. Project selection is separate: use `--project`, `.agora/project.json`, or `agora project use`. The CLI writes App ID and App Certificate from the selected project's API response into the template env file. It does **not** download a ready-made dotenv from Agora Console.
+
+Prefer `agora quickstart env write` inside official quickstarts. Use `agora project env write <path>` only when you need a specific dotenv path outside that layout.
 
 | Command | Env path | Key names |
 |---------|----------|-----------|
@@ -218,21 +259,23 @@ Prints build metadata. Release binaries include version, commit, and build date.
 Quickstart template behavior:
 
 - Next.js quickstarts write `.env.local` with `NEXT_PUBLIC_AGORA_APP_ID` plus `NEXT_AGORA_APP_CERTIFICATE`
-- Python quickstarts copy `server/.env.example` to `server/.env.local`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
-- Go quickstarts copy `server/.env.example` to `server/.env.local`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
+- Python quickstarts copy `server/.env.example` to `server/.env`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
+- Go quickstarts copy `server/.env.example` to `server/.env`, then use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE`
 - Existing Python and Go quickstarts keep their recorded env path and legacy `APP_ID` / `APP_CERTIFICATE` keys when reconfigured.
 
-`project env write` auto-detects Next.js workspaces (or accepts `--template nextjs|standard`) and writes `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE` or the Next.js equivalents. Use `quickstart env write` when you want the CLI to choose the official quickstart's env path.
+`project env write` auto-detects Next.js workspaces (or accepts `--template nextjs|standard`) and writes `AGORA_APP_ID` / `AGORA_APP_CERTIFICATE` or the Next.js equivalents.
 
 Existing `.env` and `.env.local` files are preserved: the CLI appends missing credentials, updates existing credential keys, and comments out duplicate or stale Agora credential aliases for the selected runtime.
 
+See [Using `.env.local`](docs/env-local.md) for how the CLI creates and updates env files from Quickstart examples and the selected project's credentials.
+
 See [docs/automation.md](docs/automation.md) for JSON fields and the full credential matrix.
 
 ### Repo-local binding
 
-The CLI writes repo-local project metadata to `.agora/project.json` so it can detect which Agora project a cloned demo is bound to even when you work inside the repo later.
+`.agora/project.json` is the **repo-local** project binding (not the env file). It lets the CLI know which Agora project a cloned demo uses when you work inside that repo later. `agora project use` only sets the **global CLI context** and does not rewrite `.agora/project.json`.
 
-Project resolution precedence is consistent across commands:
+Commands that resolve an existing project context, including env-write commands, use this precedence:
 
 1. explicit `--project` or positional project argument
 2. repo-local `.agora/project.json` resolved from the target repo path
@@ -341,7 +384,8 @@ The most common issues:
 - **OAuth browser does not open**: `agora login --no-browser` prints the URL so you can open it elsewhere; or `agora config update --browser-auto-open=false`.
 - **`git` is missing**: `agora init` and `agora quickstart create` shell out to `git clone`. Install `git` and retry.
 - **Project has no app certificate**: `quickstart env write`, `init`, and `project env --with-secrets` need a project with an App Certificate. Pick another project or enable one in [Agora Console](https://console.agora.io).
-- **No project selected**: pass `--project <name>`, run `agora project use <name>`, or run from a repo that already has `.agora/project.json`.
+- **No project selected**: the command has no project context. Pass `--project <name>`, run `agora project use <name>`, or work inside a repo with `.agora/project.json` (created by `init` / `quickstart env write`). Do not expect the CLI to infer a project from `.env.local` alone.
+- **Wrong or stale credentials in a quickstart**: re-run `agora quickstart env write . --project <id>` from the demo directory instead of pasting a Console-downloaded env file.
 
 Full guide with debug logging, CI tips, completion troubleshooting, and the `--debug` flag: [docs/troubleshooting.md](docs/troubleshooting.md).