[DX-1143] Docs: add environment variables usage documentation

docs/Auto-completion.md

@@ -107,4 +107,12 @@ If you don't see any suggestions, verify that:
 
 - Auto-completion works with all Ably CLI commands and flags
 - The completion system is context-aware and will only suggest valid options
-- Custom aliases are not included in auto-completion
+- Custom aliases are not included in auto-completion
+- Hidden development flags (e.g., `--control-host`, `--dashboard-host`) are excluded from auto-completion unless `ABLY_SHOW_DEV_FLAGS=true` is set
+
+---
+
+## Related
+
+- [Interactive REPL](Interactive-REPL.md) — Interactive mode provides its own tab completion for commands and flags
+- [Troubleshooting](Troubleshooting.md) — General troubleshooting for CLI issues

docs/Debugging.md

@@ -55,4 +55,21 @@ Refer to [Testing.md](Testing.md) for how to run specific tests.
     ```bash
     DEBUG=oclif* bin/run.js [command]
     ```
+*   **Terminal Diagnostics:** Enable terminal state logging for TTY/stdin/stdout issues:
+    ```bash
+    TERMINAL_DIAGNOSTICS=1 ably-interactive
+    ```
 *   **Check Configuration:** Use `ably config show` to view stored credentials or `ably config path` to find the config file location.
+*   **Override Configuration:** Use environment variables to override config for testing:
+    ```bash
+    ABLY_API_KEY=your_key ably channels list
+    ```
+
+---
+
+## Related
+
+- [Development Stage](Environment-Variables/Development-Usage.md) Env Variables — Development, testing, debugging, and internal env variables. For user-facing variables, run `ably env`.
+- [Testing Guide](Testing.md) — Test layers, running tests, and debugging E2E failures
+- [E2E Testing CLI Runner](E2E-Testing-CLI-Runner.md) — E2E test runner debugging flags (`E2E_DEBUG`, `ABLY_CLI_TEST_SHOW_OUTPUT`)
+- [Troubleshooting](Troubleshooting.md) — Solutions for common build, test, and runtime issues

docs/E2E-Testing-CLI-Runner.md

