[DX-1326] docs: document ably init and use it across getting-started pages by umair-ably · Pull Request #3380 · ably/docs

umair-ably · 2026-05-13T11:02:38Z

Summary

Add a new CLI reference page at /docs/cli/init for the ably init command, covering synopsis, options (--target, --json, --pretty-json, --verbose), examples, and supported AI coding tools (Claude Code, Cursor, VS Code, Windsurf).
Link the new page from the CLI index table and from the platform nav.
Replace the two-step "install CLI then ably login" snippet across all getting-started pages (core, chat, push) with the single npx -p @ably/cli ably init command.
Update /docs/platform/tools/cli to lead with the one-command install and explain what ably init does end-to-end.

Test plan

yarn develop and confirm /docs/cli/init renders, appears in the platform nav, and is linked from the CLI index table.
Spot-check a few getting-started pages (JavaScript, Python, React Native, FCM) to confirm the new single-command snippet renders correctly.
Verify /docs/platform/tools/cli reads cleanly with the new lead-in and the alternative npm install -g @ably/cli block.

🤖 Generated with Claude Code

coderabbitai · 2026-05-13T11:02:46Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 260e58da-61e0-42cd-9529-db016fea6c5a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/cli-1-command-install

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

sacOO7

Will review other pages after some AIT work

Copilot

Pull request overview

This PR introduces documentation for the new ably init CLI command and updates multiple getting-started guides to use a single-command CLI setup flow, while also integrating the new command into the CLI reference navigation.

Changes:

Adds a new CLI reference page for ably init at /docs/cli/init, including options and examples.
Updates the main Ably CLI docs page to lead with the new one-command setup flow.
Replaces the existing “install CLI then login” snippets across Pub/Sub, Chat, and Push getting-started pages with the new init-based snippet, and wires the new page into the CLI index + platform nav.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 31 comments.

Show a summary per file

File	Description
src/pages/docs/push/getting-started/web.mdx	Updates Push web getting-started CLI setup snippet to use `init`.
src/pages/docs/push/getting-started/react-native.mdx	Updates Push React Native getting-started CLI setup snippet to use `init`.
src/pages/docs/push/getting-started/flutter.mdx	Updates Push Flutter getting-started CLI setup snippet to use `init`.
src/pages/docs/push/getting-started/fcm.mdx	Updates Push FCM getting-started CLI setup snippet to use `init`.
src/pages/docs/push/getting-started/apns.mdx	Updates Push APNs getting-started CLI setup snippet to use `init`.
src/pages/docs/platform/tools/cli.mdx	Revises Ably CLI landing page install/usage sections to introduce `ably init`.
src/pages/docs/getting-started/swift.mdx	Updates Pub/Sub Swift getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/ruby.mdx	Updates Pub/Sub Ruby getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/react.mdx	Updates Pub/Sub React getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/react-native.mdx	Updates Pub/Sub React Native getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/python.mdx	Updates Pub/Sub Python getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/php.mdx	Updates Pub/Sub PHP getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/objective-c.mdx	Updates Pub/Sub Objective-C getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/node.mdx	Updates Pub/Sub Node.js getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/nextjs.mdx	Updates Pub/Sub Next.js getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/laravel.mdx	Updates Pub/Sub Laravel getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/kotlin.mdx	Updates Pub/Sub Kotlin getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/javascript.mdx	Updates Pub/Sub JavaScript getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/java.mdx	Updates Pub/Sub Java getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/go.mdx	Updates Pub/Sub Go getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/flutter.mdx	Updates Pub/Sub Flutter getting-started CLI snippet to use `init`.
src/pages/docs/getting-started/dotnet.mdx	Updates Pub/Sub .NET getting-started CLI snippet to use `init`.
src/pages/docs/cli/init.mdx	Adds the new `ably init` CLI reference page (synopsis/options/examples).
src/pages/docs/cli/index.mdx	Adds `ably init` to the CLI commands index table.
src/pages/docs/chat/getting-started/swift.mdx	Updates Chat Swift getting-started CLI snippet to use `init`.
src/pages/docs/chat/getting-started/swift-async-sequence.mdx	Updates Chat Swift AsyncSequence getting-started CLI snippet to use `init`.
src/pages/docs/chat/getting-started/react.mdx	Updates Chat React getting-started CLI snippet to use `init`.
src/pages/docs/chat/getting-started/react-ui-kit.mdx	Updates Chat React UI Kit getting-started CLI snippet to use `init`.
src/pages/docs/chat/getting-started/react-native.mdx	Updates Chat React Native getting-started CLI snippet to use `init`.
src/pages/docs/chat/getting-started/jvm.mdx	Updates Chat JVM getting-started CLI snippet to use `init`.
src/pages/docs/chat/getting-started/javascript.mdx	Updates Chat JavaScript getting-started CLI snippet to use `init`.
src/pages/docs/chat/getting-started/android.mdx	Updates Chat Android getting-started CLI snippet to use `init`.
src/data/nav/platform.ts	Adds `/docs/cli/init` to the platform navigation under Ably CLI Reference.

Comments suppressed due to low confidence (1)

src/pages/docs/cli/init.mdx:92

npx -p @ably/cli init is likely incorrect: with -p, npx will try to run an executable named init, but the Ably CLI executable is ably. Use npx @ably/cli init or npx -p @ably/cli ably init instead.

npx -p @ably/cli init

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add a reference page for the new `ably init` command, link it from the CLI index and platform nav, and replace the two-step install/login snippet across getting-started, chat, and push pages with the single `npx -p @ably/cli init` command. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

