diff --git a/CLAUDE.md b/CLAUDE.md
index 2f19893ccc..c955af1967 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -297,6 +297,10 @@ See `writing-style-guide.md` for full details. Key points:
 - Avoid em-dashes, Latin abbreviations (use "for example" not "e.g."), and slang
 - Avoid bold prefixes in bullet points
 
+## CLI reference docs (`src/pages/docs/cli/`)
+
+CLI command pages use **kebab-case** for argument and flag placeholders (for example `<channel-name>`, `[lock-id]`, `--client-id`), even when the upstream oclif autogenerated reference uses `SNAKE_CASE`/uppercase (for example `CHANNEL_NAME`). This case difference is the deliberate doc convention — do not "fix" pages to match oclif casing.
+
 ## Testing
 
 Tests use Jest with React Testing Library. Test files are colocated with source files as `*.test.tsx` or `*.test.ts`.
diff --git a/src/pages/docs/cli/apps/current.mdx b/src/pages/docs/cli/apps/current.mdx
index 2501816cad..490b6bf476 100644
--- a/src/pages/docs/cli/apps/current.mdx
+++ b/src/pages/docs/cli/apps/current.mdx
@@ -10,7 +10,7 @@ Use the `ably apps current` command to display information about the currently s
 
 <Code>
 ```shell
-ably apps current
+ably apps current [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/apps/delete.mdx b/src/pages/docs/cli/apps/delete.mdx
index 15db935a4a..88609dcd66 100644
--- a/src/pages/docs/cli/apps/delete.mdx
+++ b/src/pages/docs/cli/apps/delete.mdx
@@ -14,7 +14,7 @@ ably apps delete [app-id] [options]
 ```
 </Code>
 
-<Aside data-type="important">
+<Aside data-type='important'>
 Deleting an application is irreversible. All data associated with the application, including API keys, channels, and message history, will be permanently removed.
 </Aside>
 
diff --git a/src/pages/docs/cli/apps/rules/update.mdx b/src/pages/docs/cli/apps/rules/update.mdx
index 798f9453a7..8bd968ca49 100644
--- a/src/pages/docs/cli/apps/rules/update.mdx
+++ b/src/pages/docs/cli/apps/rules/update.mdx
@@ -22,7 +22,7 @@ The name or ID of the channel rule to update.
 
 ## Options
 
-<Aside data-type="note">
+<Aside data-type='note'>
 Boolean options support a `--no-` prefix to disable the option. For example, use `--no-persisted` to disable message persistence.
 </Aside>
 
diff --git a/src/pages/docs/cli/apps/update.mdx b/src/pages/docs/cli/apps/update.mdx
index b67d855f29..2220958145 100644
--- a/src/pages/docs/cli/apps/update.mdx
+++ b/src/pages/docs/cli/apps/update.mdx
@@ -22,7 +22,7 @@ The app name or ID to update.
 
 ## Options
 
-<Aside data-type="note">
+<Aside data-type='note'>
 Boolean options support a `--no-` prefix to disable the option. For example, use `--no-tls-only` to allow non-TLS connections.
 </Aside>
 
diff --git a/src/pages/docs/cli/auth/revoke-token.mdx b/src/pages/docs/cli/auth/revoke-token.mdx
index e5515cb2fc..02b65d74ed 100644
--- a/src/pages/docs/cli/auth/revoke-token.mdx
+++ b/src/pages/docs/cli/auth/revoke-token.mdx
@@ -14,7 +14,7 @@ ably auth revoke-token [options]
 ```
 </Code>
 
-<Aside data-type="important">
+<Aside data-type='important'>
 Token revocation is irreversible. All tokens matching the supplied target are revoked, and any clients using those tokens will need to obtain new ones.
 </Aside>
 
diff --git a/src/pages/docs/cli/autocomplete.mdx b/src/pages/docs/cli/autocomplete.mdx
index 45aa860e4a..b9d961e223 100644
--- a/src/pages/docs/cli/autocomplete.mdx
+++ b/src/pages/docs/cli/autocomplete.mdx
@@ -10,7 +10,7 @@ Use the `ably autocomplete` command to display installation instructions for she
 
 <Code>
 ```shell
