diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index a5b5df3..00d1f0c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -18,7 +18,7 @@ body: attributes: label: CLI version description: Output of `agora --version` - placeholder: "e.g. agora-cli 0.2.2 (commit abc1234, built 2026-05-26)" + placeholder: "e.g. agora-cli 0.2.5 (commit abc1234, built 2026-06-05)" validations: required: true diff --git a/AGENTS.md b/AGENTS.md index a5d1c38..40b265a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,7 +104,7 @@ agora **Design rules — do not break these:** - `project` = remote Agora control-plane resource; it never scaffolds local files -- `quickstart` = local repo clone; requires `git` on the PATH +- `quickstart` = local repo clone; requires `git` on the PATH; upstream `.git` is removed after clone so demos start without template history - `init` = the only command that composes both - The `add` namespace is reserved; keep it hidden and return a command-not-found error if invoked diff --git a/CHANGELOG.md b/CHANGELOG.md index 51e344c..65194ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,18 +15,26 @@ Earlier entries pre-date this convention and only carry their version's compare ## [Unreleased] -## [0.2.5] - 2026-06-01 +## [0.2.5] - 2026-06-05 -Installer migration improvements. +Installer migration, quickstart scaffold cleanup, and onboarding doc refresh. ### Added - Add `install.sh --replace-npm` to migrate from a global npm-managed `agoraio-cli` install to the standalone installer by running `npm uninstall -g agoraio-cli` before installing the binary. +- Emit a `clone:strip-git` progress event after removing upstream template git metadata during quickstart scaffolds. ### Changed +- Remove upstream `.git` metadata after quickstart scaffolds are cloned so demos start without the template repository's history. - Improve managed-install errors with explicit uninstall-and-reinstall guidance so users can switch to the standalone installer without relying on side-by-side PATH shadowing. - Update website install and troubleshooting docs with npm-to-standalone migration steps and clearer PATH shadowing guidance. +- Restructure README quick start, command routing tables, env workflows, and documentation index. +- Document CI and release workflow expectations in CONTRIBUTING.md. + +### Fixed + +- Bump the pinned Go toolchain to 1.26.4 so release builds include stdlib fixes for GO-2026-5037 and GO-2026-5039. ## [0.2.4] - 2026-06-01 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c693a37..84a984f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,6 +128,22 @@ change; prefer adding a new code and deprecating the old one over a rename. that is part of the public contract (JSON shape, exit code, stderr text). Use `app_test.go` for isolated helper logic. +## CI and releases + +GitHub Actions are configured for: + +- push and pull request validation on Linux, macOS, and Windows +- automated tag-driven releases for `v*` tags +- cross-platform release artifacts for Linux, macOS, and Windows + +Release workflow behavior: + +- a pushed tag matching `v*` (for example `v0.2.5`) triggers the release workflow +- the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically +- release artifacts include checksums, Cosign signatures, and an SBOM + +See [AGENTS.md](AGENTS.md) for the full release pipeline (npm, Homebrew, apt, GitHub Pages). + ## Branching model - `main` is always releasable. CI must be green before merge. diff --git a/README.md b/README.md index 457dcc6..d4e6067 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,6 @@ Native Agora CLI for authentication, project management, quickstart setup, and developer onboarding. Use it to go from an Agora account to a runnable app with one command. -```bash -agora login -agora init my-nextjs-demo --template nextjs -``` - -## 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 token service | `agora init my-go-demo --template go` | A Go server quickstart with project metadata and env wiring | - ## Install ### Requirements @@ -51,7 +38,7 @@ npm install -g agoraio-cli irm https://raw.githubusercontent.com/AgoraIO/cli/main/install.ps1 | iex ``` -Locked-down environments that block `curl | sh` can use npm, download a release archive from GitHub, or mirror the binary internally. Every release includes `checksums.txt`, a Cosign keyless signature, and an SBOM; see [docs/install.md](docs/install.md#enterprise--locked-down-environments) for manual tarball and verification steps. +Locked-down environments that block `curl | sh` can use npm, download a release archive from GitHub, or mirror the binary internally. Every release includes `checksums.txt`, a Cosign keyless signature, and an SBOM; see [docs/install.md](docs/install.md#enterprise--locked-down-environments) for manual tarball, checksum, and Cosign verification steps. Notes: @@ -59,51 +46,44 @@ Notes: - **Shell setup is auto-on**: the installer wires the install directory onto your `PATH` (when needed) and writes a shell completion script for the detected shell (bash, zsh, fish, or PowerShell). Pass `--no-path`, `--no-completion`, or the umbrella `--skip-shell` (PowerShell: `-NoPath` / `-NoCompletion` / `-SkipShell`) to opt out granularly. - Installer help is always available with `curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --help`. - Pinned versions, dry runs, custom install directories, npm details, and source builds are documented in [docs/install.md](docs/install.md). +- Release artifacts and checksums: [GitHub Releases](https://github.com/AgoraIO/cli/releases). Vulnerability disclosures: [SECURITY.md](SECURITY.md). -### Verifying release artifacts - -Every release ships with a SHA-256 `checksums.txt` and a Cosign keyless signature. The official installers verify the SHA-256 automatically. You can also verify manually: +### Build from source ```bash -# Verify SHA-256 against the published checksums.txt -curl -fsSLO https://github.com/AgoraIO/cli/releases/download/vX.Y.Z/checksums.txt -sha256sum -c checksums.txt --ignore-missing +go build -o agora . +./agora --help ``` -For Cosign signature verification and the SBOM workflow, see the **Security** section of [docs/install.md](docs/install.md). Vulnerability disclosures: see [SECURITY.md](SECURITY.md). +Requires the Go toolchain pinned in [go.mod](go.mod). For direct installer options and source install notes, see [docs/install.md](docs/install.md). -## First Run +## Quick Start ```bash agora login agora init my-nextjs-demo --template nextjs +agora project doctor --json ``` -## Docs +Command examples use `agora` for the installed CLI. Local source builds use `./agora` from the repo root. -- Human docs (GitHub Pages): [https://agoraio.github.io/cli/](https://agoraio.github.io/cli/) -- Agent-friendly Markdown mirror: [https://agoraio.github.io/cli/md/](https://agoraio.github.io/cli/md/) -- Release notes: [CHANGELOG.md](CHANGELOG.md) -- Install options (direct installer, Windows, source): [docs/install.md](docs/install.md) -- Full command reference (auto-generated): [docs/commands.md](docs/commands.md) -- Automation and JSON contract: [docs/automation.md](docs/automation.md) -- JSON envelope schema (machine-readable): [docs/schema/envelope.v1.json](docs/schema/envelope.v1.json) -- Stable error codes: [docs/error-codes.md](docs/error-codes.md) -- Telemetry controls: [docs/telemetry.md](docs/telemetry.md) -- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md) -- Security policy: [SECURITY.md](SECURITY.md) -- Support and contact channels: [SUPPORT.md](SUPPORT.md) -- Contributor and agent guide: [AGENTS.md](AGENTS.md), plus [CONTRIBUTING.md](CONTRIBUTING.md) +## What You Can Build Quickly -Command examples use `agora` for the installed CLI. Local source builds are covered in [Build From Source](#build-from-source). +| 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 token service | `agora init my-go-demo --template go` | A Go server quickstart with project metadata and env wiring | + +Run `agora quickstart list` to see all available templates. ## Command Model The command model is intentionally layered: -- `init` for the recommended onboarding path -- `quickstart` for standalone starter repos -- `project` for remote Agora resources and env export +- `init` for the recommended onboarding path (project + clone + env) +- `quickstart` for local cloned starter repos (requires `git`) +- `project` for remote Agora control-plane resources (does not clone scaffolds) - `auth` for login and session inspection - `config` for local CLI defaults - `telemetry` for telemetry preferences @@ -115,6 +95,29 @@ The command model is intentionally layered: - `mcp` to run the CLI as a local MCP server (`agora mcp serve`) for agent integrations - `completion` for shell completion scripts (auto-installed by the installer; see `agora completion --help` for manual setup) +### Which command? + +| Goal | Command | +|------|---------| +| New user, one shot | `agora init --template ` | +| 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]` | +| Write env to an arbitrary path / non-quickstart repo | `agora project env write ` | +| Install self-test | `agora doctor --json` | +| Project/workspace readiness | `agora project doctor --json` | + +### Env-related commands + +``` +agora init # recommended: project + clone + env +├── project +│ ├── env Print project env values (no file write) +│ └── env write Generic dotenv block (AGORA_* or NEXT_*) +└── quickstart + └── env write [dir] Template-specific env file and key names +``` + Discover the full command tree: ```bash @@ -133,6 +136,7 @@ Manages standalone official starter repos and their runtime-specific env files. Use this when you want to: +- list available templates with `quickstart list` - clone a quickstart without creating a project - bind a quickstart to an existing project - re-sync env files after changing project selection @@ -145,7 +149,8 @@ Use this when you want to: - create or inspect projects directly - switch the default project context -- export project env values +- export project env values with `project env` +- write credentials to a dotenv file with `project env write` - inspect project readiness with `project doctor` ### `auth` @@ -172,72 +177,30 @@ Runs the CLI as a local MCP server so MCP-capable clients can call Agora workflo Prints build metadata. Release binaries include version, commit, and build date. -## Common Workflows - -### Onboard a new demo - -```bash -agora login -agora init my-nextjs-demo --template nextjs -``` - -### Use an existing project with a quickstart - -```bash -agora quickstart create my-go-demo --template go --project my-existing-project -agora quickstart env write my-go-demo --project my-existing-project -``` - -### Update env after changing projects - -```bash -agora project use my-agent-demo -agora quickstart env write my-go-demo -``` - -### Inspect project readiness - -```bash -agora project doctor -agora project doctor --json -``` - -### Use low-level commands directly - -```bash -agora project create my-agent-demo --feature rtc --feature convoai -agora quickstart create my-go-demo --template go --project my-agent-demo -agora quickstart env write my-go-demo --project my-agent-demo -``` - -### Inspect the full command tree - -```bash -agora --help --all -``` +## Env Files and Project Binding -## Quickstart Env Conventions +`quickstart env write` and `project env write` both keep dotenv files limited to runtime credentials, but they target different workflows: -`quickstart env write` is different from `project env write`, but both keep dotenv files limited to runtime credentials. +| Command | Env path | Key names | +|---------|----------|-----------| +| `agora init` / `quickstart env write` | Template-defined (`.env.local`, `server/.env`, etc.) | Template-specific (`NEXT_PUBLIC_*`, `APP_ID`, …) | +| `agora project env write ` | User-supplied path | `AGORA_*` or `NEXT_*` only | -- `project env write` writes only App ID and App Certificate keys for the detected or `--template`-selected layout (for example `AGORA_*` for standard Node, `NEXT_PUBLIC_*` / `NEXT_*` for Next.js, or `APP_ID` / `APP_CERTIFICATE` for Python and Go). See [docs/automation.md](docs/automation.md) for the full matrix and JSON fields. -- `quickstart env write` understands the quickstart type and writes only the App ID and App Certificate variable names the cloned repo expects -- 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 +Quickstart template behavior: -Template-specific behavior: - -- Generic project env writes use `AGORA_APP_ID` plus `AGORA_APP_CERTIFICATE` -- Next.js quickstarts write `.env.local` and use `NEXT_PUBLIC_AGORA_APP_ID` plus `NEXT_AGORA_APP_CERTIFICATE` +- 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`, then use `APP_ID` plus `APP_CERTIFICATE` - Go quickstarts copy `server-go/env.example` to `server-go/.env`, then use `APP_ID` plus `APP_CERTIFICATE` -The CLI also writes repo-local project metadata to: +`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. It does not use `APP_ID` / `APP_CERTIFICATE`; use `quickstart env write` for Python and Go quickstart layouts. + +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. -- `.agora/project.json` +See [docs/automation.md](docs/automation.md) for JSON fields and the full credential matrix. -That allows the CLI to detect which Agora project a cloned demo is bound to even when you are working inside the repo later. +### Repo-local binding -## Repo-Local Project 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. Project resolution precedence is consistent across commands: @@ -274,20 +237,40 @@ agora quickstart env write /abs/path/to/my-go-demo --json agora quickstart env write /abs/path/to/my-go-demo --project my-other-project --json ``` -## Automation / Agent Usage +## Common Workflows + +### Use an existing project with a quickstart + +```bash +agora quickstart create my-go-demo --template go --project my-existing-project +agora quickstart env write my-go-demo --project my-existing-project +``` + +### Update env after changing projects + +```bash +agora project use my-agent-demo +agora quickstart env write my-go-demo +``` + +### Use low-level commands directly + +```bash +agora project create my-agent-demo --feature rtc --feature convoai +agora quickstart create my-go-demo --template go --project my-agent-demo +agora quickstart env write my-go-demo --project my-agent-demo +``` + +## Automation and Agents For scripts, CI, and agentic workflows: - prefer `--json` for machine consumption - set `AGORA_HOME` to an isolated temporary directory in CI or multi-agent runs -- prefer `init` for end-to-end setup -- use low-level commands when the workflow must be decomposed or resumed in stages -- use `agora --help --all` to inspect the full command tree -- use `quickstart env write` to re-sync env files after changing project selection -- use `project doctor --json` for readiness checks -- rely on the same JSON envelope for both success and failure +- prefer `init` for end-to-end setup; decompose with lower-level commands when a workflow must be resumed in stages +- use `agora introspect --json` and [AGENTS.md](AGENTS.md) for agent discovery; [docs/automation.md](docs/automation.md) for the JSON envelope contract -Examples: +Example: ```bash export AGORA_HOME="$(mktemp -d)" @@ -298,21 +281,7 @@ agora project doctor --json agora auth status --json ``` -The JSON envelope and stable result shapes are documented in [docs/automation.md](docs/automation.md). `auth status --json` exits `3` with `error.code` set to `AUTH_UNAUTHENTICATED` when no local session exists. - -## CI and Releases - -GitHub Actions are configured for: - -- push and pull request validation on Linux, macOS, and Windows -- automated tag-driven releases for `v*` tags -- cross-platform release artifacts for Linux, macOS, and Windows - -Release workflow behavior: - -- a pushed tag matching `v*` (for example `v0.2.5`) triggers the release workflow -- the workflow runs tests, builds release binaries, packages them, and publishes a GitHub release automatically -- release artifacts include checksums +`auth status --json` exits `3` with `error.code` set to `AUTH_UNAUTHENTICATED` when no local session exists. ## Configuration @@ -329,12 +298,12 @@ Built-in default config values are documented in [config.example.json](config.ex ## Troubleshooting -For a full troubleshooting guide with diagnostic commands, see [docs/troubleshooting.md](docs/troubleshooting.md). The fastest first step is always: +For a full troubleshooting guide with diagnostic commands, see [docs/troubleshooting.md](docs/troubleshooting.md). -```bash -agora doctor --json -agora project doctor --json -``` +Start with the right doctor command: + +- **`agora doctor --json`** — install self-test (PATH, version, network, auth, MCP host) +- **`agora project doctor --json`** — project and workspace readiness (credentials, `.agora` binding, env consistency; add `--deep` for repo-local checks) The most common issues: @@ -346,11 +315,18 @@ The most common issues: Full guide with debug logging, CI tips, completion troubleshooting, and the `--debug` flag: [docs/troubleshooting.md](docs/troubleshooting.md). -## Build From Source - -```bash -go build -o agora . -./agora --help -``` +## Documentation -Requires the Go toolchain pinned in [go.mod](go.mod). For direct installer options and source install notes, see [docs/install.md](docs/install.md). +- Human docs (GitHub Pages): [https://agoraio.github.io/cli/](https://agoraio.github.io/cli/) +- Agent-friendly Markdown mirror: [https://agoraio.github.io/cli/md/](https://agoraio.github.io/cli/md/) +- Release notes: [CHANGELOG.md](CHANGELOG.md) +- Install options (direct installer, Windows, source): [docs/install.md](docs/install.md) +- Full command reference (auto-generated): [docs/commands.md](docs/commands.md) +- Automation and JSON contract: [docs/automation.md](docs/automation.md) +- JSON envelope schema (machine-readable): [docs/schema/envelope.v1.json](docs/schema/envelope.v1.json) +- Stable error codes: [docs/error-codes.md](docs/error-codes.md) +- Telemetry controls: [docs/telemetry.md](docs/telemetry.md) +- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md) +- Security policy: [SECURITY.md](SECURITY.md) +- Support and contact channels: [SUPPORT.md](SUPPORT.md) +- Contributor and agent guide: [AGENTS.md](AGENTS.md), plus [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/RELEASING.md b/RELEASING.md index 42b5c7a..6db0567 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -35,7 +35,7 @@ The release workflow (`.github/workflows/release.yml`) then: ## Release notes -Before tagging, ensure [CHANGELOG.md](CHANGELOG.md) has the version section finalized, including any migration or upgrade notes. GoReleaser publishes auto-generated release notes from commits; paste highlights from the CHANGELOG section into the GitHub release description if you want a curated summary. +Before tagging, ensure [CHANGELOG.md](CHANGELOG.md) has the version section finalized (empty `[Unreleased]`, dated release heading, updated compare links), including any migration or upgrade notes. GoReleaser publishes auto-generated release notes from commits; paste highlights from the CHANGELOG section into the GitHub release description if you want a curated summary. ## Local Verification diff --git a/docs/automation.md b/docs/automation.md index 4488908..5e23ac2 100644 --- a/docs/automation.md +++ b/docs/automation.md @@ -214,6 +214,7 @@ Additional stage-specific fields may appear (for example `repoUrl`, `projectId`, | `clone:override` | `quickstart create`, `init` | Before `clone:start` when an `AGORA_QUICKSTART_