[DX-1143] Docs: add environment variables usage documentation#373
[DX-1143] Docs: add environment variables usage documentation#373umair-ably merged 13 commits intomainfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
sacOO7
changed the title
There was a problem hiding this comment.
Pull request overview
Adds a centralized documentation reference for all Ably CLI environment variables and improves discoverability by cross-linking related docs across the contributor documentation set.
Changes:
- Introduces
docs/ENV_VARIABLES_USAGE.mdas a comprehensive reference for CLI environment variables (auth, config, behavior, dev/test/internal modes). - Adds “Related” cross-link sections to multiple existing docs to make the env var reference and adjacent guides easier to find.
- Applies small doc corrections (e.g., code fence language tags, typo fix, and E2E env var naming in Testing docs).
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/ENV_VARIABLES_USAGE.md | New comprehensive env var reference and cross-links (some auth precedence/details need correction per review comments). |
| docs/Troubleshooting.md | Adds text code fences, clarifies interactive exit/history behavior, and adds related links. |
| docs/Testing.md | Fixes E2E env var naming, adds env var cross-links, and adds a “Related” section. |
| docs/Project-Structure.md | Adds “Related” cross-links (including env var reference). |
| docs/Interactive-REPL.md | Fixes typo, clarifies history env var, adds “Related” section. |
| docs/Exit-Codes.md | Adds “Related” section and minor formatting tweak. |
| docs/E2E-Testing-CLI-Runner.md | Adds text code fences, whitespace cleanup, and “Related” links. |
| docs/Debugging.md | Adds terminal diagnostics example, config override example, and “Related” links. |
| docs/Auto-completion.md | Notes ABLY_SHOW_DEV_FLAGS impact and adds “Related” links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
sacOO7
changed the title
![claude-code-ably-assistant[bot]](https://avatars.githubusercontent.com/in/2109912?s=60&v=4){kind=small}
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
sacOO7
changed the title
sacOO7
force-pushed
the
feature/update-env-variables-usage-docs
branch
from
5330228 to
244b63e
Compare
|
@claude review |
There was a problem hiding this comment.
Review: Documentation-only PR — Factual Accuracy Check
This PR adds a comprehensive env var reference doc and cross-links it from 8 existing docs. The structure and content are solid overall. I found three factual errors worth fixing before merge.
Issue 1 — stats commands misplaced in the Data Plane table (significant)
File: docs/ENV_VARIABLES_USAGE.md, "Commands by Auth Type" → Data Plane section
The table lists stats | (all) under Data Plane (ABLY_API_KEY / ABLY_TOKEN), but stats commands extend ControlBaseCommand and call the Control API. They need ABLY_ACCESS_TOKEN, not ABLY_API_KEY.
// src/stats-base-command.ts
export abstract class StatsBaseCommand extends ControlBaseCommand {
A user who reads this doc and tries ABLY_API_KEY="..." ably stats app will get an unexpected auth failure, since they needed ABLY_ACCESS_TOKEN instead.
Fix: Move stats | app, account to the Control API table.
Issue 2 — connections: list doesn't exist (significant)
File: docs/ENV_VARIABLES_USAGE.md, Data Plane table
The table shows connections | list, but there is no connections list command. The actual subcommand is connections test.
src/commands/connections/
index.ts (topic command, not leaf)
test.ts ← the only real leaf command
Fix: Change list → test.
Issue 3 — Source file table: ABLY_APP_ID row has wrong count and missing files (minor)
File: docs/ENV_VARIABLES_USAGE.md, "Source Code Reference" table
The row reads:
src/commands/auth/*.ts(12 files) →ABLY_APP_ID
The actual count of auth files using ABLY_APP_ID is 10, and the variable is also used in two non-auth files that aren't listed:
src/commands/channels/inspect.tssrc/commands/apps/delete.ts
(Total 12 files, but not all in auth/.)
Fix: Correct the row to reflect the actual file set, or simplify to a pattern that covers all 12.
There was a problem hiding this comment.
Review complete. Three factual errors in ENV_VARIABLES_USAGE.md: (1) stats commands are in the wrong table — they use the Control API, not data plane; (2) connections: list doesn't exist, the subcommand is connections test; (3) the source file table counts 12 auth files for ABLY_APP_ID but only 10 are in auth/ — the other two are in channels/ and apps/. Everything else checked out: auth resolution order, ABLY_TOKEN banner suppression note, env var count (25), and the cross-links in other docs are all accurate.
There was a problem hiding this comment.
Pull request overview
Adds a comprehensive environment-variable reference for the Ably CLI and cross-links it from other contributor docs to improve discoverability and reduce “tribal knowledge” around auth/config/test/debug behavior.
Changes:
- Added
docs/ENV_VARIABLES_USAGE.mdas a central reference for all CLI env vars (plus test-runner env vars). - Updated multiple existing docs with “Related” sections linking to the new reference and to each other.
- Made small doc fixes (code-fence language tags, a typo fix, clarified exit code/history trimming notes, and corrected E2E API key naming in Testing docs).
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/Troubleshooting.md | Adds env-var guidance (ABLY_CLI_CONFIG_DIR, history trimming note) and cross-links to the new env-var reference. |
| docs/Testing.md | Clarifies E2E credential env var name (E2E_ABLY_API_KEY) and adds cross-links to env-var reference + E2E runner docs. |
| docs/Project-Structure.md | Adds “Related” links to env-var reference and other key contributor docs. |
| docs/Interactive-REPL.md | Fixes typo and documents ABLY_HISTORY_FILE; adds related links to env-var reference. |
| docs/Exit-Codes.md | Adds “Related” links to env-var reference and interactive mode docs. |
| docs/ENV_VARIABLES_USAGE.md | Introduces the new comprehensive env-var reference (auth/config/behavior/dev/testing/internal). |
| docs/E2E-Testing-CLI-Runner.md | Adds “Related” section linking into env-var reference and other contributor docs. |
| docs/Debugging.md | Adds TERMINAL_DIAGNOSTICS mention and related links to env-var reference. |
| docs/Auto-completion.md | Notes ABLY_SHOW_DEV_FLAGS impact and adds related links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
sacOO7
force-pushed
the
feature/update-env-variables-usage-docs
branch
from
244b63e to
35d4a82
Compare
|
@claude review |
There was a problem hiding this comment.
Pull request overview
Adds a dedicated reference doc for all environment variables used by ably-cli and improves documentation discoverability by cross-linking relevant docs to that reference.
Changes:
- Added
docs/ENV_VARIABLES_USAGE.md, documenting all CLI env vars (auth/config/behavior/dev/internal) plus source-code cross references. - Updated multiple existing docs to add “Related” sections linking back to the env-var reference (and other key docs).
- Misc doc fixes: code fence language tags, a typo fix, and some clarifications around testing/auth and interactive history/exit codes.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/ENV_VARIABLES_USAGE.md | New comprehensive env-var reference, including precedence, behavior notes, and source-code mapping table. |
| docs/Troubleshooting.md | Adds env-var pointers and clarifies interactive/history troubleshooting; adds Related links. |
| docs/Testing.md | Corrects E2E credential var naming, adds env-var pointers, and adds Related links. |
| docs/Project-Structure.md | Adds Related links to help navigate to env-var reference and other docs. |
| docs/Interactive-REPL.md | Fixes typo, clarifies history env var, and adds Related links. |
| docs/Exit-Codes.md | Adds Related links for env vars impacting interactive mode. |
| docs/E2E-Testing-CLI-Runner.md | Improves code block tagging, trims whitespace, and adds Related links with env-var notes. |
| docs/Debugging.md | Adds terminal diagnostics + config override examples and Related links. |
| docs/Auto-completion.md | Adds note about ABLY_SHOW_DEV_FLAGS and Related links. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
sacOO7
force-pushed
the
feature/update-env-variables-usage-docs
branch
from
35d4a82 to
0061a7b
Compare
sacOO7
force-pushed
the
feature/update-env-variables-usage-docs
branch
from
0061a7b to
87b921c
Compare
|
|
||
| > For development, testing, debugging, and internal variables, see [Development Stage Usage](Development-Usage.md). | ||
|
|
||
| --- |
There was a problem hiding this comment.
Everything below this line can be deleted with your newest changes imo
| | [`ABLY_CURRENT_COMMAND`](#ably_current_command) | Internal | Current command tracking | Set automatically | | ||
| | [`NODE_ENV`](#node_env) | Internal | Node environment override | Not set | | ||
|
|
||
| --- |
There was a problem hiding this comment.
I think everything below this line can also go...
The quick reference above already makes it very clear what each one does + they're only internal dev flags. Also, way less to maintain
sacOO7
dismissed
claude-code-ably-assistant[bot]’s stale review
Outdated review, all comments are well addressed
…k all docs Add ENV_VARIABLES_USAGE.md documenting all 25 environment variables with usage examples, auth resolution order, CI/CD patterns, and source code cross-references. Update existing docs with Related sections for better discoverability. Fix minor typos and add fenced code block language tags.
…o avoid bloating in a single page, updated references across other docs
…env` and `ably env --help` commands
…info Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
umair-ably
force-pushed
the
feature/update-env-variables-usage-docs
branch
from
7b69e49 to
00cd1aa
Compare
| new DetailSection("Client ID", [ | ||
| { | ||
| kind: "paragraph", | ||
| text: "`--client-id` is ignored when `ABLY_TOKEN` is set — the client ID is embedded in the token. A warning is logged if `--client-id` is passed.", |
There was a problem hiding this comment.
Do we want to delete
--client-id` is ignored when `ABLY_TOKEN` is set — the client ID is embedded in the token. A warning is logged if `--client-id` is passed.` ?
There was a problem hiding this comment.
ahh one sec.. some of these changes should not be in here
| new DetailSection("Login bypass", [ | ||
| { | ||
| kind: "paragraph", | ||
| text: "Bypasses the `ably login` workflow and skips interactive app/key selection. Useful in scripts and CI/CD pipelines.", |
There was a problem hiding this comment.
Previous review comment at https://ably-real-time.slack.com/archives/D06FYTN91U5/p1777574075208169 mentioned to move login bypass per command help page. Do we intentionally want to remove it?
…sential info" This reverts commit 00cd1aa. The trim removed detailed sections that should be kept (e.g. client ID behavior for ABLY_API_KEY/ABLY_TOKEN, login bypass notes, scope details for ABLY_CLI_NON_INTERACTIVE, and per-variable property tables/examples in the docs). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…l sections Re-applies the trim of docs (Development-Usage, General-Usage, Troubleshooting), src/commands/env.ts, env-vars.ts cosmetic changes, and test updates from 00cd1aa, but keeps the per-variable DetailSection blocks in src/data/env-vars.ts (Login bypass, Client ID, Token expiry, Scope) so the focused single-variable view still surfaces the substantive guidance. Tests that asserted on the trimmed-only details shape were updated to match the restored content (length checks bumped to actual counts; the ABLY_TOKEN issue-token assertion now relies on the substring check alone; renderSingleVar line cap raised from 20 to 30). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The minimal `ably env` view no longer renders the Prerequisites or Examples headings — it shows the per-variable summary table prefixed with `ably env <NAME>` and the `ably env --help` footer instead. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
ably envcommand and docs covering usage for all env. variables in the ably-cli source code.ably envcommand that surfaces the environment variables supported by the CLIdirectly in the terminal.
doesn't apply when auth is managed by the surrounding web UI.
Examples
Summary
docs/ENV_VARIABLES_USAGE.md— a comprehensive reference for all 25 environment variables used by the CLI,organized into General Usage (auth, config, behavior, host overrides) and Development Stage Usage (debugging,
testing, tooling, internal vars)
Project-Structure, Testing, Troubleshooting) with "Related" cross-link sections for improved discoverability
textlanguage tags to fenced code blocks,correct
ABLY_API_KEY→E2E_ABLY_API_KEYin Testing.md, clarify exit code descriptions and history trimmingbehavior
Highlights
contributors)