[DX-1326] docs: document ably init and use it across getting-started pages

src/data/nav/platform.ts

@@ -394,6 +394,7 @@ export default {
               link: '/docs/cli',
               index: true,
             },
+            { name: 'Init', link: '/docs/cli/init' },
             { name: 'Login', link: '/docs/cli/login' },
             {
               name: 'Accounts',

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

@@ -44,19 +44,11 @@ implementation("com.ably.chat:chat-extensions-compose:1.2.0")
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/chat/getting-started/javascript.mdx

@@ -62,19 +62,11 @@ echo "ABLY_API_KEY={{API_KEY}}" > .env
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/chat/getting-started/jvm.mdx

@@ -59,19 +59,11 @@ implementation("org.slf4j:slf4j-nop:2.0.17")
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/chat/getting-started/react-native.mdx

@@ -53,19 +53,11 @@ cd ios && pod install && cd ..
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/chat/getting-started/react-ui-kit.mdx

@@ -67,19 +67,11 @@ That's all the setup you need—the kit's CSS is automatically bundled by Vite a
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/chat/getting-started/react.mdx

@@ -60,19 +60,11 @@ echo "VITE_ABLY_API_KEY={{API_KEY}}" > .env
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/chat/getting-started/swift-async-sequence.mdx

@@ -25,19 +25,11 @@ Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skill
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/chat/getting-started/swift.mdx

@@ -25,19 +25,11 @@ Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skill
 
 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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/cli/index.mdx

@@ -28,6 +28,7 @@ The following top-level commands are available in the Ably CLI:
 
 | Command | Description |
 | ------- | ----------- |
+| [`ably init`](/docs/cli/init) | Install the CLI, authenticate, and install [Agent Skills](https://github.com/ably/agent-skills) |
 | [`ably login`](/docs/cli/login) | Log in to your Ably account (alias for "ably accounts login") |
 | [`ably accounts`](/docs/cli/accounts) | Manage Ably accounts and your configured access tokens |
 | [`ably apps`](/docs/cli/apps) | Manage Ably apps |

src/pages/docs/cli/init.mdx

@@ -0,0 +1,108 @@
+---
+title: "Init"
+meta_description: "Set up the Ably CLI in a single command: install, authenticate, and install Agent Skills into AI coding tools."
+meta_keywords: "ably cli, cli, init, ably init, onboarding, agent skills, claude code, cursor, vs code, windsurf"
+---
+
+Use the `ably init` command to set up the Ably CLI in a single step. It installs the CLI, authenticates you with [OAuth Device Authorization](https://datatracker.ietf.org/doc/html/rfc8628), and installs the Ably [Agent Skills](https://github.com/ably/agent-skills) into any AI coding tools detected on your machine.
+
+Supported AI coding tools:
+
+* [Claude Code](https://www.anthropic.com/claude-code) - installed via the `@ably/agent-skills` Claude Code plugin.
+* [Cursor](https://cursor.com)
+* [VS Code](https://code.visualstudio.com) (GitHub Copilot)
+* [Windsurf](https://windsurf.com)
+
+For tools other than Claude Code, the skill files are copied directly into the tool's user skills directory.
+
+## Synopsis
+
+<Code>
+```shell
+ably init [options]
+```
+</Code>
+
+You can also run `init` without installing the CLI first:
+
+<Code>
+```shell
+npx -p @ably/cli ably init
+```
+</Code>
+
+## Options
+
+### `--target | -t` <a id="target"/>
+
+Target AI coding tools to install Agent Skills for. Defaults to `auto`, which detects installed tools and prompts you to choose. Repeat the flag to specify multiple tools.
+
+Supported values:
+
+* `auto` - Auto-detect installed tools (default).
+* `claude-code` - Claude Code.
+* `cursor` - Cursor.
+* `vscode` - VS Code (GitHub Copilot).
+* `windsurf` - Windsurf.
+
+`auto` cannot be combined with explicit targets.
+
+### `--json` <a id="json"/>
+
+Output results as compact JSON. Mutually exclusive with `--pretty-json`.
+
+### `--pretty-json` <a id="pretty-json"/>
+
+Output results in formatted, colorized JSON. Mutually exclusive with `--json`.
+
+### `--verbose | -v` <a id="verbose"/>
+
+Enable verbose logging. Can be combined with `--json` or `--pretty-json`.
+
+## Examples
+
+Set up the CLI with auto-detected AI coding tools:
+
+<Code>
+```shell
+ably init
+```
+</Code>
+
+Install Agent Skills for Claude Code only:
+
+<Code>
+```shell
+ably init --target claude-code
+```
+</Code>
+
+Install Agent Skills for Cursor and Windsurf:
+
+<Code>
+```shell
+ably init --target cursor --target windsurf
+```
+</Code>
+
+Set up the CLI without installing it first:
+
+<Code>
+```shell
+npx -p @ably/cli ably init
+```
+</Code>
+
+Run `init` in JSON mode for use in scripts:
+
+<Code>
+```shell
+ably init --json
+```
+</Code>
+
+## See also
+
+* [Login](/docs/cli/login) - Authenticate without installing Agent Skills.
+* [Environment variables](/docs/cli/env) - Authenticate via environment variables instead of OAuth.
+* [CLI reference](/docs/cli) - Full list of available commands.

src/pages/docs/getting-started/dotnet.mdx

@@ -41,19 +41,11 @@ dotnet add package ably.io
 
 Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features. It can simulate other clients by publishing messages, subscribing to channels, and managing presence states.
 
-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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/getting-started/flutter.mdx

@@ -167,19 +167,11 @@ Initialize the Ably service at the application level to prevent it from being re
 
 Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features. It can simulate other clients by publishing messages, subscribing to channels, and managing presence states.
 
-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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/getting-started/go.mdx

@@ -34,19 +34,11 @@ go get -u github.com/ably/ably-go/ably
 
 Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features. It can simulate other clients by publishing messages, subscribing to channels, and managing presence states.
 
-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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>
 

src/pages/docs/getting-started/java.mdx

@@ -52,19 +52,11 @@ Using an AI coding assistant? [Teach it Ably](/docs/platform/ai-llms#agent-skill
 
 Use the [Ably CLI](https://github.com/ably/cli) as an additional client to quickly test Pub/Sub features. It can simulate other clients by publishing messages, subscribing to channels, and managing presence states.
 
-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:
 
 <Code>
 ```shell
-npm install -g @ably/cli
-```
-</Code>
-
-2. Run the following to log in to your Ably account and set the default app and API key:
-
-<Code>
-```shell
-ably login
+npx -p @ably/cli ably init
 ```
 </Code>