From 10b63cec95843351ab77144bbe3537dd49a338c6 Mon Sep 17 00:00:00 2001 From: sunshinexcode <24xinhui@163.com> Date: Thu, 6 Aug 2026 17:31:15 +0800 Subject: [PATCH 1/2] docs(env): document Quickstart env file handling --- README.md | 2 ++ docs/env-local.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++ docs/llms.txt | 2 ++ 3 files changed, 75 insertions(+) create mode 100644 docs/env-local.md diff --git a/README.md b/README.md index 871515b..76ba1ce 100644 --- a/README.md +++ b/README.md @@ -216,6 +216,8 @@ Quickstart template behavior: 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 diff --git a/docs/env-local.md b/docs/env-local.md new file mode 100644 index 0000000..bf53e8f --- /dev/null +++ b/docs/env-local.md @@ -0,0 +1,71 @@ +--- +title: Using .env.local +--- + +# Using `.env.local` + +For official Next.js, Python, and Go Quickstarts, Agora CLI creates or updates +the runtime-specific env file with the Agora App ID and App Certificate for the +selected project. It does not download a ready-made dotenv file from Console. +The CLI starts with the example env file from the cloned repository, then +writes the credential keys required by that runtime. + +## How the file is created + +| Command | Behavior | +|---------|----------| +| `agora init --template ` | Clones the Quickstart, selects or creates a project, and writes its env file. | +| `agora quickstart create ...` | Writes the env file when a project is resolved; without a project, it clones the template only. | +| `agora quickstart env write [dir]` | Creates or updates the runtime-specific env file in an existing Quickstart. | +| `agora project env write [path]` | Creates or updates a dotenv file at the selected path without cloning a Quickstart. | + +Quickstart env layouts: + +| Quickstart | Example source | Target path | Credential keys | +|------------|----------------|-------------|-----------------| +| Next.js | `env.local.example` | `.env.local` | `NEXT_PUBLIC_AGORA_APP_ID`, `NEXT_AGORA_APP_CERTIFICATE` | +| Python | `server/.env.example` | `server/.env.local` | `AGORA_APP_ID`, `AGORA_APP_CERTIFICATE` | +| Go | `server/.env.example` | `server/.env.local` | `AGORA_APP_ID`, `AGORA_APP_CERTIFICATE` | + +If the target env file already exists, the CLI uses it as the starting content +and updates the Agora credential keys while preserving unrelated entries. If +the target does not exist, the CLI starts from the Quickstart's example file. +If neither file exists, it creates a new file containing the credential entries. + +To refresh credentials or switch the Quickstart to another project, run the env +write command again with the target project. The CLI updates the same env file +in place: + +```bash +cd +agora quickstart env write . --project +``` + +Prefer `agora quickstart env write` for official Quickstarts. Use +`agora project env write ` when you want to write credentials to a +specific dotenv path outside the official Quickstart layout. + +## Where the credentials come from + +After authentication, the CLI fetches the selected project's details from the +Agora CLI project API. The App ID and App Certificate returned for that project +are written to the local env file. + +Project selection follows this precedence: + +1. Explicit `--project ` +2. Repo-local `.agora/project.json` +3. Global project context set by `agora project use` + +The selected project must have an App Certificate. If it does not, enable one +in Agora Console or select a different project before writing the env file. + +Restart the development server after updating the env file so it reloads the +new values. + +## Keep credentials private + +The env file can contain an App Certificate. Do not commit it to version +control, paste its values into issues or logs, or share it outside the intended +development environment. Confirm that the file is covered by the repository's +`.gitignore` rules. diff --git a/docs/llms.txt b/docs/llms.txt index fd44624..65158cb 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -19,6 +19,7 @@ Check project health: agora project doctor --json - Command reference: /cli/commands.html - Automation (JSON contract): /cli/automation.html - Error codes: /cli/error-codes.html +- Environment files: /cli/env-local.html - Telemetry controls: /cli/telemetry.html ### Agent-Friendly Markdown @@ -26,6 +27,7 @@ Check project health: agora project doctor --json - Commands: /cli/md/commands.md - Automation: /cli/md/automation.md - Error codes: /cli/md/error-codes.md +- Environment files: /cli/md/env-local.md - Install guide: /cli/md/install.md - Telemetry: /cli/md/telemetry.md - Agent rules: /cli/md/agents/README.md From ecb9e2ccc27e14721e59584d38ce59d9a532b92f Mon Sep 17 00:00:00 2001 From: sunshinexcode <24xinhui@163.com> Date: Thu, 6 Aug 2026 21:01:44 +0800 Subject: [PATCH 2/2] docs(env): add documentation for Quickstart env file creation and update sitemap --- CHANGELOG.md | 4 ++++ docs/sitemap.xml | 10 ++++++++++ 2 files changed, 14 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e22c4e5..bff4fde 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,10 @@ Earlier entries pre-date this convention and only carry their version's compare ## [Unreleased] +### 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`. + ## [0.2.8] - 2026-07-28 Region-aware authentication, OAuth UX, quickstart compatibility, and installer and documentation delivery improvements. diff --git a/docs/sitemap.xml b/docs/sitemap.xml index 30b1d84..430c162 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -29,6 +29,11 @@ layout: none monthly 0.8 + + {{ site.url }}{{ site.baseurl }}/env-local.html + monthly + 0.7 + {{ site.url }}{{ site.baseurl }}/telemetry.html monthly @@ -60,6 +65,11 @@ layout: none monthly 0.8 + + {{ site.url }}{{ site.baseurl }}/md/env-local.md + monthly + 0.7 + {{ site.url }}{{ site.baseurl }}/md/install.md monthly