[DX-329] Implemented reference documentation for ably-cli tool#3307
[DX-329] Implemented reference documentation for ably-cli tool#3307
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
66fc5d9 to
fa194d7
Compare
…ronment. This gives Node.js 8GB of heap space instead of the default ~4GB, which should handle the additional CLI doc pages comfortably on the xlarge runner.
5f06b43 to
ef019c9
Compare
- Added navigation footers to generated CLI command pages
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Pull request overview
This PR adds a comprehensive Ably CLI command reference under /docs/cli, and exposes it in the Platform navigation, alongside a CI tweak intended to reduce build-time Node memory pressure.
Changes:
- Added MDX reference pages for many
ablycommands and command groups (accounts, apps, auth, channels, logs, push, rooms, spaces, etc.), including examples and global flag references. - Added a new navigation entry to surface the CLI reference in the Platform “API references” section.
- Updated CircleCI build job environment with a higher Node heap limit.
Reviewed changes
Copilot reviewed 167 out of 167 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/pages/docs/cli/index.mdx | CLI reference landing page (global flags + command list) |
| src/pages/docs/cli/autocomplete.mdx | Docs for ably autocomplete |
| src/pages/docs/cli/help.mdx | Docs for ably help |
| src/pages/docs/cli/interactive.mdx | Docs for ably interactive |
| src/pages/docs/cli/login.mdx | Docs for ably login |
| src/pages/docs/cli/status.mdx | Docs for ably status |
| src/pages/docs/cli/version.mdx | Docs for ably version |
| src/pages/docs/cli/accounts/index.mdx | ably accounts group index |
| src/pages/docs/cli/accounts/current.mdx | Docs for ably accounts current |
| src/pages/docs/cli/accounts/list.mdx | Docs for ably accounts list |
| src/pages/docs/cli/accounts/login.mdx | Docs for ably accounts login |
| src/pages/docs/cli/accounts/logout.mdx | Docs for ably accounts logout |
| src/pages/docs/cli/accounts/switch.mdx | Docs for ably accounts switch |
| src/pages/docs/cli/apps/index.mdx | ably apps group index |
| src/pages/docs/cli/apps/create.mdx | Docs for ably apps create |
| src/pages/docs/cli/apps/current.mdx | Docs for ably apps current |
| src/pages/docs/cli/apps/delete.mdx | Docs for ably apps delete |
| src/pages/docs/cli/apps/list.mdx | Docs for ably apps list |
| src/pages/docs/cli/apps/switch.mdx | Docs for ably apps switch |
| src/pages/docs/cli/apps/update.mdx | Docs for ably apps update |
| src/pages/docs/cli/apps/rules/index.mdx | ably apps rules group index |
| src/pages/docs/cli/apps/rules/create.mdx | Docs for ably apps rules create |
| src/pages/docs/cli/apps/rules/delete.mdx | Docs for ably apps rules delete |
| src/pages/docs/cli/apps/rules/list.mdx | Docs for ably apps rules list |
| src/pages/docs/cli/apps/rules/update.mdx | Docs for ably apps rules update |
| src/pages/docs/cli/auth/index.mdx | ably auth group index |
| src/pages/docs/cli/auth/issue-ably-token.mdx | Docs for ably auth issue-ably-token |
| src/pages/docs/cli/auth/issue-jwt-token.mdx | Docs for ably auth issue-jwt-token |
| src/pages/docs/cli/auth/revoke-token.mdx | Docs for ably auth revoke-token |
| src/pages/docs/cli/auth/keys/index.mdx | ably auth keys group index |
| src/pages/docs/cli/auth/keys/create.mdx | Docs for ably auth keys create |
| src/pages/docs/cli/auth/keys/current.mdx | Docs for ably auth keys current |
| src/pages/docs/cli/auth/keys/get.mdx | Docs for ably auth keys get |
| src/pages/docs/cli/auth/keys/list.mdx | Docs for ably auth keys list |
| src/pages/docs/cli/auth/keys/revoke.mdx | Docs for ably auth keys revoke |
| src/pages/docs/cli/auth/keys/switch.mdx | Docs for ably auth keys switch |
| src/pages/docs/cli/auth/keys/update.mdx | Docs for ably auth keys update |
| src/pages/docs/cli/bench/index.mdx | ably bench group index |
| src/pages/docs/cli/bench/publisher.mdx | Docs for ably bench publisher |
| src/pages/docs/cli/bench/subscriber.mdx | Docs for ably bench subscriber |
| src/pages/docs/cli/channels/index.mdx | ably channels group index |
| src/pages/docs/cli/channels/append.mdx | Docs for ably channels append |
| src/pages/docs/cli/channels/batch-publish.mdx | Docs for ably channels batch-publish |
| src/pages/docs/cli/channels/delete.mdx | Docs for ably channels delete |
| src/pages/docs/cli/channels/history.mdx | Docs for ably channels history |
| src/pages/docs/cli/channels/inspect.mdx | Docs for ably channels inspect |
| src/pages/docs/cli/channels/list.mdx | Docs for ably channels list |
| src/pages/docs/cli/channels/publish.mdx | Docs for ably channels publish |
| src/pages/docs/cli/channels/subscribe.mdx | Docs for ably channels subscribe |
| src/pages/docs/cli/channels/update.mdx | Docs for ably channels update |
| src/pages/docs/cli/channels/annotations/index.mdx | ably channels annotations group index |
| src/pages/docs/cli/channels/annotations/publish.mdx | Docs for ably channels annotations publish |
| src/pages/docs/cli/channels/annotations/subscribe.mdx | Docs for ably channels annotations subscribe |
| src/pages/docs/cli/channels/annotations/get.mdx | Docs for ably channels annotations get |
| src/pages/docs/cli/channels/annotations/delete.mdx | Docs for ably channels annotations delete |
| src/pages/docs/cli/channels/occupancy/index.mdx | ably channels occupancy group index |
| src/pages/docs/cli/channels/occupancy/get.mdx | Docs for ably channels occupancy get |
| src/pages/docs/cli/channels/occupancy/subscribe.mdx | Docs for ably channels occupancy subscribe |
| src/pages/docs/cli/channels/presence/index.mdx | ably channels presence group index |
| src/pages/docs/cli/channels/presence/enter.mdx | Docs for ably channels presence enter |
| src/pages/docs/cli/channels/presence/get.mdx | Docs for ably channels presence get |
| src/pages/docs/cli/channels/presence/subscribe.mdx | Docs for ably channels presence subscribe |
| src/pages/docs/cli/config/index.mdx | ably config group index |
| src/pages/docs/cli/config/path.mdx | Docs for ably config path |
| src/pages/docs/cli/config/show.mdx | Docs for ably config show |
| src/pages/docs/cli/connections/index.mdx | ably connections group index |
| src/pages/docs/cli/connections/test.mdx | Docs for ably connections test |
| src/pages/docs/cli/integrations/index.mdx | ably integrations group index |
| src/pages/docs/cli/integrations/create.mdx | Docs for ably integrations create |
| src/pages/docs/cli/integrations/delete.mdx | Docs for ably integrations delete |
| src/pages/docs/cli/integrations/get.mdx | Docs for ably integrations get |
| src/pages/docs/cli/integrations/list.mdx | Docs for ably integrations list |
| src/pages/docs/cli/integrations/update.mdx | Docs for ably integrations update |
| src/pages/docs/cli/logs/index.mdx | ably logs group index |
| src/pages/docs/cli/logs/history.mdx | Docs for ably logs history |
| src/pages/docs/cli/logs/subscribe.mdx | Docs for ably logs subscribe |
| src/pages/docs/cli/logs/channel-lifecycle/index.mdx | ably logs channel-lifecycle group index |
| src/pages/docs/cli/logs/channel-lifecycle/subscribe.mdx | Docs for ably logs channel-lifecycle subscribe |
| src/pages/docs/cli/logs/connection-lifecycle/index.mdx | ably logs connection-lifecycle group index |
| src/pages/docs/cli/logs/connection-lifecycle/subscribe.mdx | Docs for ably logs connection-lifecycle subscribe |
| src/pages/docs/cli/logs/connection-lifecycle/history.mdx | Docs for ably logs connection-lifecycle history |
| src/pages/docs/cli/logs/push/index.mdx | ably logs push group index |
| src/pages/docs/cli/logs/push/subscribe.mdx | Docs for ably logs push subscribe |
| src/pages/docs/cli/logs/push/history.mdx | Docs for ably logs push history |
| src/pages/docs/cli/push/index.mdx | ably push group index |
| src/pages/docs/cli/push/publish.mdx | Docs for ably push publish |
| src/pages/docs/cli/push/batch-publish.mdx | Docs for ably push batch-publish |
| src/pages/docs/cli/push/channels/index.mdx | ably push channels group index |
| src/pages/docs/cli/push/channels/list.mdx | Docs for ably push channels list |
| src/pages/docs/cli/push/channels/list-channels.mdx | Docs for ably push channels list-channels |
| src/pages/docs/cli/push/channels/save.mdx | Docs for ably push channels save |
| src/pages/docs/cli/push/channels/remove.mdx | Docs for ably push channels remove |
| src/pages/docs/cli/push/channels/remove-where.mdx | Docs for ably push channels remove-where |
| src/pages/docs/cli/push/config/index.mdx | ably push config group index |
| src/pages/docs/cli/push/config/show.mdx | Docs for ably push config show |
| src/pages/docs/cli/push/config/set-apns.mdx | Docs for ably push config set-apns |
| src/pages/docs/cli/push/config/set-fcm.mdx | Docs for ably push config set-fcm |
| src/pages/docs/cli/push/config/clear-apns.mdx | Docs for ably push config clear-apns |
| src/pages/docs/cli/push/config/clear-fcm.mdx | Docs for ably push config clear-fcm |
| src/pages/docs/cli/push/devices/index.mdx | ably push devices group index |
| src/pages/docs/cli/push/devices/list.mdx | Docs for ably push devices list |
| src/pages/docs/cli/push/devices/get.mdx | Docs for ably push devices get |
| src/pages/docs/cli/push/devices/save.mdx | Docs for ably push devices save |
| src/pages/docs/cli/push/devices/remove.mdx | Docs for ably push devices remove |
| src/pages/docs/cli/push/devices/remove-where.mdx | Docs for ably push devices remove-where |
| src/pages/docs/cli/queues/index.mdx | ably queues group index |
| src/pages/docs/cli/queues/create.mdx | Docs for ably queues create |
| src/pages/docs/cli/queues/delete.mdx | Docs for ably queues delete |
| src/pages/docs/cli/queues/list.mdx | Docs for ably queues list |
| src/pages/docs/cli/rooms/index.mdx | ably rooms group index |
| src/pages/docs/cli/rooms/list.mdx | Docs for ably rooms list |
| src/pages/docs/cli/rooms/messages/index.mdx | ably rooms messages group index |
| src/pages/docs/cli/rooms/messages/send.mdx | Docs for ably rooms messages send |
| src/pages/docs/cli/rooms/messages/subscribe.mdx | Docs for ably rooms messages subscribe |
| src/pages/docs/cli/rooms/messages/history.mdx | Docs for ably rooms messages history |
| src/pages/docs/cli/rooms/messages/update.mdx | Docs for ably rooms messages update |
| src/pages/docs/cli/rooms/messages/delete.mdx | Docs for ably rooms messages delete |
| src/pages/docs/cli/rooms/messages/reactions/index.mdx | ably rooms messages reactions group index |
| src/pages/docs/cli/rooms/messages/reactions/send.mdx | Docs for ably rooms messages reactions send |
| src/pages/docs/cli/rooms/messages/reactions/subscribe.mdx | Docs for ably rooms messages reactions subscribe |
| src/pages/docs/cli/rooms/messages/reactions/remove.mdx | Docs for ably rooms messages reactions remove |
| src/pages/docs/cli/rooms/occupancy/index.mdx | ably rooms occupancy group index |
| src/pages/docs/cli/rooms/occupancy/get.mdx | Docs for ably rooms occupancy get |
| src/pages/docs/cli/rooms/occupancy/subscribe.mdx | Docs for ably rooms occupancy subscribe |
| src/pages/docs/cli/rooms/presence/index.mdx | ably rooms presence group index |
| src/pages/docs/cli/rooms/presence/enter.mdx | Docs for ably rooms presence enter |
| src/pages/docs/cli/rooms/presence/get.mdx | Docs for ably rooms presence get |
| src/pages/docs/cli/rooms/presence/subscribe.mdx | Docs for ably rooms presence subscribe |
| src/pages/docs/cli/rooms/reactions/index.mdx | ably rooms reactions group index |
| src/pages/docs/cli/rooms/reactions/send.mdx | Docs for ably rooms reactions send |
| src/pages/docs/cli/rooms/reactions/subscribe.mdx | Docs for ably rooms reactions subscribe |
| src/pages/docs/cli/rooms/typing/index.mdx | ably rooms typing group index |
| src/pages/docs/cli/rooms/typing/keystroke.mdx | Docs for ably rooms typing keystroke |
| src/pages/docs/cli/rooms/typing/subscribe.mdx | Docs for ably rooms typing subscribe |
| src/pages/docs/cli/spaces/index.mdx | ably spaces group index |
| src/pages/docs/cli/spaces/create.mdx | Docs for ably spaces create |
| src/pages/docs/cli/spaces/get.mdx | Docs for ably spaces get |
| src/pages/docs/cli/spaces/list.mdx | Docs for ably spaces list |
| src/pages/docs/cli/spaces/subscribe.mdx | Docs for ably spaces subscribe |
| src/pages/docs/cli/spaces/cursors/index.mdx | ably spaces cursors group index |
| src/pages/docs/cli/spaces/cursors/get.mdx | Docs for ably spaces cursors get |
| src/pages/docs/cli/spaces/cursors/set.mdx | Docs for ably spaces cursors set |
| src/pages/docs/cli/spaces/cursors/subscribe.mdx | Docs for ably spaces cursors subscribe |
| src/pages/docs/cli/spaces/locations/index.mdx | ably spaces locations group index |
| src/pages/docs/cli/spaces/locations/get.mdx | Docs for ably spaces locations get |
| src/pages/docs/cli/spaces/locations/set.mdx | Docs for ably spaces locations set |
| src/pages/docs/cli/spaces/locations/subscribe.mdx | Docs for ably spaces locations subscribe |
| src/pages/docs/cli/spaces/locks/index.mdx | ably spaces locks group index |
| src/pages/docs/cli/spaces/locks/acquire.mdx | Docs for ably spaces locks acquire |
| src/pages/docs/cli/spaces/locks/get.mdx | Docs for ably spaces locks get |
| src/pages/docs/cli/spaces/locks/subscribe.mdx | Docs for ably spaces locks subscribe |
| src/pages/docs/cli/spaces/members/index.mdx | ably spaces members group index |
| src/pages/docs/cli/spaces/members/enter.mdx | Docs for ably spaces members enter |
| src/pages/docs/cli/spaces/members/get.mdx | Docs for ably spaces members get |
| src/pages/docs/cli/spaces/members/subscribe.mdx | Docs for ably spaces members subscribe |
| src/pages/docs/cli/spaces/occupancy/index.mdx | ably spaces occupancy group index |
| src/pages/docs/cli/spaces/occupancy/get.mdx | Docs for ably spaces occupancy get |
| src/pages/docs/cli/spaces/occupancy/subscribe.mdx | Docs for ably spaces occupancy subscribe |
| src/pages/docs/cli/stats/index.mdx | ably stats group index |
| src/pages/docs/cli/stats/account.mdx | Docs for ably stats account |
| src/pages/docs/cli/stats/app.mdx | Docs for ably stats app |
| src/pages/docs/cli/support/index.mdx | ably support group index |
| src/pages/docs/cli/support/ask.mdx | Docs for ably support ask |
| src/pages/docs/cli/support/contact.mdx | Docs for ably support contact |
| src/data/nav/platform.ts | Adds nav link to the CLI reference page |
| .circleci/config.yml | Increases Node heap limit for the build job |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…e and interactive mode
- Marked `--json` and `--mutable-json` flags as mutually exclusive
…rence-documentation
|
TODO
|
… and technical doc
…reference doc Standardize CLI terminology by replacing "flags" with "options" throughout all 125+ CLI reference pages. Inline the three global options (--json, --pretty-json, --verbose) as full subsections on each page instead of linking to the index page, improving discoverability.
|
Update for push commands - #3353 |
1a1386d to
0e2ccd5
Compare
AndyTWF
left a comment
There was a problem hiding this comment.
Looks good, but noting that this requires a CLI release prior to merging
- Clarify --message flag: accepts plain text, JSON data, or full message object - Add example showing full message object format for push publish - Update batch-publish payload description with @filename syntax and message field - Add batch-publish example showing "message" field in channel items Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
docs(cli): improve push publish and batch-publish reference docs
… identifiers Reflects ably/ably-cli#361 — converts --name, --channel, and --location flags to positional arguments across 9 command docs: apps create, apps rules create, auth keys create, queues create, push channels list/save/remove/remove-where, and spaces locations set.
There was a problem hiding this comment.
Given the depth of docs added here I've naturally not read them all, but the composition of the MDX docs on the review app looks good to me, and I only have a handful of minor non-blocking nits to add. The orphaned pages nit is the biggest one. Nice job though.
Obvs need to verify that the cli has been released before this as @AndyTWF mentioned, and my agent picked up a couple of unresolved comments in the thread.
Not a consideration for this PR, but I do wonder what our best strategy will be for keeping these docs in sync with the rapid development of the CLI.
|
|
||
| ### `--refresh-cache | -r` <a id="refresh-cache"/> | ||
|
|
||
| Refresh the autocomplete cache, ignoring displaying instructions. |
There was a problem hiding this comment.
nit: Might want to re-word this, doesn't make grammatical sense to me. "instead of displaying instructions" ?
| | [`ably support`](/docs/cli/support) | Get support and help from Ably | | ||
| | [`ably autocomplete`](/docs/cli/autocomplete) | Display autocomplete installation instructions | | ||
| | [`ably status`](/docs/cli/status) | Check the status of the Ably service | | ||
| | [`ably help`](/docs/cli/help) | Display help for ably | |
There was a problem hiding this comment.
nit: interactive and version are docs in the PR but aren't in this table. interactive also isn't in the sidebar.
|
|
||
| ## Output | ||
|
|
||
| The `ably accounts list` command displays list of accounts in format: |
There was a problem hiding this comment.
nit: another grammar tidyup
|
TODO's
|
Uh oh!
There was an error while loading. Please reload this page.