-ably autocomplete [shell]
+ably autocomplete [shell] [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/config/path.mdx b/src/pages/docs/cli/config/path.mdx
index 2ca01e9e40..6401dda6f3 100644
--- a/src/pages/docs/cli/config/path.mdx
+++ b/src/pages/docs/cli/config/path.mdx
@@ -10,7 +10,7 @@ Use the `ably config path` command to print the path to the Ably CLI config file
 
 <Code>
 ```shell
-ably config path
+ably config path [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/config/show.mdx b/src/pages/docs/cli/config/show.mdx
index 06cc10e6f3..6b0568f1e7 100644
--- a/src/pages/docs/cli/config/show.mdx
+++ b/src/pages/docs/cli/config/show.mdx
@@ -10,7 +10,7 @@ Use the `ably config show` command to display the contents of the Ably CLI confi
 
 <Code>
 ```shell
-ably config show
+ably config show [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/env.mdx b/src/pages/docs/cli/env.mdx
index ee1cd4a02e..5f211121ac 100644
--- a/src/pages/docs/cli/env.mdx
+++ b/src/pages/docs/cli/env.mdx
@@ -88,7 +88,7 @@ ably env ABLY_API_KEY --json
 
 ## Usage
 
-<Aside data-type="note">
+<Aside data-type='note'>
 The CLI does not automatically load `.env` files. Set environment variables in your shell, CI/CD configuration, or inline with your commands.
 </Aside>
 
diff --git a/src/pages/docs/cli/interactive.mdx b/src/pages/docs/cli/interactive.mdx
index f7b229c30f..ac9f086c2c 100644
--- a/src/pages/docs/cli/interactive.mdx
+++ b/src/pages/docs/cli/interactive.mdx
@@ -10,11 +10,11 @@ Use the `ably interactive` command to launch an interactive shell for the Ably C
 
 <Code>
 ```shell
-ably interactive
+ably interactive [options]
 ```
 </Code>
 
-<Aside data-type="note">
+<Aside data-type='note'>
 This feature is in ALPHA and may change in future releases.
 </Aside>
 
diff --git a/src/pages/docs/cli/login.mdx b/src/pages/docs/cli/login.mdx
index 70528a7bf8..70a0a21f24 100644
--- a/src/pages/docs/cli/login.mdx
+++ b/src/pages/docs/cli/login.mdx
@@ -16,7 +16,7 @@ ably login [options]
 ```
 </Code>
 
-<Aside data-type="note">
+<Aside data-type='note'>
 This command is an alias for [`ably accounts login`](/docs/cli/accounts/login).
 </Aside>
 
diff --git a/src/pages/docs/cli/push/devices/get.mdx b/src/pages/docs/cli/push/devices/get.mdx
index 04a62217e8..12d98c813f 100644
--- a/src/pages/docs/cli/push/devices/get.mdx
+++ b/src/pages/docs/cli/push/devices/get.mdx
@@ -10,7 +10,7 @@ Use the `ably push devices get` command to get details of a push device registra
 
 <Code>
 ```shell
-ably push devices get <device-id>
+ably push devices get <device-id> [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/spaces/cursors/get.mdx b/src/pages/docs/cli/spaces/cursors/get.mdx
index fbbcd8728f..b6b5a6b217 100644
--- a/src/pages/docs/cli/spaces/cursors/get.mdx
+++ b/src/pages/docs/cli/spaces/cursors/get.mdx
@@ -10,7 +10,7 @@ Use the `ably spaces cursors get` command to get all current cursors in a space.
 
 <Code>
 ```shell
-ably spaces cursors get <space-name>
+ably spaces cursors get <space-name> [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/spaces/get.mdx b/src/pages/docs/cli/spaces/get.mdx
index 067022d0c1..84d427ae57 100644
--- a/src/pages/docs/cli/spaces/get.mdx
+++ b/src/pages/docs/cli/spaces/get.mdx
@@ -10,7 +10,7 @@ Use the `ably spaces get` command to get the current state of a space.
 
 <Code>
 ```shell
-ably spaces get <space-name>
+ably spaces get <space-name> [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/spaces/locations/get.mdx b/src/pages/docs/cli/spaces/locations/get.mdx
index ce3768c107..0f0304e228 100644
--- a/src/pages/docs/cli/spaces/locations/get.mdx
+++ b/src/pages/docs/cli/spaces/locations/get.mdx
@@ -10,7 +10,7 @@ Use the `ably spaces locations get` command to get all current locations in a sp
 
 <Code>
 ```shell
-ably spaces locations get <space-name>
+ably spaces locations get <space-name> [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/spaces/locks/get.mdx b/src/pages/docs/cli/spaces/locks/get.mdx
index 7ab4eb2739..ffd0b029b8 100644
--- a/src/pages/docs/cli/spaces/locks/get.mdx
+++ b/src/pages/docs/cli/spaces/locks/get.mdx
@@ -10,7 +10,7 @@ Use the `ably spaces locks get` command to get a lock or all locks in a space.
 
 <Code>
 ```shell
-ably spaces locks get <space-name> [lock-id]
+ably spaces locks get <space-name> [lock-id] [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/spaces/members/get.mdx b/src/pages/docs/cli/spaces/members/get.mdx
index 591ad15b8d..96b9f36543 100644
--- a/src/pages/docs/cli/spaces/members/get.mdx
+++ b/src/pages/docs/cli/spaces/members/get.mdx
@@ -10,7 +10,7 @@ Use the `ably spaces members get` command to get all members in a space.
 
 <Code>
 ```shell
-ably spaces members get <space-name>
+ably spaces members get <space-name> [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/spaces/occupancy/get.mdx b/src/pages/docs/cli/spaces/occupancy/get.mdx
index 71ceaa70c4..19f271ed98 100644
--- a/src/pages/docs/cli/spaces/occupancy/get.mdx
+++ b/src/pages/docs/cli/spaces/occupancy/get.mdx
@@ -10,7 +10,7 @@ Use the `ably spaces occupancy get` command to get current occupancy metrics for
 
 <Code>
 ```shell
-ably spaces occupancy get <space-name>
+ably spaces occupancy get <space-name> [options]
 ```
 </Code>
 
diff --git a/src/pages/docs/cli/version.mdx b/src/pages/docs/cli/version.mdx
index f998d76e54..2ec906feb4 100644
--- a/src/pages/docs/cli/version.mdx
+++ b/src/pages/docs/cli/version.mdx
@@ -10,7 +10,7 @@ Use the `ably version` command to display version information for the Ably CLI,
 
 <Code>
 ```shell
-ably version
+ably version [options]
 ```
 </Code>