sacOO7 · 2026-05-14T07:51:39Z

 Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test chat features. It can simulate other users by sending messages, entering presence, and acting as another user typing a message.

-1. Install the Ably CLI:
+Install the Ably CLI, log in to your Ably account, and set the default app and API key in a single command:


Suggested change

Install the Ably CLI, log in to your Ably account, and set the default app and API key in a single command:

Ably CLI: Install, authenticate, configure the default app with API key and set up [ably agent skills](https://github.com/ably/agent-skills) in a single command

As a third person, somehow log in to your Ably account doesn't give clarity on logging in for the purpose CLI authentication.

Same can be applied across all updated docs.

I'll update to mention auth, but I don't think we need to highlight the skills here. We still have an aside specifically for skills at the top of this page, and the updated CLI docs links also mention skills.

sacOO7 · 2026-05-14T07:57:31Z

 <If loggedIn={false}>
  <Aside data-type='note'>
  The code examples in this guide include a demo API key. If you wish to interact with the Ably CLI and view outputs within your Ably account, ensure that you replace them with your own API key.
  </Aside>
 </If>


Since, npx -p @ably/cli ably init setup everything including authentication in a single command.
This note seems is unnecessary. Currently, it feels ambiguous or doesn't make sense.

Same can be applied across all updated docs.

this note is correct afaict... it only shows when not logged in to highlight that using the demo key alongside the CLI won't work.

The CLI doing auth in 1 step does not take away from needing to use the correct API key in the example code below

sacOO7 · 2026-05-14T08:16:16Z

@@ -44,24 +44,16 @@

 Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test chat features. It can simulate other users by sending messages, entering presence, and acting as another user typing a message.


(Optional) can be removed so that Install Ably CLI becomes part of the standard development workflow. Even if users are not directly using ably-cli, the required skills are still installed as part of npx -p @ably/cli ably init.

(Optional) may have existed earlier because ably-cli was still pre-GA. Since ably-cli is now stable, users should be able to rely on it without issues.

hmm I think we should still keep "optional" because the CLI step is optional with context of this getting started guide i.e. you don't need the CLI to use the getting-started guide

Replace external GitHub link with /docs/platform/tools/cli and shorten "log in to your Ably account" to "authenticate" across getting-started pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

umair-ably requested review from m-hulbert and sacOO7 May 13, 2026 11:04

umair-ably added the review-app Create a Heroku review app label May 13, 2026

ably-ci temporarily deployed to ably-docs-docs-cli-1-co-o62ip9 May 13, 2026 11:19 Inactive

umair-ably changed the title ~~docs: document ably init and use it across getting-started pages~~ [DX-1326] docs: document ably init and use it across getting-started pages May 13, 2026

sacOO7 requested a review from Copilot May 13, 2026 12:16

Copilot started reviewing on behalf of sacOO7 May 13, 2026 12:17 View session

sacOO7 reviewed May 13, 2026

View reviewed changes

Comment thread src/pages/docs/cli/index.mdx Outdated

Copilot AI reviewed May 13, 2026

View reviewed changes

umair-ably force-pushed the docs/cli-1-command-install branch from 0cb540c to 7695d34 Compare May 13, 2026 14:55

ably-ci temporarily deployed to ably-docs-docs-cli-1-co-o62ip9 May 13, 2026 14:55 Inactive

docs: shorten ably init description in CLI index table

2e6f698

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ably-ci temporarily deployed to ably-docs-docs-cli-1-co-o62ip9 May 13, 2026 14:56 Inactive

sacOO7 reviewed May 14, 2026

View reviewed changes

Comment thread src/pages/docs/chat/getting-started/android.mdx

sacOO7 reviewed May 14, 2026

View reviewed changes

Comment thread src/pages/docs/chat/getting-started/android.mdx Outdated

docs: link CLI section to internal docs and tighten phrasing

d46db2b

Replace external GitHub link with /docs/platform/tools/cli and shorten "log in to your Ably account" to "authenticate" across getting-started pages. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ably-ci deployed to ably-docs-docs-cli-1-co-o62ip9 May 14, 2026 08:48 View deployment

umair-ably requested a review from sacOO7 May 14, 2026 08:58

	Install the Ably CLI, log in to your Ably account, and set the default app and API key in a single command:
	Ably CLI: Install, authenticate, configure the default app with API key and set up [ably agent skills](https://github.com/ably/agent-skills) in a single command

		@@ -44,24 +44,16 @@

		Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test chat features. It can simulate other users by sending messages, entering presence, and acting as another user typing a message.

Conversation

umair-ably commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

coderabbitai Bot commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

sacOO7 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sacOO7 May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sacOO7 May 14, 2026

Choose a reason for hiding this comment

Uh oh!

umair-ably May 14, 2026

Choose a reason for hiding this comment

Uh oh!

umair-ably May 14, 2026

Choose a reason for hiding this comment

Uh oh!

sacOO7 May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sacOO7 May 14, 2026

Choose a reason for hiding this comment

Uh oh!

umair-ably May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sacOO7 May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

umair-ably May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

umair-ably commented May 13, 2026 •

edited

Loading

coderabbitai Bot commented May 13, 2026 •

edited

Loading

sacOO7 left a comment •

edited

Loading

sacOO7 May 14, 2026 •

edited

Loading

sacOO7 May 14, 2026 •

edited

Loading

sacOO7 May 14, 2026 •

edited

Loading