@@ -164,7 +164,7 @@ const events = await waitForJsonEvents(
 
 When tests fail, the system automatically outputs:
 
-```
+```text
 === E2E TEST FAILURE DEBUG ===
 Test: should handle presence events
 Error: Timeout waiting for pattern "Action: enter"
@@ -237,4 +237,12 @@ await waitForOutput(subscriber, 'target event');
 - **Better CI reliability with proper process management**
 - **Clear separation of concerns with helper functions**
 
-The system automatically tracks CLI runners per test and provides comprehensive debugging output when tests fail, making it much easier to diagnose issues in CI environments. 
+The system automatically tracks CLI runners per test and provides comprehensive debugging output when tests fail, making it much easier to diagnose issues in CI environments.
+
+---
+
+## Related
+
+- [Testing Guide](Testing.md) — Test layers, auth in tests, duration defaults, and running tests
+- [Debugging Guide](Debugging.md) — General debugging tips including `DEBUG` env var and Node inspector
+- [Troubleshooting](Troubleshooting.md) — Solutions for common build and test errors (WebSocket mocking, HTTP mocking, memory leaks)

docs/Environment-Variables/Development-Usage.md

@@ -0,0 +1,28 @@
+# Environment Variables — Development Stage Usage
+
+These variables are for CLI contributors, development, testing, and internal modes. They are **not intended for end-user configuration** unless explicitly noted.
+
+> For user-facing environment variables (authentication, configuration, behavioral control, host overrides), run `ably env` in your terminal.
+
+---
+
+## Quick Reference
+
+| Variable | Category | Purpose | Default |
+| --- | --- | --- | --- |
+| `ABLY_SHOW_DEV_FLAGS` | Development | Reveal hidden dev flags | Not set |
+| `ABLY_CONTROL_HOST` | Host Override | Override Control API host | `control.ably.net` |
+| `ABLY_DASHBOARD_HOST` | Host Override | Override Ably dashboard URL | `https://ably.com` |
+| `DEBUG` | Debugging | oclif framework debug output | Not set |
+| `TERMINAL_DIAGNOSTICS` | Debugging | Terminal state diagnostics | Not set |
+| `ABLY_CLI_TEST_MODE` | Testing | Enable test mode | Not set |
+| `SKIP_CONFIRMATION` | Testing | Auto-confirm prompts (test alias for `ABLY_CLI_NON_INTERACTIVE`) | Not set |
+| `GENERATING_DOC` | Tooling | Doc generation mode | Not set |
+| `CI` | Environment | CI detection | Not set |
+| `ABLY_INTERACTIVE_MODE` | Internal | Interactive shell mode flag | Not set |
+| `ABLY_WRAPPER_MODE` | Internal | Wrapper script detection | Not set |
+| `ABLY_SUPPRESS_WELCOME` | Internal | Suppress welcome logo | Not set |
+| `ABLY_WEB_CLI_MODE` | Internal | Web browser CLI mode | Not set |
+| `ABLY_ANONYMOUS_USER_MODE` | Internal | Anonymous web CLI mode | Not set |
+| `ABLY_CURRENT_COMMAND` | Internal | Current command tracking | Set automatically |
+| `NODE_ENV` | Internal | Node environment override | Not set |

docs/Environment-Variables/General-Usage.md

@@ -0,0 +1,23 @@
+# Environment Variables — General Usage
+
+These environment variables are most commonly used during development as well as by end users in CI/CD pipelines, scripts, and production use.
+
+> **Note:** The CLI does not automatically load `.env` files. Set environment variables in your shell, CI/CD configuration, or inline with your commands.
+
+---
+
+## Quick Reference
+
+| Variable | Category | Purpose | Default |
+| --- | --- | --- | --- |
+| `ABLY_API_KEY` | Authentication | API key for data plane commands | None |
+| `ABLY_TOKEN` | Authentication | Token/JWT for data plane commands | None |
+| `ABLY_ACCESS_TOKEN` | Authentication | Access token for Control API commands | None |
+| `ABLY_APP_ID` | App Selection | Default app for `--app` flag | None |
+| `ABLY_CLI_CONFIG_DIR` | Configuration | Custom config directory | `~/.ably` |
+| `ABLY_HISTORY_FILE` | Configuration | Custom history file location | `~/.ably/history` |
+| `ABLY_CLI_DEFAULT_DURATION` | Behavior | Auto-exit long-running commands (seconds) | None (forever) |
+| `ABLY_CLI_NON_INTERACTIVE` | Behavior | Auto-confirm "Did you mean?" prompts | Not set |
+| `ABLY_ENDPOINT` | Host Override | Override Realtime/REST API endpoint | SDK default |
+
+> For development, testing, debugging, and internal variables, see [Development Stage Usage](Development-Usage.md).

docs/Exit-Codes.md

@@ -54,4 +54,11 @@ The `bin/ably-interactive` wrapper script uses these exit codes to determine whe
 Exit codes are handled in:
 - `src/commands/interactive.ts`: Sets exit code 42 for user exit
 - `src/utils/sigint-exit.ts`: Handles SIGINT behavior and exit code 130
-- `bin/ably-interactive`: Wrapper script that interprets exit codes
+- `bin/ably-interactive`: Wrapper script that interprets exit codes
+
+---
+
+## Related
+
+- [Interactive-REPL.md](Interactive-REPL.md) — Architecture and wrapper script design
+- [Troubleshooting.md](Troubleshooting.md#interactive-mode-issues) — Common interactive mode issues

docs/Interactive-REPL.md

@@ -29,7 +29,7 @@ There are some relevant Node.js projects we can draw inspiration from:
 [oclif](https://oclif.io/) does not appear to have any plugins to support an interactive/embedded CLI mode.
 However, a [REPL plugin](https://github.com/sisou/oclif-plugin-repl) exists, although that's unlikely to share much with the goals of interactive CLI.
 
-If there are any existing libraries that we can depend on to enable this functionality, taht that should be our preference to keep the CLI complexity low. However, any dependencies used should be well maintained and popular. If the additional dependencies to support this functionality add any material bloat, we should consider how this functionality can be added as an optional plugin so that the standard locally installed CLI has minimal dependencies.
+If there are any existing libraries that we can depend on to enable this functionality, that should be our preference to keep the CLI complexity low. However, any dependencies used should be well maintained and popular. If the additional dependencies to support this functionality add any material bloat, we should consider how this functionality can be added as an optional plugin so that the standard locally installed CLI has minimal dependencies.
 
 ## Execution Plan
 
@@ -43,7 +43,7 @@ The chosen approach runs commands inline (no spawning/forking) with a bash wrapp
 
 - **Inline execution**: Commands run in the same process, eliminating spawn overhead
 - **Natural Ctrl+C**: Interrupting commands exits the process, wrapper restarts seamlessly
-- **Persistent history**: Command history saved to `~/.ably/history` across restarts
+- **Persistent history**: Command history saved to `~/.ably/history` across restarts (configurable via `ABLY_HISTORY_FILE`)
 - **Special exit handling**: Typing 'exit' uses exit code 42 to signal wrapper to terminate (see [Exit Codes documentation](Exit-Codes.md) for details)
 
 **Expected Performance**:
@@ -409,3 +409,13 @@ private getAvailableCommands(): string[] {
 5. **Reliability**: Leverages OS-level process management
 
 This plan delivers a responsive interactive shell with natural Ctrl+C handling and seamless user experience through the bash wrapper approach.
+
+---
+
+## Related
+
+- [Exit Codes](Exit-Codes.md) — Exit codes used in interactive mode and wrapper script behavior
+- [Troubleshooting](Troubleshooting.md#interactive-mode-issues) — Common interactive mode issues (unexpected exits, Ctrl+C, history)
+- [Auto-completion](Auto-completion.md) — Shell tab completion setup for commands and flags
+- [Testing Guide](Testing.md) — Subprocess and TTY test layers for interactive mode
+- [Project Structure](Project-Structure.md) — Repository layout including `src/commands/interactive.ts` and `bin/ably-interactive`

docs/Project-Structure.md

@@ -167,3 +167,13 @@ This document outlines the directory structure of the Ably CLI project.
 ├── LICENSE
 └── README.md
 ```
+
+---
+
+## Related
+
+- [Development Stage](Environment-Variables/Development-Usage.md) Env Variables — Development, testing, debugging, and internal env variables. For user-facing variables, run `ably env`.
+- [Testing Guide](Testing.md) — Test layers and directory layout (`test/unit/`, `test/e2e/`, `test/tty/`, `test/integration/`)
+- [Debugging Guide](Debugging.md) — Debugging tips for CLI development
+- [Interactive REPL](Interactive-REPL.md) — Architecture of `src/commands/interactive.ts` and `bin/ably-interactive`
+- [Exit Codes](Exit-Codes.md) — Exit codes handled in `src/commands/interactive.ts` and `src/utils/sigint-exit.ts`

docs/Testing.md

@@ -68,7 +68,7 @@ Unit tests for commands with `--json` support should test all three output modes
 
 ## Choosing the right layer
 
-```
+```text
 What are you testing?
 │
 ├─ Flag parsing, help output, error messages, output format?
@@ -99,7 +99,7 @@ Explicit rules:
 |---------|-------------|
 | `pnpm test:unit` | All unit tests |
 | `pnpm test:integration` | Subprocess/interactive tests |
-| `pnpm test:e2e` | E2E tests (needs `ABLY_API_KEY` etc.) |
+| `pnpm test:e2e` | E2E tests (needs `E2E_ABLY_API_KEY` etc.) |
 | `pnpm test:tty` | TTY tests (local only, needs real terminal) |
 | `pnpm test` | Unit + integration + E2E |
 | `pnpm test test/unit/commands/foo.test.ts` | Specific test file |
@@ -114,6 +114,8 @@ Set `E2E_DEBUG=true` and/or `ABLY_CLI_TEST_SHOW_OUTPUT=true` for verbose output:
 E2E_DEBUG=true ABLY_CLI_TEST_SHOW_OUTPUT=true pnpm test:e2e
 ```
 
+See [E2E-Testing-CLI-Runner.md](E2E-Testing-CLI-Runner.md) for the full E2E debugging guide.
+
 ---
 
 ## Test structure
@@ -134,6 +136,8 @@ Exempt: `interactive.test.ts`, `interactive-sigint.test.ts`, `bench/*.test.ts`.
 
 ### Auth in tests
 
+Authentication in tests uses different mechanisms depending on the layer. Run `ably env` for the full reference on `ABLY_API_KEY`, `ABLY_TOKEN`, `ABLY_ACCESS_TOKEN`, and other auth env vars.
+
 **Unit tests** — `MockConfigManager` provides auth automatically. No env vars or flags needed:
 
 ```typescript
@@ -159,7 +163,7 @@ runCommand(["channels", "publish", "my-channel", "hello"], {
 
 ### Duration in tests
 
-Unit and integration tests set `ABLY_CLI_DEFAULT_DURATION: "0.25"` in `vitest.config.ts`, so subscribe/long-running commands auto-exit after 250ms. Do NOT pass `--duration` to `runCommand()` — it overrides the fast default.
+Unit and integration tests set `ABLY_CLI_DEFAULT_DURATION: "0.25"` in `vitest.config.ts`, so subscribe/long-running commands auto-exit after 250ms. Do NOT pass `--duration` to `runCommand()` — it overrides the fast default. Run `ably env ABLY_CLI_DEFAULT_DURATION` for full details on this variable and the 28 commands it affects.
 
 Exceptions: `test:wait` command tests (required flag), `interactive-sigint.test.ts` (needs longer for SIGINT), and help output checks.
 
@@ -247,3 +251,11 @@ Each accepts an optional `Partial<T>` to override fields:
 | `killTty()` | Kill the PTY process (async) |
 | `PROMPT_PATTERN` | `"ably>"` |
 | `DEFAULT_WAIT_TIMEOUT` | 8000ms |
+
+---
+
+## Related
+
+- [Debugging Guide](Debugging.md) — Debugging tips for CLI development, including `DEBUG` and Node inspector
+- [E2E Testing CLI Runner](E2E-Testing-CLI-Runner.md) — E2E test runner system, debugging flags, and process management
+- [Troubleshooting](Troubleshooting.md) — Solutions for common build and test errors

docs/Troubleshooting.md

@@ -11,7 +11,7 @@ This document provides solutions for common issues encountered when developing o
 **Problem**: Tests failing with errors about modules not being found or incorrect paths.
 
 **Example Error**:
-```
+```text
 Error: Cannot find module '../commands/publish'
 ```
 
@@ -37,7 +37,7 @@ import MyCommand from '../../src/commands/my-command.js'
 **Problem**: Tests fail with memory errors or hang indefinitely.
 
 **Example Error**:
-```
+```text
 FATAL ERROR: JavaScript heap out of memory
 ```
 
@@ -68,7 +68,7 @@ afterEach(async () => {
 **Problem**: Tests involving WebSocket connections fail or hang.
 
 **Example Error**:
-```
+```text
 Timeout of 2000ms exceeded
 ```
 
@@ -106,7 +106,7 @@ afterEach(() => {
 **Problem**: Tests involving HTTP requests fail with network errors.
 
 **Example Error**:
-```
+```text
 Error: connect ECONNREFUSED
 ```
 
@@ -166,6 +166,10 @@ afterEach(() => {
   ```bash
   ABLY_API_KEY=your_key ably channels list
   ```
+- Override the config directory entirely:
+  ```bash
+  ABLY_CLI_CONFIG_DIR=/path/to/custom/config ably accounts login
+  ```
 
 ---
 
@@ -190,7 +194,7 @@ afterEach(() => {
 **Problem**: TypeScript compilation errors.
 
 **Example Error**:
-```
+```text
 Property 'x' does not exist on type 'Y'
 ```
 
@@ -220,10 +224,10 @@ Property 'x' does not exist on type 'Y'
 **Problem**: The interactive mode exits with unexpected error codes.
 
 **Solution**:
-- Check the exit code to understand what happened (see [Exit Codes documentation](Exit-Codes.md))
+- Check the exit code to understand what happened (see [Exit Codes documentation](Exit-Codes.md) and [Development Stage Env Variables](Environment-Variables/Development-Usage.md) for interactive mode env vars)
 - Common exit codes:
-  - Exit code 0: Normal exit (usually from 'exit' command)
-  - Exit code 42: User typed 'exit' (special code for wrapper)
+  - Exit code 0: Wrapper (`ably-interactive`) terminated normally
+  - Exit code 42: User typed 'exit' in interactive mode (signals wrapper to terminate)
   - Exit code 130: SIGINT/Ctrl+C (double Ctrl+C or force quit)
   - Exit code 143: SIGTERM received
 
@@ -243,8 +247,8 @@ Property 'x' does not exist on type 'Y'
 
 **Solution**:
 - Check that `~/.ably/history` file exists and is writable
-- Verify the `ABLY_HISTORY_FILE` environment variable if using custom location
-- Ensure the history file isn't exceeding size limits (default: 1000 commands)
+- Verify the `ABLY_HISTORY_FILE` environment variable if using custom location (run `ably env ABLY_HISTORY_FILE` for details)
+- Ensure the history file isn't exceeding size limits (default: 1000 commands, auto-trimmed at 2000 lines)
 
 ---
 
@@ -253,3 +257,14 @@ Property 'x' does not exist on type 'Y'
 If you find errors in documentation or rules, please update them using the proper workflow and submit a pull request.
 
 See `AGENTS.md` for more details on the development workflow.
+
+---
+
+## Related
+
+- [Development Stage](Environment-Variables/Development-Usage.md) Env Variables — Development, testing, debugging, and internal env variables. For user-facing variables, run `ably env`.
+- [Debugging Guide](Debugging.md) — Debugging tips including `DEBUG`, `TERMINAL_DIAGNOSTICS`, and Node inspector
+- [Testing Guide](Testing.md) — Test layers, running tests, and debugging failures
+- [Exit Codes](Exit-Codes.md) — Exit codes used by the CLI, particularly in interactive mode
+- [Interactive REPL](Interactive-REPL.md) — Interactive mode architecture and wrapper script design
+- [Auto-completion](Auto-completion.md) — Shell tab completion setup and troubleshooting

src/base-command.ts

@@ -63,6 +63,11 @@ export const WEB_CLI_RESTRICTED_COMMANDS = [
   // config only applicable to local env
   "config*",
 
+  // env documents local-CLI environment variables (auth, config dirs, history
+  // files) that don't apply in web CLI mode where auth and config are managed
+  // by the surrounding web UI
+  "env",
+
   // File-reading commands can expose server filesystem contents in web CLI mode
   "push:config:set-apns",
   "push:config:set-fcm",