From 05ed4f131a0e2edb64fd689ad852784e951f9bc4 Mon Sep 17 00:00:00 2001 From: Mark Hulbert <39801222+m-hulbert@users.noreply.github.com> Date: Mon, 15 Dec 2025 13:29:05 +0100 Subject: [PATCH] Add initial set of CLI reference docs --- src/pages/docs/cli/accounts/current.mdx | 72 ++++++++ src/pages/docs/cli/accounts/index.mdx | 20 ++ src/pages/docs/cli/accounts/list.mdx | 63 +++++++ src/pages/docs/cli/accounts/login.mdx | 80 ++++++++ src/pages/docs/cli/accounts/logout.mdx | 76 ++++++++ src/pages/docs/cli/accounts/stats.mdx | 147 +++++++++++++++ src/pages/docs/cli/accounts/switch.mdx | 52 ++++++ .../docs/cli/apps/channel-rules/create.mdx | 110 +++++++++++ .../docs/cli/apps/channel-rules/delete.mdx | 72 ++++++++ .../docs/cli/apps/channel-rules/index.mdx | 18 ++ .../docs/cli/apps/channel-rules/list.mdx | 95 ++++++++++ .../docs/cli/apps/channel-rules/update.mdx | 110 +++++++++++ src/pages/docs/cli/apps/create.mdx | 63 +++++++ src/pages/docs/cli/apps/current.mdx | 68 +++++++ src/pages/docs/cli/apps/delete.mdx | 96 ++++++++++ src/pages/docs/cli/apps/index.mdx | 40 ++++ src/pages/docs/cli/apps/list.mdx | 89 +++++++++ src/pages/docs/cli/apps/logs/history.mdx | 80 ++++++++ src/pages/docs/cli/apps/logs/index.mdx | 20 ++ src/pages/docs/cli/apps/logs/subscribe.mdx | 56 ++++++ src/pages/docs/cli/apps/set-apns-p12.mdx | 76 ++++++++ src/pages/docs/cli/apps/stats.mdx | 116 ++++++++++++ src/pages/docs/cli/apps/switch.mdx | 64 +++++++ src/pages/docs/cli/apps/update.mdx | 78 ++++++++ src/pages/docs/cli/auth/index.mdx | 30 +++ src/pages/docs/cli/auth/issue-ably-token.mdx | 128 +++++++++++++ src/pages/docs/cli/auth/issue-jwt-token.mdx | 116 ++++++++++++ src/pages/docs/cli/auth/keys/create.mdx | 103 +++++++++++ src/pages/docs/cli/auth/keys/current.mdx | 82 +++++++++ src/pages/docs/cli/auth/keys/get.mdx | 70 +++++++ src/pages/docs/cli/auth/keys/index.mdx | 21 +++ src/pages/docs/cli/auth/keys/list.mdx | 97 ++++++++++ src/pages/docs/cli/auth/keys/revoke.mdx | 78 ++++++++ src/pages/docs/cli/auth/keys/switch.mdx | 66 +++++++ src/pages/docs/cli/auth/keys/update.mdx | 70 +++++++ src/pages/docs/cli/auth/revoke-token.mdx | 82 +++++++++ src/pages/docs/cli/bench/index.mdx | 16 ++ src/pages/docs/cli/bench/publisher.mdx | 110 +++++++++++ src/pages/docs/cli/bench/subscriber.mdx | 70 +++++++ src/pages/docs/cli/channel-rule/index.mdx | 22 +++ src/pages/docs/cli/channels/batch-publish.mdx | 163 +++++++++++++++++ src/pages/docs/cli/channels/history.mdx | 163 +++++++++++++++++ src/pages/docs/cli/channels/index.mdx | 41 +++++ src/pages/docs/cli/channels/list.mdx | 135 ++++++++++++++ src/pages/docs/cli/channels/logs.mdx | 173 ++++++++++++++++++ src/pages/docs/cli/channels/occupancy/get.mdx | 79 ++++++++ .../docs/cli/channels/occupancy/index.mdx | 14 ++ .../docs/cli/channels/occupancy/subscribe.mdx | 106 +++++++++++ .../docs/cli/channels/presence/enter.mdx | 143 +++++++++++++++ .../docs/cli/channels/presence/index.mdx | 14 ++ .../docs/cli/channels/presence/subscribe.mdx | 105 +++++++++++ src/pages/docs/cli/channels/publish.mdx | 150 +++++++++++++++ src/pages/docs/cli/channels/subscribe.mdx | 144 +++++++++++++++ src/pages/docs/cli/config.mdx | 64 +++++++ src/pages/docs/cli/connections/index.mdx | 21 +++ src/pages/docs/cli/connections/logs.mdx | 54 ++++++ src/pages/docs/cli/connections/stats.mdx | 98 ++++++++++ src/pages/docs/cli/connections/test.mdx | 69 +++++++ src/pages/docs/cli/help.mdx | 102 +++++++++++ src/pages/docs/cli/index.mdx | 119 ++++++++++++ src/pages/docs/cli/integrations/create.mdx | 108 +++++++++++ src/pages/docs/cli/integrations/delete.mdx | 78 ++++++++ src/pages/docs/cli/integrations/get.mdx | 66 +++++++ src/pages/docs/cli/integrations/index.mdx | 19 ++ src/pages/docs/cli/integrations/list.mdx | 104 +++++++++++ src/pages/docs/cli/integrations/update.mdx | 100 ++++++++++ src/pages/docs/cli/interactive.mdx | 49 +++++ src/pages/docs/cli/login.mdx | 84 +++++++++ src/pages/docs/cli/logs/index.mdx | 25 +++ src/pages/docs/cli/queues/create.mdx | 82 +++++++++ src/pages/docs/cli/queues/delete.mdx | 78 ++++++++ src/pages/docs/cli/queues/index.mdx | 17 ++ src/pages/docs/cli/queues/list.mdx | 105 +++++++++++ src/pages/docs/cli/rooms/index.mdx | 59 ++++++ src/pages/docs/cli/rooms/list.mdx | 91 +++++++++ src/pages/docs/cli/rooms/messages/history.mdx | 109 +++++++++++ src/pages/docs/cli/rooms/messages/index.mdx | 26 +++ .../cli/rooms/messages/reactions/index.mdx | 15 ++ .../cli/rooms/messages/reactions/remove.mdx | 87 +++++++++ .../cli/rooms/messages/reactions/send.mdx | 103 +++++++++++ .../rooms/messages/reactions/subscribe.mdx | 73 ++++++++ src/pages/docs/cli/rooms/messages/send.mdx | 99 ++++++++++ .../docs/cli/rooms/messages/subscribe.mdx | 105 +++++++++++ src/pages/docs/cli/rooms/occupancy/get.mdx | 69 +++++++ src/pages/docs/cli/rooms/occupancy/index.mdx | 14 ++ .../docs/cli/rooms/occupancy/subscribe.mdx | 75 ++++++++ src/pages/docs/cli/rooms/presence/enter.mdx | 93 ++++++++++ src/pages/docs/cli/rooms/presence/index.mdx | 14 ++ .../docs/cli/rooms/presence/subscribe.mdx | 84 +++++++++ src/pages/docs/cli/rooms/reactions/index.mdx | 14 ++ src/pages/docs/cli/rooms/reactions/send.mdx | 116 ++++++++++++ .../docs/cli/rooms/reactions/subscribe.mdx | 68 +++++++ src/pages/docs/cli/rooms/typing/index.mdx | 14 ++ src/pages/docs/cli/rooms/typing/keystroke.mdx | 88 +++++++++ src/pages/docs/cli/rooms/typing/subscribe.mdx | 67 +++++++ src/pages/docs/cli/spaces/cursors/get-all.mdx | 112 ++++++++++++ src/pages/docs/cli/spaces/cursors/index.mdx | 15 ++ src/pages/docs/cli/spaces/cursors/set.mdx | 129 +++++++++++++ .../docs/cli/spaces/cursors/subscribe.mdx | 90 +++++++++ src/pages/docs/cli/spaces/index.mdx | 51 ++++++ src/pages/docs/cli/spaces/list.mdx | 99 ++++++++++ .../docs/cli/spaces/locations/get-all.mdx | 84 +++++++++ src/pages/docs/cli/spaces/locations/index.mdx | 15 ++ src/pages/docs/cli/spaces/locations/set.mdx | 127 +++++++++++++ .../docs/cli/spaces/locations/subscribe.mdx | 103 +++++++++++ src/pages/docs/cli/spaces/locks/acquire.mdx | 101 ++++++++++ src/pages/docs/cli/spaces/locks/get-all.mdx | 111 +++++++++++ src/pages/docs/cli/spaces/locks/get.mdx | 95 ++++++++++ src/pages/docs/cli/spaces/locks/index.mdx | 16 ++ src/pages/docs/cli/spaces/locks/subscribe.mdx | 80 ++++++++ src/pages/docs/cli/spaces/members/enter.mdx | 112 ++++++++++++ src/pages/docs/cli/spaces/members/index.mdx | 14 ++ .../docs/cli/spaces/members/subscribe.mdx | 112 ++++++++++++ src/pages/docs/cli/status.mdx | 53 ++++++ src/pages/docs/cli/support/ask.mdx | 115 ++++++++++++ src/pages/docs/cli/support/contact.mdx | 47 +++++ src/pages/docs/cli/support/index.mdx | 17 ++ src/pages/docs/cli/version.mdx | 63 +++++++ 118 files changed, 9038 insertions(+) create mode 100644 src/pages/docs/cli/accounts/current.mdx create mode 100644 src/pages/docs/cli/accounts/index.mdx create mode 100644 src/pages/docs/cli/accounts/list.mdx create mode 100644 src/pages/docs/cli/accounts/login.mdx create mode 100644 src/pages/docs/cli/accounts/logout.mdx create mode 100644 src/pages/docs/cli/accounts/stats.mdx create mode 100644 src/pages/docs/cli/accounts/switch.mdx create mode 100644 src/pages/docs/cli/apps/channel-rules/create.mdx create mode 100644 src/pages/docs/cli/apps/channel-rules/delete.mdx create mode 100644 src/pages/docs/cli/apps/channel-rules/index.mdx create mode 100644 src/pages/docs/cli/apps/channel-rules/list.mdx create mode 100644 src/pages/docs/cli/apps/channel-rules/update.mdx create mode 100644 src/pages/docs/cli/apps/create.mdx create mode 100644 src/pages/docs/cli/apps/current.mdx create mode 100644 src/pages/docs/cli/apps/delete.mdx create mode 100644 src/pages/docs/cli/apps/index.mdx create mode 100644 src/pages/docs/cli/apps/list.mdx create mode 100644 src/pages/docs/cli/apps/logs/history.mdx create mode 100644 src/pages/docs/cli/apps/logs/index.mdx create mode 100644 src/pages/docs/cli/apps/logs/subscribe.mdx create mode 100644 src/pages/docs/cli/apps/set-apns-p12.mdx create mode 100644 src/pages/docs/cli/apps/stats.mdx create mode 100644 src/pages/docs/cli/apps/switch.mdx create mode 100644 src/pages/docs/cli/apps/update.mdx create mode 100644 src/pages/docs/cli/auth/index.mdx create mode 100644 src/pages/docs/cli/auth/issue-ably-token.mdx create mode 100644 src/pages/docs/cli/auth/issue-jwt-token.mdx create mode 100644 src/pages/docs/cli/auth/keys/create.mdx create mode 100644 src/pages/docs/cli/auth/keys/current.mdx create mode 100644 src/pages/docs/cli/auth/keys/get.mdx create mode 100644 src/pages/docs/cli/auth/keys/index.mdx create mode 100644 src/pages/docs/cli/auth/keys/list.mdx create mode 100644 src/pages/docs/cli/auth/keys/revoke.mdx create mode 100644 src/pages/docs/cli/auth/keys/switch.mdx create mode 100644 src/pages/docs/cli/auth/keys/update.mdx create mode 100644 src/pages/docs/cli/auth/revoke-token.mdx create mode 100644 src/pages/docs/cli/bench/index.mdx create mode 100644 src/pages/docs/cli/bench/publisher.mdx create mode 100644 src/pages/docs/cli/bench/subscriber.mdx create mode 100644 src/pages/docs/cli/channel-rule/index.mdx create mode 100644 src/pages/docs/cli/channels/batch-publish.mdx create mode 100644 src/pages/docs/cli/channels/history.mdx create mode 100644 src/pages/docs/cli/channels/index.mdx create mode 100644 src/pages/docs/cli/channels/list.mdx create mode 100644 src/pages/docs/cli/channels/logs.mdx create mode 100644 src/pages/docs/cli/channels/occupancy/get.mdx create mode 100644 src/pages/docs/cli/channels/occupancy/index.mdx create mode 100644 src/pages/docs/cli/channels/occupancy/subscribe.mdx create mode 100644 src/pages/docs/cli/channels/presence/enter.mdx create mode 100644 src/pages/docs/cli/channels/presence/index.mdx create mode 100644 src/pages/docs/cli/channels/presence/subscribe.mdx create mode 100644 src/pages/docs/cli/channels/publish.mdx create mode 100644 src/pages/docs/cli/channels/subscribe.mdx create mode 100644 src/pages/docs/cli/config.mdx create mode 100644 src/pages/docs/cli/connections/index.mdx create mode 100644 src/pages/docs/cli/connections/logs.mdx create mode 100644 src/pages/docs/cli/connections/stats.mdx create mode 100644 src/pages/docs/cli/connections/test.mdx create mode 100644 src/pages/docs/cli/help.mdx create mode 100644 src/pages/docs/cli/index.mdx create mode 100644 src/pages/docs/cli/integrations/create.mdx create mode 100644 src/pages/docs/cli/integrations/delete.mdx create mode 100644 src/pages/docs/cli/integrations/get.mdx create mode 100644 src/pages/docs/cli/integrations/index.mdx create mode 100644 src/pages/docs/cli/integrations/list.mdx create mode 100644 src/pages/docs/cli/integrations/update.mdx create mode 100644 src/pages/docs/cli/interactive.mdx create mode 100644 src/pages/docs/cli/login.mdx create mode 100644 src/pages/docs/cli/logs/index.mdx create mode 100644 src/pages/docs/cli/queues/create.mdx create mode 100644 src/pages/docs/cli/queues/delete.mdx create mode 100644 src/pages/docs/cli/queues/index.mdx create mode 100644 src/pages/docs/cli/queues/list.mdx create mode 100644 src/pages/docs/cli/rooms/index.mdx create mode 100644 src/pages/docs/cli/rooms/list.mdx create mode 100644 src/pages/docs/cli/rooms/messages/history.mdx create mode 100644 src/pages/docs/cli/rooms/messages/index.mdx create mode 100644 src/pages/docs/cli/rooms/messages/reactions/index.mdx create mode 100644 src/pages/docs/cli/rooms/messages/reactions/remove.mdx create mode 100644 src/pages/docs/cli/rooms/messages/reactions/send.mdx create mode 100644 src/pages/docs/cli/rooms/messages/reactions/subscribe.mdx create mode 100644 src/pages/docs/cli/rooms/messages/send.mdx create mode 100644 src/pages/docs/cli/rooms/messages/subscribe.mdx create mode 100644 src/pages/docs/cli/rooms/occupancy/get.mdx create mode 100644 src/pages/docs/cli/rooms/occupancy/index.mdx create mode 100644 src/pages/docs/cli/rooms/occupancy/subscribe.mdx create mode 100644 src/pages/docs/cli/rooms/presence/enter.mdx create mode 100644 src/pages/docs/cli/rooms/presence/index.mdx create mode 100644 src/pages/docs/cli/rooms/presence/subscribe.mdx create mode 100644 src/pages/docs/cli/rooms/reactions/index.mdx create mode 100644 src/pages/docs/cli/rooms/reactions/send.mdx create mode 100644 src/pages/docs/cli/rooms/reactions/subscribe.mdx create mode 100644 src/pages/docs/cli/rooms/typing/index.mdx create mode 100644 src/pages/docs/cli/rooms/typing/keystroke.mdx create mode 100644 src/pages/docs/cli/rooms/typing/subscribe.mdx create mode 100644 src/pages/docs/cli/spaces/cursors/get-all.mdx create mode 100644 src/pages/docs/cli/spaces/cursors/index.mdx create mode 100644 src/pages/docs/cli/spaces/cursors/set.mdx create mode 100644 src/pages/docs/cli/spaces/cursors/subscribe.mdx create mode 100644 src/pages/docs/cli/spaces/index.mdx create mode 100644 src/pages/docs/cli/spaces/list.mdx create mode 100644 src/pages/docs/cli/spaces/locations/get-all.mdx create mode 100644 src/pages/docs/cli/spaces/locations/index.mdx create mode 100644 src/pages/docs/cli/spaces/locations/set.mdx create mode 100644 src/pages/docs/cli/spaces/locations/subscribe.mdx create mode 100644 src/pages/docs/cli/spaces/locks/acquire.mdx create mode 100644 src/pages/docs/cli/spaces/locks/get-all.mdx create mode 100644 src/pages/docs/cli/spaces/locks/get.mdx create mode 100644 src/pages/docs/cli/spaces/locks/index.mdx create mode 100644 src/pages/docs/cli/spaces/locks/subscribe.mdx create mode 100644 src/pages/docs/cli/spaces/members/enter.mdx create mode 100644 src/pages/docs/cli/spaces/members/index.mdx create mode 100644 src/pages/docs/cli/spaces/members/subscribe.mdx create mode 100644 src/pages/docs/cli/status.mdx create mode 100644 src/pages/docs/cli/support/ask.mdx create mode 100644 src/pages/docs/cli/support/contact.mdx create mode 100644 src/pages/docs/cli/support/index.mdx create mode 100644 src/pages/docs/cli/version.mdx diff --git a/src/pages/docs/cli/accounts/current.mdx b/src/pages/docs/cli/accounts/current.mdx new file mode 100644 index 0000000000..5a37cc7108 --- /dev/null +++ b/src/pages/docs/cli/accounts/current.mdx @@ -0,0 +1,72 @@ +--- +title: "ably accounts current" +meta_description: "Show the current Ably account information using the CLI." +meta_keywords: "ably cli, cli, accounts, current account, ably accounts current" +--- + + +```shell +ably accounts current [flags] +``` + + +Use the `ably accounts current` command to display information about the currently active Ably account. This shows account details, user information, configured apps, and the current API key being used. + +## Flags + +You can optionally pass the following flags to the `ably accounts current` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably accounts current` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably accounts current` command displays: + +| Property | Description | +| -------- | ----------- | +| Account | The account name and ID. | +| User | The email address of the logged-in user. | +| Apps configured | Number of apps configured for this account. | +| Current App | The currently selected app name and ID. | +| Current API Key | The API key being used. | +| Key Label | The label of the current API key. | + +## Examples + +Show current account information: + + +```shell +ably accounts current +``` + + +**Output:** + +```text +Account: Ably (a12B3c) +User: example.email@example.com +Apps configured: 2 +Current App: example-app (Ab1CdE) +Current API Key: Ab1CdE.F2ghIJ +Key Label: Example Key +``` + + diff --git a/src/pages/docs/cli/accounts/index.mdx b/src/pages/docs/cli/accounts/index.mdx new file mode 100644 index 0000000000..65ce14ef86 --- /dev/null +++ b/src/pages/docs/cli/accounts/index.mdx @@ -0,0 +1,20 @@ +--- +title: "ably accounts" +meta_description: "Manage Ably accounts and configured access tokens using the CLI." +meta_keywords: "ably cli, cli, accounts, authentication, account management, ably accounts" +--- + +Use the `ably accounts` command group to manage your Ably accounts and configured access tokens. These commands enable you to log in, switch between accounts, view account information, and monitor account statistics. + +## Subcommands + +The following commands are used to manage accounts: + +| Command | Description | +| ------- | ----------- | +| [`ably accounts current`](/docs/cli/accounts/current) | Show the current Ably account information. | +| [`ably accounts list`](/docs/cli/accounts/list) | List all locally configured Ably accounts. | +| [`ably accounts login`](/docs/cli/accounts/login) | Log in to an Ably account. | +| [`ably accounts logout`](/docs/cli/accounts/logout) | Log out from an Ably account. | +| [`ably accounts switch`](/docs/cli/accounts/switch) | Switch to a different Ably account. | +| [`ably accounts stats`](/docs/cli/accounts/stats) | Get account-level statistics. | diff --git a/src/pages/docs/cli/accounts/list.mdx b/src/pages/docs/cli/accounts/list.mdx new file mode 100644 index 0000000000..e5e9ae9fda --- /dev/null +++ b/src/pages/docs/cli/accounts/list.mdx @@ -0,0 +1,63 @@ +--- +title: "ably accounts list" +meta_description: "List all locally configured Ably accounts using the CLI." +meta_keywords: "ably cli, cli, accounts, account list, ably accounts list" +--- + + +```shell +ably accounts list [flags] +``` + + +Use the `ably accounts list` command to display all locally configured Ably accounts. This shows account information for all accounts that have been configured in the CLI, including which one is currently active. + +## Global flags + +The following global flags are supported using the `ably accounts list` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably accounts list` command displays: + +| Property | Description | +| -------- | ----------- | +| Account | The account name and ID. | +| Name | The alias name of the account, if one is configured. | +| User | The email address of the logged-in user. | +| Apps | Number of apps configured for this account. | +| Current App | The currently selected app name and ID. | + +## Examples + +List all configured accounts: + + +```shell +ably accounts list +``` + + +**Output:** + +```text +Found 1 accounts: + +▶ Account: default (current) + Name: ExampleAccount (a12B3c) + User: example.email@example.com + Apps configured: 2 + Current app: example-app (Ab1CdE) +``` + diff --git a/src/pages/docs/cli/accounts/login.mdx b/src/pages/docs/cli/accounts/login.mdx new file mode 100644 index 0000000000..d470535690 --- /dev/null +++ b/src/pages/docs/cli/accounts/login.mdx @@ -0,0 +1,80 @@ +--- +title: "ably accounts login" +meta_description: "Log in to your Ably account using the CLI." +meta_keywords: "ably cli, cli, accounts, login, authentication, ably accounts login" +--- + + +```shell +ably accounts login [flags] +``` + + +Use the `ably accounts login` command to authenticate with your Ably account. + +## Arguments + +Pass the following arguments to the `ably accounts login` command: + +### `` + +The access token for your Ably account, for example: `abc1D2ef3Gh4Ij...`. + +If not provided, the CLI will prompt you to enter an access token, or open a browser window for you to obtain one from your Ably account. + +## Flags + +You can optionally pass the following flags to the `ably accounts login` command: + +### `--alias | -a` + +An alias name for this account configuration. If not specified, this becomes the default account. + +### `--no-browser` + +Prevent the CLI from automatically opening a browser for authentication. Use this flag if you prefer to handle authentication manually or in headless environments. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably accounts login` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Log in with interactive authentication: + +```shell +ably accounts login +``` + +Log in with a specific access token: + +```shell +ably accounts login abc1D2ef3Gh4Ij... +``` + +Log in with an alias for the account: + +```shell +ably accounts login --alias example-company +``` + +Log in without opening a browser: + +```shell +ably accounts login --no-browser +``` diff --git a/src/pages/docs/cli/accounts/logout.mdx b/src/pages/docs/cli/accounts/logout.mdx new file mode 100644 index 0000000000..b91349b21f --- /dev/null +++ b/src/pages/docs/cli/accounts/logout.mdx @@ -0,0 +1,76 @@ +--- +title: "ably accounts logout" +meta_description: "Log out from an Ably account using the CLI." +meta_keywords: "ably cli, cli, accounts, logout, authentication, ably accounts logout" +--- + + +```shell +ably accounts logout [flags] +``` + + +Use the `ably accounts logout` command to remove authentication credentials for an Ably account from the CLI. This will remove the locally stored access token and any associated account configuration. + +## Arguments + +Pass the following arguments to the `ably accounts logout` command: + +### `` + +The alias of the account to log out from, for example: `example-company`. + +If not provided, logs out from the currently active account. + +## Flags + +You can optionally pass the following flags to the `ably accounts logout` command: + +### `--force | -f` + +Force logout without a confirmation prompt. This skips the interactive confirmation step. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably accounts logout` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Log out from the current account: + + +```shell +ably accounts logout +``` + + +Log out from a specific account by alias: + + +```shell +ably accounts logout example-company +``` + + +Force logout without confirmation: + + +```shell +ably accounts logout --force +``` + diff --git a/src/pages/docs/cli/accounts/stats.mdx b/src/pages/docs/cli/accounts/stats.mdx new file mode 100644 index 0000000000..938fcdc276 --- /dev/null +++ b/src/pages/docs/cli/accounts/stats.mdx @@ -0,0 +1,147 @@ +--- +title: "ably accounts stats" +meta_description: "Get account-level statistics using the CLI." +meta_keywords: "ably cli, cli, accounts, stats, statistics, metrics, ably accounts stats" +--- + + +```shell +ably accounts stats [flags] +``` + + +Use the `ably accounts stats` command to retrieve usage statistics for your Ably account. This provides metrics for things such as connections, channels and messages. + +## Flags + +You can optionally pass the following flags to the `ably accounts stats` command: + +### `--start` + +Start time for the history query in milliseconds since the epoch, for example: `1618005600000`. + +### `--end` + +End time for the history query in milliseconds since the epoch, for example: `1618091999999`. + +### `--unit` + +The unit of time to aggregate the statistics over. The options are `minute`, `hour`, `day`, or `month`. The default is `minute`. + +### `--limit` + +Maximum number of statistic records to return. The default is `10`. + +### `--live` + +Subscribe to live statistics updates. When enabled, the command will continuously display new statistics as they become available, at minute intervals. + +### `--interval` + +Polling interval in seconds when using `--live` mode. The default is `6` seconds. + +### `--debug` + +Show debug information for live statistics polling. This provides additional information about the polling process. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably accounts stats` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably accounts stats` command displays statistics for each time period: + +| Metric | Description | +| ------ | ----------- | +| Connections | Peak, minimum, mean connections, plus opened, refused, and active counts | +| Channels | Peak, minimum, mean channels, plus opened, refused, and active counts | +| Messages | Total, published, delivered message counts and data volume | +| API Requests | Succeeded, failed, refused, and total request counts | +| Token Requests | Succeeded, failed, and refused token request counts | +| Peak Rates | Maximum rates per second for messages, connections, channels, API requests, and token requests | + +## Examples + +Get recent account statistics: + + +```shell +ably accounts stats +``` + + +**Output:** + +```text +Using: Account=Ably (a12B3c) + +Stats for 2025-09-21 10:23 UTC (local: 9/21/2025, 12:23:00 PM) - 1 minute interval +Connections: 10 peak, 10 min, 3 mean, 0 opened, 0 refused, 0 active +Channels: 4 peak, 4 min, 1.2 mean, 0 opened, 0 refused, 0 active +Messages: 0 total, 0 published, 0 delivered, 0.0 B data volume +API Requests: 0 succeeded, 0 failed, 0 refused, 0 total +Token Requests: 0 succeeded, 0 failed, 0 refused +Peak Rates: + Messages: 0 msgs/s + Connections: 0 conns/s + Channels: 0 chans/s + API Requests: 0 reqs/s + Token Requests: 0 tokens/s +``` + + +Get hourly statistics: + + +```shell +ably accounts stats --unit hour +``` + + +Get statistics for a specific time range: + + +```shell +ably accounts stats --start 1618005600000 --end 1618091999999 +``` + + +Limit results to 5 records: + + +```shell +ably accounts stats --limit 5 +``` + + +Subscribe to live statistics updates: + + +```shell +ably accounts stats --live +``` + + +Subscribe to live statistics with custom interval: + + +```shell +ably accounts stats --live --interval 15 +``` + diff --git a/src/pages/docs/cli/accounts/switch.mdx b/src/pages/docs/cli/accounts/switch.mdx new file mode 100644 index 0000000000..3fa8732699 --- /dev/null +++ b/src/pages/docs/cli/accounts/switch.mdx @@ -0,0 +1,52 @@ +--- +title: "ably accounts switch" +meta_description: "Switch to a different Ably account using the CLI." +meta_keywords: "ably cli, cli, accounts, switch account, ably accounts switch" +--- + + +```shell +ably accounts switch [flags] +``` + + +Use the `ably accounts switch` command to change the currently active Ably account. This allows you to switch between multiple configured accounts without needing to log out and log back in. + +## Arguments + +### `` + +The alias of the account to switch to, for example: `example-company`. + +If not provided, the CLI will prompt you to select from a list of available accounts. + +## Global flags + +The following global flags are supported using the `ably accounts switch` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Choose an account to switch to from a list: + +```shell +ably accounts switch +``` + +Switch to a specific account by alias: + + +```shell +ably accounts switch example-company +``` + diff --git a/src/pages/docs/cli/apps/channel-rules/create.mdx b/src/pages/docs/cli/apps/channel-rules/create.mdx new file mode 100644 index 0000000000..49a295fb39 --- /dev/null +++ b/src/pages/docs/cli/apps/channel-rules/create.mdx @@ -0,0 +1,110 @@ +--- +title: "ably apps channel-rules create" +meta_description: "Create a channel rule for an Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, channel rules, create rule, ably apps channel-rules create" +--- + + +```shell +ably apps channel-rules create --name [flags] +``` + + +Use the `ably apps channel-rules create` command to create a new [channel rule](/docs/channels/channel-rules-namespaces) for an Ably app. Channel rules define behaviors and settings for groups of channels that match a specific naming pattern. + +## Arguments + +### `--name` + +The name of the channel rule. This defines the pattern that channels must match to be affected by this rule. + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably apps channel-rules create` command supports: + +### `--app` + +App ID or name to create the channel rule in. If not specified, uses the current app from your CLI configuration. + +### `--authenticated` + +Whether channels matching this rule require clients to be authenticated. + +### `--persisted` + +Whether messages on channels matching this rule should be persisted to [message history](/docs/storage-history/history). + +### `--persist-last` + +Whether to persist only the last message on channels matching this rule. + +### `--push-enabled` + +Whether [push notifications](/docs/push) should be enabled for channels matching this rule. + +### `--tls-only` + +Whether to enforce TLS for channels matching this rule. + +### `--populate-channel-registry` + +Whether to populate the channel registry for channels matching this rule. + +### `--batching-enabled` + +Whether to enable batching for messages on channels matching this rule. + +### `--batching-interval` + +The batching interval for messages on channels matching this rule (in milliseconds). + +### `--conflation-enabled` + +Whether to enable [delta compression](/docs/channels/channel-parameters/deltas) (conflation) for messages on channels matching this rule. + +### `--conflation-interval` + +The conflation interval for messages on channels matching this rule (in milliseconds). + +### `--conflation-key` + +The conflation key for messages on channels matching this rule. + +### `--expose-time-serial` + +Whether to expose the time serial for messages on channels matching this rule. + +## Global flags + +The following global flags are supported using the `ably apps channel-rules create` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Create a basic channel rule with persistence: + +```shell +ably apps channel-rules create --name "chat" --persisted +``` + +Create a channel rule with push notifications enabled: + +```shell +ably apps channel-rules create --name "events" --push-enabled +``` + +Create a comprehensive channel rule: + +```shell +ably apps channel-rules create --name "notifications" --persisted --push-enabled --app "My App" +``` diff --git a/src/pages/docs/cli/apps/channel-rules/delete.mdx b/src/pages/docs/cli/apps/channel-rules/delete.mdx new file mode 100644 index 0000000000..2114d797b2 --- /dev/null +++ b/src/pages/docs/cli/apps/channel-rules/delete.mdx @@ -0,0 +1,72 @@ +--- +title: "ably apps channel-rules delete" +meta_description: "Delete a channel rule from an Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, channel rules, delete rule, ably apps channel-rules delete" +--- + + +```shell +ably apps channel-rules delete [flags] +``` + + +Use the `ably apps channel-rules delete` command to permanently remove a [channel rule](/docs/channels/channel-rules-namespaces) from an Ably app. This action cannot be undone and will remove all configured behaviors for channels matching the rule pattern. + +## Arguments + +### `` + +The name or ID of the channel rule to delete, for example: `chat` or `/gfgdchvj`. + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably apps channel-rules delete` command supports: + +### `--app` + +App ID or name to delete the channel rule from. If not specified, uses the current app from your CLI configuration. + +### `--force | -f` + +Force deletion without confirmation prompt. Use with caution as this action is irreversible. + +## Global flags + +The following global flags are supported using the `ably apps channel-rules delete` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Delete a channel rule with confirmation: + +```shell +ably apps channel-rules delete chat +``` + +Delete a channel rule from a specific app: + +```shell +ably apps channel-rules delete events --app "My App" +``` + +Delete a channel rule without confirmation: + +```shell +ably apps channel-rules delete notifications --force +``` + +Delete a channel rule with JSON output: + +```shell +ably apps channel-rules delete chat --json +``` diff --git a/src/pages/docs/cli/apps/channel-rules/index.mdx b/src/pages/docs/cli/apps/channel-rules/index.mdx new file mode 100644 index 0000000000..aff93d8cd1 --- /dev/null +++ b/src/pages/docs/cli/apps/channel-rules/index.mdx @@ -0,0 +1,18 @@ +--- +title: "ably apps channel-rules" +meta_description: "Manage Ably channel rules (namespaces) using the CLI." +meta_keywords: "ably cli, cli, apps, channel rules, namespaces, ably apps channel-rules" +--- + +Use the `ably apps channel-rules` command group to manage [channel rules](/docs/channels/channel-rules-namespaces) (also known as namespaces) for your Ably applications. Channel rules allow you to configure permissions, persistence, and other settings for groups of channels based on naming patterns. + +## Subcommands + +The following commands are used to manage channel rules: + +| Command | Description | +| ------- | ----------- | +| [`ably apps channel-rules create`](/docs/cli/apps/channel-rules/create) | Create a channel rule for an app. | +| [`ably apps channel-rules delete`](/docs/cli/apps/channel-rules/delete) | Delete a channel rule from an app. | +| [`ably apps channel-rules list`](/docs/cli/apps/channel-rules/list) | List channel rules for an app. | +| [`ably apps channel-rules update`](/docs/cli/apps/channel-rules/update) | Update a channel rule for an app. | \ No newline at end of file diff --git a/src/pages/docs/cli/apps/channel-rules/list.mdx b/src/pages/docs/cli/apps/channel-rules/list.mdx new file mode 100644 index 0000000000..e45a70cd24 --- /dev/null +++ b/src/pages/docs/cli/apps/channel-rules/list.mdx @@ -0,0 +1,95 @@ +--- +title: "ably apps channel-rules list" +meta_description: "List channel rules for an Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, channel rules, list rules, ably apps channel-rules list" +--- + + +```shell +ably apps channel-rules list [flags] +``` + + +Use the `ably apps channel-rules list` command to display all [channel rules](/docs/channels/channel-rules-namespaces) configured for an Ably app. This shows the configuration settings for each rule including persistence, authentication, and other channel behaviors. + +## Global flags + +The following global flags are supported using the `ably apps channel-rules list` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably apps channel-rules list` command displays: + +| Property | Description | +| -------- | ----------- | +| **Rule Count** | Total number of channel rules found | +| **Channel Rule ID** | The unique identifier for each rule | +| **Persisted** | Whether messages are persisted for channels matching this rule | +| **Push Enabled** | Whether push notifications are enabled | +| **Authenticated** | Whether clients must be authenticated | +| **Persist Last Message** | Whether only the last message is persisted | +| **Populate Channel Registry** | Whether to populate the channel registry | +| **Batching Enabled** | Whether message batching is enabled | +| **Conflation Enabled** | Whether message conflation is enabled | +| **TLS Only** | Whether TLS is enforced | +| **Created** | When the rule was created | +| **Updated** | When the rule was last updated | + +## Examples + +List all channel rules for the current app: + +```shell +ably apps channel-rules list +``` + +``` +Found 3 channel rules: + +Channel Rule ID: /gfgdchvj + Persisted: No + Push Enabled: No + Authenticated: No + Persist Last Message: No + Populate Channel Registry: No + Batching Enabled: No + Conflation Enabled: No + TLS Only: No + Created: 10/25/2024, 11:31:56 AM + Updated: 10/25/2024, 11:31:56 AM + +Channel Rule ID: namespace + Persisted: ✓ Yes + Push Enabled: No + Authenticated: No + Persist Last Message: ✓ Yes + Populate Channel Registry: No + Batching Enabled: No + Conflation Enabled: No + TLS Only: No + Created: 5/30/2025, 10:01:55 AM + Updated: 5/30/2025, 10:01:55 AM +``` + +List channel rules in JSON format: + +```shell +ably apps channel-rules list --json +``` + +List channel rules in formatted JSON: + +```shell +ably apps channel-rules list --pretty-json +``` diff --git a/src/pages/docs/cli/apps/channel-rules/update.mdx b/src/pages/docs/cli/apps/channel-rules/update.mdx new file mode 100644 index 0000000000..62776c4728 --- /dev/null +++ b/src/pages/docs/cli/apps/channel-rules/update.mdx @@ -0,0 +1,110 @@ +--- +title: "ably apps channel-rules update" +meta_description: "Update a channel rule for an Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, channel rules, update rule, ably apps channel-rules update" +--- + + +```shell +ably apps channel-rules update [flags] +``` + + +Use the `ably apps channel-rules update` command to modify an existing [channel rule](/docs/channels/channel-rules-namespaces) for an Ably app. You can update various settings including persistence, authentication, and push notification configurations. + +## Arguments + +### `` + +The name or ID of the channel rule to update, for example: `chat` or `/gfgdchvj`. + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably apps channel-rules update` command supports: + +### `--app` + +App ID or name to update the channel rule in. If not specified, uses the current app from your CLI configuration. + +### `--authenticated` / `--no-authenticated` + +Enable or disable authentication requirement for channels matching this rule. + +### `--persisted` / `--no-persisted` + +Enable or disable message persistence to [message history](/docs/storage-history/history) for channels matching this rule. + +### `--persist-last` / `--no-persist-last` + +Enable or disable persisting only the last message on channels matching this rule. + +### `--push-enabled` / `--no-push-enabled` + +Enable or disable [push notifications](/docs/push) for channels matching this rule. + +### `--tls-only` / `--no-tls-only` + +Enable or disable TLS enforcement for channels matching this rule. + +### `--populate-channel-registry` / `--no-populate-channel-registry` + +Enable or disable populating the channel registry for channels matching this rule. + +### `--batching-enabled` / `--no-batching-enabled` + +Enable or disable message batching for channels matching this rule. + +### `--batching-interval` + +Set the batching interval for messages on channels matching this rule (in milliseconds). + +### `--conflation-enabled` / `--no-conflation-enabled` + +Enable or disable [delta compression](/docs/channels/channel-parameters/deltas) (conflation) for messages on channels matching this rule. + +### `--conflation-interval` + +Set the conflation interval for messages on channels matching this rule (in milliseconds). + +### `--conflation-key` + +Set the conflation key for messages on channels matching this rule. + +### `--expose-time-serial` / `--no-expose-time-serial` + +Enable or disable exposing the time serial for messages on channels matching this rule. + +## Global flags + +The following global flags are supported using the `ably apps channel-rules update` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Enable persistence for a channel rule: + +```shell +ably apps channel-rules update chat --persisted +``` + +Disable push notifications for a channel rule: + +```shell +ably apps channel-rules update events --push-enabled=false +``` + +Update multiple settings for a channel rule: + +```shell +ably apps channel-rules update notifications --persisted --push-enabled --app "My App" +``` diff --git a/src/pages/docs/cli/apps/create.mdx b/src/pages/docs/cli/apps/create.mdx new file mode 100644 index 0000000000..e5529da076 --- /dev/null +++ b/src/pages/docs/cli/apps/create.mdx @@ -0,0 +1,63 @@ +--- +title: "ably apps create" +meta_description: "Create a new Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, create app, ably apps create" +--- + + +```shell +ably apps create --name [flags] +``` + + +Use the `ably apps create` command to create a new Ably application. This will set up a new app with default settings that you can then configure and use for your realtime messaging needs. + +## Flags + +You can optionally pass the following flags to the `ably apps create` command: + +### `--name` + +The name for the new app. This is a required field that will be used to identify your application. + +### `--tls-only` + +Configure the app to accept TLS connections only. This enhances security by ensuring all connections are encrypted. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps create` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Create a new app with a basic configuration: + + +```shell +ably apps create --name "My New App" +``` + + +Create a new app that accepts only TLS connections: + + +```shell +ably apps create --name "My New App" --tls-only +``` + + diff --git a/src/pages/docs/cli/apps/current.mdx b/src/pages/docs/cli/apps/current.mdx new file mode 100644 index 0000000000..d022febb11 --- /dev/null +++ b/src/pages/docs/cli/apps/current.mdx @@ -0,0 +1,68 @@ +--- +title: "ably apps current" +meta_description: "Show the currently selected Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, current app, ably apps current" +--- + + +```shell +ably apps current [flags] +``` + + +Use the `ably apps current` command to display information about the currently selected Ably app. This shows details about the app that is active in your CLI session, including the app ID, name, and associated API key. + +## Flags + +You can optionally pass the following flags to the `ably apps current` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps current` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably apps current` command displays: + +| Property | Description | +| -------- | ----------- | +| **Account** | The account name and ID | +| **App** | The current app name and ID | +| **API Key** | The API key name being used | +| **Key Label** | The descriptive label of the current API key | + +## Examples + +Show current app information: + + +```shell +ably apps current +``` + + +**Output:** + +```text +Account: Ably (a12B3c) +App: example-app (Ab1CdE) +API Key: Ab1CdE.F2ghIJ +Key Label: Example Key +``` + + diff --git a/src/pages/docs/cli/apps/delete.mdx b/src/pages/docs/cli/apps/delete.mdx new file mode 100644 index 0000000000..b9d009ed36 --- /dev/null +++ b/src/pages/docs/cli/apps/delete.mdx @@ -0,0 +1,96 @@ +--- +title: "ably apps delete" +meta_description: "Delete an Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, delete app, ably apps delete" +--- + + +```shell +ably apps delete [ID] [flags] +``` + + +Use the `ably apps delete` command to permanently remove an Ably application. This action cannot be undone and will delete all associated data, channels, and configuration. + +## Arguments + +Pass the following arguments to the `ably apps delete` command: + +### `[ID]` + +The App ID to delete, for example: `Ab1CdE`. + +If not provided, uses the current app from your CLI configuration. + +## Flags + +You can optionally pass the following flags to the `ably apps delete` command: + +### `--app` + +App ID to delete. This flag overrides both the argument and current app setting. + +### `--force | -f` + +Skip the confirmation prompt and delete the app immediately. Use with extreme caution as this action is irreversible. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps delete` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Delete the current app (with confirmation): + + +```shell +ably apps delete +``` + + +Delete a specific app by ID: + + +```shell +ably apps delete app-id +``` + + +Delete an app using the --app flag: + + +```shell +ably apps delete --app app-id +``` + + +Delete an app without confirmation: + + +```shell +ably apps delete app-id --force +``` + + +Delete an app with JSON output: + + +```shell +ably apps delete app-id --json +``` + diff --git a/src/pages/docs/cli/apps/index.mdx b/src/pages/docs/cli/apps/index.mdx new file mode 100644 index 0000000000..7cf5a22cbd --- /dev/null +++ b/src/pages/docs/cli/apps/index.mdx @@ -0,0 +1,40 @@ +--- +title: "ably apps" +meta_description: "Manage Ably apps using the CLI." +meta_keywords: "ably cli, cli, apps, app management, ably apps" +--- + +Use the `ably apps` command group to manage your Ably applications. These commands allow you to create, configure, and monitor your apps, as well as manage their settings and channel rules. + +## Subcommands + +The following commands are used to manage apps: + +| Command | Description | +| ------- | ----------- | +| [`ably apps create`](/docs/cli/apps/create) | Create a new Ably app. | +| [`ably apps current`](/docs/cli/apps/current) | Show the currently selected app. | +| [`ably apps delete`](/docs/cli/apps/delete) | Delete an existing app. | +| [`ably apps list`](/docs/cli/apps/list) | List all apps in the current account. | +| [`ably apps set-apns-p12`](/docs/cli/apps/set-apns-p12) | Upload Apple Push Notification Service P12 certificate. | +| [`ably apps stats`](/docs/cli/apps/stats) | Get app statistics with optional live updates. | +| [`ably apps switch`](/docs/cli/apps/switch) | Switch to a different Ably app. | +| [`ably apps update`](/docs/cli/apps/update) | Update an app's configuration. | + +The following commands are used to manage channel rules: + +| Command | Description | +| ------- | ----------- | +| [`ably apps channel-rules`](/docs/cli/apps/channel-rules) | Manage channel rules (namespaces) for apps. | +| [`ably apps channel-rules create`](/docs/cli/apps/channel-rules/create) | Create a channel rule for an app. | +| [`ably apps channel-rules delete`](/docs/cli/apps/channel-rules/delete) | Delete a channel rule from an app. | +| [`ably apps channel-rules list`](/docs/cli/apps/channel-rules/list) | List channel rules for an app. | +| [`ably apps channel-rules update`](/docs/cli/apps/channel-rules/update) | Update a channel rule for an app. | + +The following commands are used to manage app logs: + +| Command | Description | +| ------- | ----------- | +| [`ably apps logs`](/docs/cli/apps/logs) | Stream or retrieve app logs. | +| [`ably apps logs history`](/docs/cli/apps/logs/history) | Get app log history. | +| [`ably apps logs subscribe`](/docs/cli/apps/logs/subscribe) | Subscribe to app logs. | \ No newline at end of file diff --git a/src/pages/docs/cli/apps/list.mdx b/src/pages/docs/cli/apps/list.mdx new file mode 100644 index 0000000000..2643859cdc --- /dev/null +++ b/src/pages/docs/cli/apps/list.mdx @@ -0,0 +1,89 @@ +--- +title: "ably apps list" +meta_description: "List all Ably apps in the current account using the CLI." +meta_keywords: "ably cli, cli, apps, app list, ably apps list" +--- + + +```shell +ably apps list [flags] +``` + + +Use the `ably apps list` command to display all Ably apps in your current account. This provides an overview of all your applications with their key details and settings. + +## Flags + +You can optionally pass the following flags to the `ably apps list` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps list` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably apps list` command displays: + +| Property | Description | +| -------- | ----------- | +| **Context** | Current account, app, and key being used | +| **App Count** | Total number of apps found | +| **App ID** | The unique identifier for each app | +| **Name** | The app name | +| **Status** | Whether the app is enabled or disabled | +| **Account ID** | The account the app belongs to | +| **TLS Only** | Whether the app accepts only TLS connections | +| **Created** | When the app was created | +| **Updated** | When the app was last updated | +| **Current Indicator** | Shows which app is currently selected | + +## Examples + +List all apps in the account: + + +```shell +ably apps list +``` + + +**Output:** + +```text +Using: Account=Ably (a12B3c) • App=example-app (Ab1CdE) • Key=Root (Ab1CdE.F2ghIJ) + +Found 14 apps: + +▶ App ID: Ab1CdE (current) + Name: example-app + Status: enabled + Account ID: a12B3c + TLS Only: Yes + Created: 6/12/2024, 12:53:58 PM + Updated: 6/12/2024, 12:53:59 PM + + App ID: kMlJow + Name: chat-test + Status: enabled + Account ID: a12B3c + TLS Only: Yes + Created: 11/23/2023, 3:19:41 PM + Updated: 11/23/2023, 3:19:42 PM +``` + + diff --git a/src/pages/docs/cli/apps/logs/history.mdx b/src/pages/docs/cli/apps/logs/history.mdx new file mode 100644 index 0000000000..6255e21697 --- /dev/null +++ b/src/pages/docs/cli/apps/logs/history.mdx @@ -0,0 +1,80 @@ +--- +title: "ably apps logs history" +meta_description: "Get app log history using the CLI." +meta_keywords: "ably cli, cli, apps, logs, log history, ably apps logs history" +--- + + +```shell +ably apps logs history [flags] +``` + + +Use the `ably apps logs history` command to retrieve historical log messages from your Ably app. This provides access to past log entries for debugging and monitoring purposes. + + + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably apps logs history` command supports: + +### `--direction` + +Direction of message retrieval. Options are: +- `backwards` - Retrieve messages from newest to oldest (default) +- `forwards` - Retrieve messages from oldest to newest + +### `--limit` + +Maximum number of log messages to retrieve. The default is `100`. + +## Global flags + +The following global flags are supported using the `ably apps logs history` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Get recent app log history: + +```shell +ably apps logs history +``` + +Get the last 20 log messages: + +```shell +ably apps logs history --limit 20 +``` + +Get log history in chronological order: + +```shell +ably apps logs history --direction forwards +``` + +Get log history in JSON format: + +```shell +ably apps logs history --json +``` + +Get formatted JSON output: + +```shell +ably apps logs history --pretty-json +``` + +For complete documentation on app logs, see [`ably logs app history`](/docs/cli/logs/app/history). diff --git a/src/pages/docs/cli/apps/logs/index.mdx b/src/pages/docs/cli/apps/logs/index.mdx new file mode 100644 index 0000000000..583b8029c2 --- /dev/null +++ b/src/pages/docs/cli/apps/logs/index.mdx @@ -0,0 +1,20 @@ +--- +title: "ably apps logs" +meta_description: "Stream or retrieve app logs using the CLI." +meta_keywords: "ably cli, cli, apps, logs, app logs, ably apps logs" +--- + +Use the `ably apps logs` command group to stream or retrieve logs from your Ably app. These commands provide access to app-wide logging information for monitoring and debugging purposes. + +## Subcommands + +The following commands are used to access app logs: + +| Command | Description | +| ------- | ----------- | +| [`ably apps logs history`](/docs/cli/apps/logs/history) | Get app log history. | +| [`ably apps logs subscribe`](/docs/cli/apps/logs/subscribe) | Subscribe to app logs. | + + \ No newline at end of file diff --git a/src/pages/docs/cli/apps/logs/subscribe.mdx b/src/pages/docs/cli/apps/logs/subscribe.mdx new file mode 100644 index 0000000000..3a00666944 --- /dev/null +++ b/src/pages/docs/cli/apps/logs/subscribe.mdx @@ -0,0 +1,56 @@ +--- +title: "ably apps logs subscribe" +meta_description: "Subscribe to app logs using the CLI." +meta_keywords: "ably cli, cli, apps, logs, subscribe logs, ably apps logs subscribe" +--- + + +```shell +ably apps logs subscribe [flags] +``` + + +Use the `ably apps logs subscribe` command to subscribe to realtime log messages from your Ably app. This provides a live stream of log events for monitoring and debugging purposes. + + + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably apps logs subscribe` command supports: + +### `--rewind` + +Number of historical log messages to retrieve when starting the subscription. This allows you to see recent context before new logs arrive. + +## Global flags + +The following global flags are supported using the `ably apps logs subscribe` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Subscribe to app logs: + +```shell +ably apps logs subscribe +``` + +Subscribe to app logs with historical context: + +```shell +ably apps logs subscribe --rewind 10 +``` + +For complete documentation on app logs, see [`ably logs app subscribe`](/docs/cli/logs/app/subscribe). diff --git a/src/pages/docs/cli/apps/set-apns-p12.mdx b/src/pages/docs/cli/apps/set-apns-p12.mdx new file mode 100644 index 0000000000..bcf2705740 --- /dev/null +++ b/src/pages/docs/cli/apps/set-apns-p12.mdx @@ -0,0 +1,76 @@ +--- +title: "ably apps set-apns-p12" +meta_description: "Upload Apple Push Notification Service P12 certificate for an app using the CLI." +meta_keywords: "ably cli, cli, apps, apns, p12, certificate, push notifications, ably apps set-apns-p12" +--- + + +```shell +ably apps set-apns-p12 --certificate [flags] +``` + + +Use the `ably apps set-apns-p12` command to upload an Apple Push Notification Service (APNS) P12 certificate for an Ably app. This enables [push notifications](/docs/push) to iOS devices through Apple's push notification service. + +## Arguments + +Pass the following arguments to the `ably apps set-apns-p12` command: + +### `` + +The App ID to set the APNS certificate for, for example: `Ab1CdE`. + +## Flags + +You can optionally pass the following flags to the `ably apps set-apns-p12` command: + +### `--certificate` + +Path to the P12 certificate file. This is a required field that specifies the location of your APNS certificate. + +### `--password` + +Password for the P12 certificate, if the certificate file is password-protected. + +### `--use-for-sandbox` + +Configure whether to use this certificate for the APNS sandbox environment instead of production. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps set-apns-p12` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Upload a P12 certificate: + +```shell +ably apps set-apns-p12 app-id --certificate /path/to/certificate.p12 +``` + +Upload a password-protected P12 certificate: + +```shell +ably apps set-apns-p12 app-id --certificate /path/to/certificate.p12 --password "YOUR_CERTIFICATE_PASSWORD" +``` + +Upload a certificate for the APNS sandbox environment: + +```shell +ably apps set-apns-p12 app-id --certificate /path/to/certificate.p12 --use-for-sandbox +``` diff --git a/src/pages/docs/cli/apps/stats.mdx b/src/pages/docs/cli/apps/stats.mdx new file mode 100644 index 0000000000..07c91a33eb --- /dev/null +++ b/src/pages/docs/cli/apps/stats.mdx @@ -0,0 +1,116 @@ +--- +title: "ably apps stats" +meta_description: "Get app statistics with optional live updates using the CLI." +meta_keywords: "ably cli, cli, apps, app stats, statistics, ably apps stats" +--- + + +```shell +ably apps stats [ID] [flags] +``` + + +Use the `ably apps stats` command to retrieve detailed usage statistics for an Ably app. This provides metrics on connections, channels, messages, API requests, and more, with options for historical data and live updates. + +## Arguments + +Pass the following arguments to the `ably apps stats` command: + +### `[ID]` + +The App ID to get statistics for, for example: `Ab1CdE`. + +If not provided, uses the current app from your CLI configuration. + +## Flags + +You can optionally pass the following flags to the `ably apps stats` command: + +### `--start` + +Start time in milliseconds since epoch for historical stats retrieval. + +### `--end` + +End time in milliseconds since epoch for historical stats retrieval. + +### `--unit` + +Time unit for statistics aggregation. Options are `minute`, `hour`, `day`, or `month`. The default is `minute`. + +### `--limit` + +Maximum number of statistics records to return. The default is `10`. + +### `--live` + +Subscribe to live statistics updates using minute intervals. + +### `--interval` + +Polling interval in seconds when using `--live` mode. The default is `6` seconds. + +### `--debug` + +Show debug information for live statistics polling. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps stats` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Get recent app statistics: + + +```shell +ably apps stats +``` + + +Get statistics for a specific app: + + +```shell +ably apps stats app-id +``` + + +Get hourly statistics: + + +```shell +ably apps stats --unit hour +``` + + +Get statistics for a specific time range: + + +```shell +ably apps stats app-id --start 1618005600000 --end 1618091999999 +``` + + +Subscribe to live statistics updates: + + +```shell +ably apps stats --live +``` + diff --git a/src/pages/docs/cli/apps/switch.mdx b/src/pages/docs/cli/apps/switch.mdx new file mode 100644 index 0000000000..7973525e5c --- /dev/null +++ b/src/pages/docs/cli/apps/switch.mdx @@ -0,0 +1,64 @@ +--- +title: "ably apps switch" +meta_description: "Switch to a different Ably app using the CLI." +meta_keywords: "ably cli, cli, apps, switch app, ably apps switch" +--- + + +```shell +ably apps switch [APPID] [flags] +``` + + +Use the `ably apps switch` command to change the currently active Ably app in your CLI session. This allows you to work with different apps without needing to reconfigure your authentication. + +## Arguments + +Pass the following arguments to the `ably apps switch` command: + +### `[APPID]` + +The ID of the app to switch to, for example: `Ab1CdE`. + +If not provided, the CLI will prompt you to select from available apps. + +## Flags + +You can optionally pass the following flags to the `ably apps switch` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps switch` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Switch to a specific app: + + +```shell +ably apps switch APP_ID +``` + + +Switch apps interactively (prompts for selection): + + +```shell +ably apps switch +``` + diff --git a/src/pages/docs/cli/apps/update.mdx b/src/pages/docs/cli/apps/update.mdx new file mode 100644 index 0000000000..d5af02fcdc --- /dev/null +++ b/src/pages/docs/cli/apps/update.mdx @@ -0,0 +1,78 @@ +--- +title: "ably apps update" +meta_description: "Update an Ably app's configuration using the CLI." +meta_keywords: "ably cli, cli, apps, update app, ably apps update" +--- + + +```shell +ably apps update [flags] +``` + + +Use the `ably apps update` command to modify the configuration of an existing Ably application. You can update the app name and TLS-only settings. + +## Arguments + +Pass the following arguments to the `ably apps update` command: + +### `` + +The App ID to update, for example: `Ab1CdE`. + +## Flags + +You can optionally pass the following flags to the `ably apps update` command: + +### `--name` + +New name for the app. This updates the display name used to identify your application. + +### `--tls-only` + +Configure whether the app should accept TLS connections only. This enhances security by ensuring all connections are encrypted. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably apps update` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Update an app's name: + + +```shell +ably apps update app-id --name "Updated App Name" +``` + + +Enable TLS-only mode for an app: + + +```shell +ably apps update app-id --tls-only +``` + + +Update both name and TLS setting: + + +```shell +ably apps update app-id --name "Updated App Name" --tls-only +``` + diff --git a/src/pages/docs/cli/auth/index.mdx b/src/pages/docs/cli/auth/index.mdx new file mode 100644 index 0000000000..e3c10266ab --- /dev/null +++ b/src/pages/docs/cli/auth/index.mdx @@ -0,0 +1,30 @@ +--- +title: "ably auth" +meta_description: "Manage authentication, API keys and tokens using the CLI." +meta_keywords: "ably cli, cli, auth, authentication, api keys, tokens, ably auth" +--- + +Use the `ably auth` command group to manage authentication, [API keys](/docs/auth/api-keys), and [tokens](/docs/auth/tokens) for your Ably applications. These commands allow you to create and manage API keys, issue tokens, and handle authentication credentials. + +## Subcommands + +The following commands are used to manage authentication and tokens: + +| Command | Description | +| ------- | ----------- | +| [`ably auth issue-ably-token`](/docs/cli/auth/issue-ably-token) | Create an Ably Token with specified capabilities. | +| [`ably auth issue-jwt-token`](/docs/cli/auth/issue-jwt-token) | Create an Ably JWT Token with specified capabilities. | +| [`ably auth revoke-token`](/docs/cli/auth/revoke-token) | Revoke a previously issued token. | + +The following commands are used to manage API keys: + +| Command | Description | +| ------- | ----------- | +| [`ably auth keys`](/docs/cli/auth/keys) | API key management commands. | +| [`ably auth keys create`](/docs/cli/auth/keys/create) | Create a new API key for an app. | +| [`ably auth keys current`](/docs/cli/auth/keys/current) | Show the current API key for the selected app. | +| [`ably auth keys get`](/docs/cli/auth/keys/get) | Get details for a specific API key. | +| [`ably auth keys list`](/docs/cli/auth/keys/list) | List all API keys in the app. | +| [`ably auth keys revoke`](/docs/cli/auth/keys/revoke) | Revoke an API key (permanently disables it). | +| [`ably auth keys switch`](/docs/cli/auth/keys/switch) | Switch to a different API key for the current app. | +| [`ably auth keys update`](/docs/cli/auth/keys/update) | Update an API key's properties. | \ No newline at end of file diff --git a/src/pages/docs/cli/auth/issue-ably-token.mdx b/src/pages/docs/cli/auth/issue-ably-token.mdx new file mode 100644 index 0000000000..4e78bbce3a --- /dev/null +++ b/src/pages/docs/cli/auth/issue-ably-token.mdx @@ -0,0 +1,128 @@ +--- +title: "ably auth issue-ably-token" +meta_description: "Create an Ably Token with specified capabilities using the CLI." +meta_keywords: "ably cli, cli, auth, ably token, token creation, ably auth issue-ably-token" +--- + + +```shell +ably auth issue-ably-token [flags] +``` + + +Use the `ably auth issue-ably-token` command to create an [Ably Token](/docs/auth/tokens#ably-tokens) with specified capabilities. Ably Tokens are short-lived authentication tokens that can be issued for specific capabilities and client IDs. + +## Flags + +You can optionally pass the following flags to the `ably auth issue-ably-token` command: + +### `--app` + +The App ID to create the token for. If not specified, uses the current app from your CLI configuration. + +### `--capability` + +Capabilities JSON string defining what operations the token allows. The default is `{"*":["*"]}` which grants all capabilities on all channels. + +Examples: +- `{"*":["*"]}` - All capabilities on all channels +- `{"channel1":["publish","subscribe"]}` - Publish and subscribe on channel1 +- `{"chat:*":["publish","subscribe"], "status:*":["subscribe"]}` - Mixed capabilities + +### `--client-id` + +Client ID to associate with the token. Use `"none"` to explicitly issue a token with no client ID, otherwise a default will be generated. + +### `--ttl` + +Time to live in seconds for the token. The default is `3600` (1 hour). + +### `--token-only` + +Output only the token string without any formatting or additional information. Useful for scripting and piping to other commands. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably auth issue-ably-token` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably auth issue-ably-token` command displays: + +| Property | Description | +| -------- | ----------- | +| **Token** | The generated Ably Token string | +| **Token Details** | Information about capabilities, client ID, and expiration (unless `--token-only` is used) | + +## Examples + +Issue a token with default capabilities: + + +```shell +ably auth issue-ably-token +``` + + +Issue a token with specific capabilities: + + +```shell +ably auth issue-ably-token --capability '{"*":["*"]}' +``` + + +Issue a token with mixed capabilities and 1 hour TTL: + + +```shell +ably auth issue-ably-token --capability '{"chat:*":["publish","subscribe"], "status:*":["subscribe"]}' --ttl 3600 +``` + + +Issue a token for a specific client ID with 24 hour TTL: + + +```shell +ably auth issue-ably-token --client-id client123 --ttl 86400 +``` + + +Issue a token with no client ID: + + +```shell +ably auth issue-ably-token --client-id "none" --ttl 3600 +``` + + +Get only the token string (useful for scripting): + + +```shell +ably auth issue-ably-token --token-only +``` + + +Use the token directly in another command: + + +```shell +ably channels publish --token "$(ably auth issue-ably-token --token-only)" my-channel "Hello" +``` + diff --git a/src/pages/docs/cli/auth/issue-jwt-token.mdx b/src/pages/docs/cli/auth/issue-jwt-token.mdx new file mode 100644 index 0000000000..d0b0129e7f --- /dev/null +++ b/src/pages/docs/cli/auth/issue-jwt-token.mdx @@ -0,0 +1,116 @@ +--- +title: "ably auth issue-jwt-token" +meta_description: "Create an Ably JWT Token with specified capabilities using the CLI." +meta_keywords: "ably cli, cli, auth, jwt token, token creation, ably auth issue-jwt-token" +--- + + +```shell +ably auth issue-jwt-token [flags] +``` + + +Use the `ably auth issue-jwt-token` command to create an [Ably JWT Token](/docs/auth/tokens#jwt-tokens) with specified capabilities. JWT Tokens are JSON Web Tokens that provide a standardized way to securely transmit authentication information. + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably auth issue-jwt-token` command supports: + +### `--app` + +The App ID to create the token for. If not specified, uses the current app from your CLI configuration. + +### `--capability` + +Capabilities JSON string defining what operations the token allows. The default is `{"*":["*"]}` which grants all capabilities on all channels. + +Examples: +- `{"*":["*"]}` - All capabilities on all channels +- `{"channel1":["publish","subscribe"]}` - Publish and subscribe on channel1 +- `{"chat:*":["publish","subscribe"], "status:*":["subscribe"]}` - Mixed capabilities + +### `--client-id` + +Client ID to associate with the token. Use `"none"` to explicitly issue a token with no client ID, otherwise a default will be generated. + +### `--ttl` + +Time to live in seconds for the token. The default is `3600` (1 hour). + +### `--token-only` + +Output only the token string without any formatting or additional information. Useful for scripting and piping to other commands. + +## Global flags + +The following global flags are supported using the `ably auth issue-jwt-token` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably auth issue-jwt-token` command displays: + +| Property | Description | +| -------- | ----------- | +| **Token** | The generated JWT Token string | +| **Token Details** | Information about capabilities, client ID, and expiration (unless `--token-only` is used) | + +## Examples + +Issue a JWT token with default capabilities: + + +```shell +ably auth issue-jwt-token +``` + + +Issue a JWT token with specific capabilities: + + +```shell +ably auth issue-jwt-token --capability '{"*":["*"]}' +``` + + +Issue a JWT token with mixed capabilities and 1 hour TTL: + + +```shell +ably auth issue-jwt-token --capability '{"chat:*":["publish","subscribe"], "status:*":["subscribe"]}' --ttl 3600 +``` + + +Issue a JWT token for a specific client ID with 24 hour TTL: + + +```shell +ably auth issue-jwt-token --client-id client123 --ttl 86400 +``` + + +Get only the JWT token string (useful for scripting): + + +```shell +ably auth issue-jwt-token --token-only +``` + + +Use the JWT token directly in another command: + + +```shell +ably channels publish --token "$(ably auth issue-jwt-token --token-only)" my-channel "Hello" +``` + diff --git a/src/pages/docs/cli/auth/keys/create.mdx b/src/pages/docs/cli/auth/keys/create.mdx new file mode 100644 index 0000000000..db6e4d6f52 --- /dev/null +++ b/src/pages/docs/cli/auth/keys/create.mdx @@ -0,0 +1,103 @@ +--- +title: "ably auth keys create" +meta_description: "Create a new API key for an Ably app using the CLI." +meta_keywords: "ably cli, cli, auth, api key, create key, ably auth keys create" +--- + + +```shell +ably auth keys create --name [flags] +``` + + +Use the `ably auth keys create` command to create a new [API key](/docs/auth/api-keys) for an Ably app. API keys provide authentication credentials with configurable capabilities for accessing Ably services. + +## Flags + +You can optionally pass the following flags to the `ably auth keys create` command: + +### `--name` + +The name/label for the new API key. This is a required field that helps identify the key's purpose. + +### `--app` + +The App ID to create the key for. If not specified, uses the current app from your CLI configuration. + +### `--capabilities` + +Capability object as a JSON string defining what operations the key allows. The default is `{"*":["*"]}` which grants all capabilities on all channels. + +Examples: +- `'{"*":["*"]}'` - All capabilities on all channels +- `'{"channel:*":["publish"]}'` - Publish capability on channels matching pattern +- `'{"channel1":["publish","subscribe"],"channel2":["history"]}'` - Mixed capabilities + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably auth keys create` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Create a key with default capabilities: + +```shell +ably auth keys create --name "My New Key" +``` + +Create a key for a specific app: + +```shell +ably auth keys create --name "My New Key" --app APP_ID +``` + +Create a key with all capabilities: + +```shell +ably auth keys create --name "My New Key" --capabilities '{"*":["*"]}' +``` + +Create a key with specific channel capabilities: + +```shell +ably auth keys create --name "My New Key" --capabilities '{"channel1":["publish","subscribe"],"channel2":["history"]}' +``` + +Create a key with pattern-based capabilities: + +```shell +ably auth keys create --name "My New Key" --capabilities '{"channel:*":["publish"]}' +``` + +Create a key with mixed capabilities: + +```shell +ably auth keys create --name "My New Key" --capabilities '{"channel:chat-*":["subscribe"],"channel:updates":["publish"]}' +``` + +Create a key with JSON output: + +```shell +ably auth keys create --name "My New Key" --json +``` + +Create a key with formatted JSON output: + +```shell +ably auth keys create --name "My New Key" --pretty-json +``` diff --git a/src/pages/docs/cli/auth/keys/current.mdx b/src/pages/docs/cli/auth/keys/current.mdx new file mode 100644 index 0000000000..901fcdce6a --- /dev/null +++ b/src/pages/docs/cli/auth/keys/current.mdx @@ -0,0 +1,82 @@ +--- +title: "ably auth keys current" +meta_description: "Show the current API key for the selected app using the CLI." +meta_keywords: "ably cli, cli, auth, api key, current key, ably auth keys current" +--- + + +```shell +ably auth keys current [flags] +``` + + +Use the `ably auth keys current` command to display information about the currently active [API key](/docs/auth/api-keys) for the selected app. This shows details about the key being used for authentication with Ably services. + +## Flags + +You can optionally pass the following flags to the `ably auth keys current` command: + +### `--app` + +The App ID to show the current key for. If not specified, uses the current app from your CLI configuration. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably auth keys current` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably auth keys current` command displays: + +| Property | Description | +| -------- | ----------- | +| **Account** | The account name and ID | +| **App** | The app name and ID | +| **API Key** | The key name identifier | +| **Key Value** | The full API key value used for authentication | +| **Key Label** | The descriptive label assigned to the key | + +## Examples + +Show current API key information: + + +```shell +ably auth keys current +``` + + +**Output:** + +```text +Account: Ably (a12B3c) +App: example-app (Ab1CdE) +API Key: Ab1CdE.F2ghIJ +Key Value: Ab1CdE.F2ghIJ:Ab1CdEF2ghIJAb1CdEF2ghIJAb1CdEF2ghIJ +Key Label: Example Key +``` + + +Show current key for a specific app: + + +```shell +ably auth keys current --app APP_ID +``` + + diff --git a/src/pages/docs/cli/auth/keys/get.mdx b/src/pages/docs/cli/auth/keys/get.mdx new file mode 100644 index 0000000000..ca750aed7b --- /dev/null +++ b/src/pages/docs/cli/auth/keys/get.mdx @@ -0,0 +1,70 @@ +--- +title: "ably auth keys get" +meta_description: "Get details for a specific API key using the CLI." +meta_keywords: "ably cli, cli, auth, api key, key details, ably auth keys get" +--- + + +```shell +ably auth keys get [flags] +``` + + +Use the `ably auth keys get` command to retrieve detailed information about a specific [API key](/docs/auth/api-keys). This displays key properties including capabilities, creation date, and current status. + +## Arguments + +### `` + +The key to get details for. This can be either: +- Key name in the format `APP_ID.KEY_ID` (e.g., `Ab1CdE.F2ghIJ`) +- The full API key value + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably auth keys get` command supports: + +### `--app` + +The App ID the key belongs to. If not specified, uses the current app from your CLI configuration. This is useful when providing only the KEY_ID portion. + +## Global flags + +The following global flags are supported using the `ably auth keys get` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Get key details using full key name: + +```shell +ably auth keys get APP_ID.KEY_ID +``` + +Get key details using KEY_ID with app flag: + +```shell +ably auth keys get KEY_ID --app APP_ID +``` + +Get key details in JSON format: + +```shell +ably auth keys get APP_ID.KEY_ID --json +``` + +Get key details in formatted JSON: + +```shell +ably auth keys get APP_ID.KEY_ID --pretty-json +``` diff --git a/src/pages/docs/cli/auth/keys/index.mdx b/src/pages/docs/cli/auth/keys/index.mdx new file mode 100644 index 0000000000..875beb9e73 --- /dev/null +++ b/src/pages/docs/cli/auth/keys/index.mdx @@ -0,0 +1,21 @@ +--- +title: "ably auth keys" +meta_description: "Manage Ably API keys using the CLI." +meta_keywords: "ably cli, cli, auth, api keys, key management, ably auth keys" +--- + +Use the `ably auth keys` command group to manage [API keys](/docs/auth/api-keys) for your Ably applications. API keys are used to authenticate with Ably services and can be configured with specific capabilities and restrictions. + +## Subcommands + +The following commands are used to manage API keys: + +| Command | Description | +| ------- | ----------- | +| [`ably auth keys create`](/docs/cli/auth/keys/create) | Create a new API key for an app. | +| [`ably auth keys current`](/docs/cli/auth/keys/current) | Show the current API key for the selected app. | +| [`ably auth keys get`](/docs/cli/auth/keys/get) | Get details for a specific API key. | +| [`ably auth keys list`](/docs/cli/auth/keys/list) | List all API keys in the app. | +| [`ably auth keys revoke`](/docs/cli/auth/keys/revoke) | Revoke an API key (permanently disables it). | +| [`ably auth keys switch`](/docs/cli/auth/keys/switch) | Switch to a different API key for the current app. | +| [`ably auth keys update`](/docs/cli/auth/keys/update) | Update an API key's properties. | \ No newline at end of file diff --git a/src/pages/docs/cli/auth/keys/list.mdx b/src/pages/docs/cli/auth/keys/list.mdx new file mode 100644 index 0000000000..f7d50e5023 --- /dev/null +++ b/src/pages/docs/cli/auth/keys/list.mdx @@ -0,0 +1,97 @@ +--- +title: "ably auth keys list" +meta_description: "List all API keys in an Ably app using the CLI." +meta_keywords: "ably cli, cli, auth, api keys, key list, ably auth keys list" +--- + + +```shell +ably auth keys list [flags] +``` + + +Use the `ably auth keys list` command to display all [API keys](/docs/auth/api-keys) configured for an Ably app. This shows key information including names, labels, capabilities, and which key is currently active. + +## Flags + +You can optionally pass the following flags to the `ably auth keys list` command: + +### `--app` + +The App ID to list keys for. If not specified, uses the current app from your CLI configuration. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably auth keys list` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably auth keys list` command displays: + +| Property | Description | +| -------- | ----------- | +| **Context** | Current account, app, and key being used | +| **Key Count** | Total number of keys found for the app | +| **Key Name** | The key identifier (APP_ID.KEY_ID) | +| **Key Label** | The descriptive label assigned to each key | +| **Capabilities** | The permissions granted to each key | +| **Current Indicator** | Shows which key is currently active | + +## Examples + +List all keys for the current app: + + +```shell +ably auth keys list +``` + + +**Output:** + +```text +Using: Account=Ably (a12B3c) • App=example-app (Ab1CdE) • Key=Root (Ab1CdE.F2ghIJ) + +Found 4 keys for app Ab1CdE: + + Key Name: Ab1CdE.E50WKA + Key Label: claude-cli + Capabilities: [*]* → channel-metadata, history, presence, publish, push-admin, push-subscribe, statistics, subscribe + +▶ Key Name: Ab1CdE.F2ghIJ (current) + Key Label: Example Key + Capabilities: [*]* → annotation-publish, annotation-subscribe, channel-metadata, history, message-delete-any, message-delete-own, message-update-any, message-update-own, object-publish, object-subscribe, presence, privileged-headers, publish, push-admin, push-subscribe, statistics, subscribe + + Key Name: Ab1CdE.f_1Pqw + Key Label: qwedf + Capabilities: channel1 → publish + + Key Name: Ab1CdE.lsxQKA + Key Label: Subscribe only + Capabilities: [*]* → history, presence, publish, subscribe +``` + + +List keys for a specific app: + + +```shell +ably auth keys list --app APP_ID +``` + + diff --git a/src/pages/docs/cli/auth/keys/revoke.mdx b/src/pages/docs/cli/auth/keys/revoke.mdx new file mode 100644 index 0000000000..b4eff3bab5 --- /dev/null +++ b/src/pages/docs/cli/auth/keys/revoke.mdx @@ -0,0 +1,78 @@ +--- +title: "ably auth keys revoke" +meta_description: "Revoke an API key permanently using the CLI." +meta_keywords: "ably cli, cli, auth, api key, revoke key, ably auth keys revoke" +--- + + +```shell +ably auth keys revoke [flags] +``` + + +Use the `ably auth keys revoke` command to permanently disable an [API key](/docs/auth/api-keys). Once revoked, the key can no longer be used for authentication with Ably services. This action cannot be undone. + +## Arguments + +### `` + +The key name to revoke in the format `APP_ID.KEY_ID` (e.g., `Ab1CdE.F2ghIJ`). + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably auth keys revoke` command supports: + +### `--app` + +The App ID the key belongs to. If not specified, uses the current app from your CLI configuration. + +### `--force` + +Skip the confirmation prompt and revoke the key immediately. Use with caution as this action cannot be undone. + +## Global flags + +The following global flags are supported using the `ably auth keys revoke` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Revoke a key with confirmation prompt: + +```shell +ably auth keys revoke APP_ID.KEY_ID +``` + +Revoke a key using KEY_ID with app flag: + +```shell +ably auth keys revoke KEY_ID --app APP_ID +``` + +Revoke a key without confirmation: + +```shell +ably auth keys revoke APP_ID.KEY_ID --force +``` + +Revoke a key with JSON output: + +```shell +ably auth keys revoke APP_ID.KEY_ID --json +``` + +Revoke a key with formatted JSON output: + +```shell +ably auth keys revoke APP_ID.KEY_ID --pretty-json +``` diff --git a/src/pages/docs/cli/auth/keys/switch.mdx b/src/pages/docs/cli/auth/keys/switch.mdx new file mode 100644 index 0000000000..5851d30eb0 --- /dev/null +++ b/src/pages/docs/cli/auth/keys/switch.mdx @@ -0,0 +1,66 @@ +--- +title: "ably auth keys switch" +meta_description: "Switch to a different API key for the current app using the CLI." +meta_keywords: "ably cli, cli, auth, api key, switch key, ably auth keys switch" +--- + + +```shell +ably auth keys switch [KEYNAMEORVALUE] [flags] +``` + + +Use the `ably auth keys switch` command to change the currently active [API key](/docs/auth/api-keys) for the current app. This allows you to switch between different keys with different capabilities without needing to reconfigure your CLI session. + +## Arguments + +### `[KEYNAMEORVALUE]` + +The key to switch to. This can be either: +- Key name in the format `APP_ID.KEY_ID` (e.g., `Ab1CdE.F2ghIJ`) +- The full API key value + +If not provided, the CLI will prompt you to select from available keys. + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably auth keys switch` command supports: + +### `--app` + +The App ID to switch keys for. If not specified, uses the current app from your CLI configuration. + +## Global flags + +The following global flags are supported using the `ably auth keys switch` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Switch keys interactively (prompts for selection): + +```shell +ably auth keys switch +``` + +Switch to a specific key by name: + +```shell +ably auth keys switch APP_ID.KEY_ID +``` + +Switch using KEY_ID with app flag: + +```shell +ably auth keys switch KEY_ID --app APP_ID +``` diff --git a/src/pages/docs/cli/auth/keys/update.mdx b/src/pages/docs/cli/auth/keys/update.mdx new file mode 100644 index 0000000000..a347b92a3b --- /dev/null +++ b/src/pages/docs/cli/auth/keys/update.mdx @@ -0,0 +1,70 @@ +--- +title: "ably auth keys update" +meta_description: "Update an API key's properties using the CLI." +meta_keywords: "ably cli, cli, auth, api key, update key, ably auth keys update" +--- + + +```shell +ably auth keys update [flags] +``` + + +Use the `ably auth keys update` command to modify the properties of an existing [API key](/docs/auth/api-keys). You can update the key's name and capabilities to change its behavior and permissions. + +## Arguments + +### `` + +The key name to update in the format `APP_ID.KEY_ID` (e.g., `Ab1CdE.F2ghIJ`). + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably auth keys update` command supports: + +### `--app` + +The App ID the key belongs to. If not specified, uses the current app from your CLI configuration. + +### `--name` + +New name/label for the key. This updates the descriptive label used to identify the key. + +### `--capabilities` + +New capabilities for the key as a comma-separated list. This defines what operations the key can perform. + +## Global flags + +The following global flags are supported using the `ably auth keys update` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Update a key's name: + +```shell +ably auth keys update APP_ID.KEY_ID --name "New Name" +``` + +Update a key's capabilities using KEY_ID with app flag: + +```shell +ably auth keys update KEY_ID --app APP_ID --capabilities "publish,subscribe" +``` + +Update both name and capabilities: + +```shell +ably auth keys update APP_ID.KEY_ID --name "New Name" --capabilities "publish,subscribe" +``` diff --git a/src/pages/docs/cli/auth/revoke-token.mdx b/src/pages/docs/cli/auth/revoke-token.mdx new file mode 100644 index 0000000000..f205eeac1d --- /dev/null +++ b/src/pages/docs/cli/auth/revoke-token.mdx @@ -0,0 +1,82 @@ +--- +title: "ably auth revoke-token" +meta_description: "Revoke a previously issued Ably token using the CLI." +meta_keywords: "ably cli, cli, auth, revoke token, token revocation, ably auth revoke-token" +--- + + +```shell +ably auth revoke-token [flags] +``` + + +Use the `ably auth revoke-token` command to revoke a previously issued [Ably Token](/docs/auth/tokens). Once revoked, the token can no longer be used for authentication with Ably services. + +## Arguments + +### `` + +The token to revoke. This can be either an Ably Token or JWT Token that was previously issued. + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably auth revoke-token` command supports: + +### `--app` + +The App ID that the token belongs to. If not specified, uses the current app from your CLI configuration. + +### `--client-id | -c` + +Client ID to revoke tokens for. This allows you to revoke tokens associated with a specific client. + +### `--debug` + +Show debug information during the token revocation process. + +## Global flags + +The following global flags are supported using the `ably auth revoke-token` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Revoke a specific token: + +```shell +ably auth revoke-token TOKEN +``` + +Revoke tokens for a specific client ID: + +```shell +ably auth revoke-token TOKEN --client-id clientid +``` + +Revoke a token with JSON output: + +```shell +ably auth revoke-token TOKEN --json +``` + +Revoke a token with formatted JSON output: + +```shell +ably auth revoke-token TOKEN --pretty-json +``` + +Revoke a token with debug information: + +```shell +ably auth revoke-token TOKEN --debug +``` diff --git a/src/pages/docs/cli/bench/index.mdx b/src/pages/docs/cli/bench/index.mdx new file mode 100644 index 0000000000..4c70f043c3 --- /dev/null +++ b/src/pages/docs/cli/bench/index.mdx @@ -0,0 +1,16 @@ +--- +title: "ably bench" +meta_description: "Performance benchmarking commands for the Ably CLI." +meta_keywords: "ably cli, cli, benchmark, performance, testing, ably bench" +--- + +Use the `ably bench` command group to run performance benchmarking tests against Ably services. These commands help you test the performance characteristics of your Ably implementation. + +## Subcommands + +The following commands are available for benchmarking: + +| Command | Description | +| ------- | ----------- | +| [`ably bench publisher`](/docs/cli/bench/publisher) | Run a publisher benchmark test. | +| [`ably bench subscriber`](/docs/cli/bench/subscriber) | Run a subscriber benchmark test. | \ No newline at end of file diff --git a/src/pages/docs/cli/bench/publisher.mdx b/src/pages/docs/cli/bench/publisher.mdx new file mode 100644 index 0000000000..4d02d87176 --- /dev/null +++ b/src/pages/docs/cli/bench/publisher.mdx @@ -0,0 +1,110 @@ +--- +title: "ably bench publisher" +meta_description: "Run a publisher benchmark test using the CLI." +meta_keywords: "ably cli, cli, benchmark, publisher, performance test, ably bench publisher" +--- + + +```shell +ably bench publisher [flags] +``` + + +Use the `ably bench publisher` command to run a publisher benchmark test. This helps you measure the performance characteristics of publishing messages to an Ably channel under various conditions and configurations. + +## Arguments + +Pass the following arguments to the `ably bench publisher` command: + +### `` + +The channel name to publish to, for example: `benchmark-channel`. + +## Flags + +You can optionally pass the following flags to the `ably bench publisher` command: + +### `--messages | -m` + +Number of messages to publish. The default is `1000` messages, with a maximum of `10,000`. + +### `--rate | -r` + +Messages per second to publish. The default is `15` messages per second, with a maximum of `20`. + +### `--transport | -t` + +Transport protocol to use for publishing. Options are: +- `realtime` - Use realtime WebSocket connections (default) +- `rest` - Use REST API for publishing + +### `--message-size` + +Size of the message payload in bytes. The default is `100` bytes. + +### `--wait-for-subscribers` + +Wait for subscribers to be present on the channel before starting the benchmark test. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably bench publisher` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Run a basic publisher benchmark: + + +```shell +ably bench publisher my-channel +``` + + +Run benchmark with custom message count and rate: + + +```shell +ably bench publisher --messages 5000 --rate 10 my-channel +``` + + +Use realtime transport for benchmarking: + + +```shell +ably bench publisher --transport realtime my-channel +``` + + +Use REST transport for benchmarking: + + +```shell +ably bench publisher --transport rest my-channel +``` + + +Wait for subscribers before starting: + + +```shell +ably bench publisher --wait-for-subscribers my-channel +``` + + +Use another terminal instance and the [`ably bench subscriber`](/docs/cli/bench/subscriber) command to test complete pub/sub performance. diff --git a/src/pages/docs/cli/bench/subscriber.mdx b/src/pages/docs/cli/bench/subscriber.mdx new file mode 100644 index 0000000000..b2548a1012 --- /dev/null +++ b/src/pages/docs/cli/bench/subscriber.mdx @@ -0,0 +1,70 @@ +--- +title: "ably bench subscriber" +meta_description: "Run a subscriber benchmark test using the CLI." +meta_keywords: "ably cli, cli, benchmark, subscriber, performance test, ably bench subscriber" +--- + + +```shell +ably bench subscriber [flags] +``` + + +Use the `ably bench subscriber` command to run a subscriber benchmark test. This helps you measure the performance characteristics of receiving messages from an Ably channel, typically used in conjunction with the publisher benchmark. + +## Arguments + +Pass the following arguments to the `ably bench subscriber` command: + +### `` + +The channel name to subscribe to, for example: `benchmark-channel`. + +## Flags + +You can optionally pass the following flags to the `ably bench subscriber` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably bench subscriber` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Run a basic subscriber benchmark: + + +```shell +ably bench subscriber my-channel +``` + + +Use another terminal instance and the [`ably bench publisher`](/docs/cli/bench/publisher) command to test complete pub/sub performance: + +**Terminal 1:** + +```shell +ably bench subscriber my-channel +``` + + +**Terminal 2:** + +```shell +ably bench publisher my-channel +``` + diff --git a/src/pages/docs/cli/channel-rule/index.mdx b/src/pages/docs/cli/channel-rule/index.mdx new file mode 100644 index 0000000000..e830db8c0e --- /dev/null +++ b/src/pages/docs/cli/channel-rule/index.mdx @@ -0,0 +1,22 @@ +--- +title: "ably channel-rule" +meta_description: "Legacy channel rule commands for the Ably CLI." +meta_keywords: "ably cli, cli, channel rules, namespaces, legacy, ably channel-rule" +--- + + + +Use the `ably channel-rule` command group to manage [channel rules](/docs/channels/channel-rules-namespaces) (also known as namespaces) for your Ably applications. Channel rules allow you to configure permissions and settings for groups of channels based on naming patterns. + +## Migration Notice + +This command group is deprecated. Use the following modern equivalents: + +| Legacy Command | Modern Equivalent | +| -------------- | ----------------- | +| `ably channel-rule create` | [`ably apps channel-rules create`](/docs/cli/apps/channel-rules/create) | +| `ably channel-rule delete` | [`ably apps channel-rules delete`](/docs/cli/apps/channel-rules/delete) | +| `ably channel-rule list` | [`ably apps channel-rules list`](/docs/cli/apps/channel-rules/list) | +| `ably channel-rule update` | [`ably apps channel-rules update`](/docs/cli/apps/channel-rules/update) | \ No newline at end of file diff --git a/src/pages/docs/cli/channels/batch-publish.mdx b/src/pages/docs/cli/channels/batch-publish.mdx new file mode 100644 index 0000000000..d1800a6c42 --- /dev/null +++ b/src/pages/docs/cli/channels/batch-publish.mdx @@ -0,0 +1,163 @@ +--- +title: "ably channels batch-publish" +meta_description: "Publish messages to multiple Ably channels with a single request using the CLI." +meta_keywords: "ably cli, cli, command, batch publish, pubsub, pub/sub, multiple channels, bulk publishing" +--- + + +```shell +ably channels batch-publish [flags] +``` + + +Use the `ably channels batch-publish` command to publish messages to multiple Ably channels with a single request, improving efficiency when sending the same message to many channels. + +For publishing to a single channel, use the [`ably channels publish`](/docs/cli/channels/publish) command instead. Use another terminal instance to subscribe to the channels using the [`ably channels subscribe`](/docs/cli/channels/subscribe) command in order to receive published messages. + +## Arguments + +### `` + +The message to publish in plain text or JSON format. This argument is optional if using the `--spec` flag. + +Examples: + +* `"Hello!"` +* `{"name":"my-event","data":"Hello!"}` + +## Flags + +You can optionally pass the following flags to the `ably channels batch-publish` command: + +### `--channels` + +Comma-separated list of channel names to publish to, for example: `channel1,channel2,channel3`. + +### `--channels-json` + +JSON array of channel names to publish to, for example: `["channel1","channel2","channel3"]`. + +### `--encoding | -e` + +The encoding of the message. Common encodings include `json`, `utf-8`, and `base64`. + +### `--name | -n` + +The event name for the message, if not specified in the message JSON. + +### `--spec` + +Complete batch specification as JSON. Can be either: + +* A single `BatchSpec` object, for example: `{"channels":["ch1","ch2"],"messages":[{"data":"hello"}]}`. +* An array of `BatchSpec` objects for multiple batches. + +When using `--spec`, the `message` argument and other flags are ignored. + +## Global flags + +The following global flags are supported using the `ably channels batch-publish` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Publish to multiple channels with comma-separated list + +Publish the same message to three channels: + + +```shell +ably channels batch-publish --channels "example-channel-1,example-channel-2,example-channel-3" "Hello everyone!" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Sending batch publish request... +Batch publish successful! +Response: { + "responses": [ + { + "channel": "example-channel-1", + "messageId": "Ab1CdE:12345" + }, + { + "channel": "example-channel-2", + "messageId": "Ab1CdE:12346" + }, + { + "channel": "example-channel-3", + "messageId": "Ab1CdE:12347" + } + ] +} +``` + + +### Publish using JSON array of channels + +Use JSON format to specify channels: + + +```shell +ably channels batch-publish --channels-json '["game-room-1","game-room-2"]' "Game update: New player joined!" +``` + + +### Publish with event name + +Publish a message with a specific event name: + + +```shell +ably channels batch-publish --channels "alerts,notifications" --name "system-alert" "Server maintenance scheduled" +``` + + +### Using complete batch specification + +Publish different messages to different channels using the `--spec` flag: + + +```shell +ably channels batch-publish --spec '{ + "channels": ["user-123", "user-456"], + "messages": [ + {"name": "notification", "data": "You have a new message"} + ] +}' +``` + + +### Multiple batch specifications + +Publish different content to different channel groups: + + +```shell +ably channels batch-publish --spec '[ + { + "channels": ["alerts"], + "messages": [{"name": "alert", "data": "High CPU usage detected"}] + }, + { + "channels": ["logs"], + "messages": [{"name": "log", "data": "System check completed"}] + } +]' +``` + + diff --git a/src/pages/docs/cli/channels/history.mdx b/src/pages/docs/cli/channels/history.mdx new file mode 100644 index 0000000000..5e4a55cc4d --- /dev/null +++ b/src/pages/docs/cli/channels/history.mdx @@ -0,0 +1,163 @@ +--- +title: "ably channels history" +meta_description: "Retrieve message history for an Ably channel using the CLI." +meta_keywords: "ably cli, cli, command, channel history, message history, persistence, historical data" +--- + + +```shell +ably channels history [flags] +``` + + +Use the `ably channels history` command to retrieve messages that have been previously sent to a channel. + +Messages are stored for 2 minutes by default, unless a longer duration is [configured](/docs/storage-history/storage) for your app. + + + +## Arguments + +Pass the following argument to the `ably channels history` command: + +### `` + +The channel name to retrieve history for, for example: `example-channel`. + +## Output + +Each message returned from history has the following properties: + +| Property | Description | +| -------- | ----------- | +| Timestamp | When the message was published in ISO 8601 format. | +| Event | The event name if one was specified when the message was published. | +| Client ID | The client ID of the publisher. | +| Data | The message contents. | + +## Flags + +You can optionally pass the following flags to the `ably channels history` command: + +### `--start` + +Start time for the history query in ISO 8601 format, for example: `2025-01-20T09:00:00Z`. + +### `--end` + +End time for the history query in ISO 8601 format, for example: `2025-01-20T10:30:00Z`. + +### `--direction` + +Direction of message retrieval. Options are `backwards` or `forwards`. The default is `backwards`. + +* `backwards`: Retrieve messages from newest to oldest +* `forwards`: Retrieve messages from oldest to newest + +### `--limit` + +Maximum number of messages to retrieve. The default is `50`. Maximum allowed is `1000`. + +### `--cipher` + +Decryption key for encrypted messages. Use AES-128 encryption format. + +## Global flags + +The following global flags are supported using the `ably channels history` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Retrieve recent message history + +Get the last 10 messages from a channel: + + +```shell +ably channels history example-channel --limit 10 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Found 3 messages in the history of channel example-channel: + +[1] 2025-01-20T10:35:15.896Z +Event: (none) +Client ID: ably-cli-abc123 +Data: +Message 3 at 1758110833755 + +[2] 2025-01-20T10:35:14.852Z +Event: (none) +Client ID: ably-cli-abc123 +Data: +Message 2 at 1758110832714 + +[3] 2025-01-20T10:35:13.745Z +Event: (none) +Client ID: ably-cli-abc123 +Data: +Message 1 at 1758110831689 + +Showing maximum of 10 messages. Use --limit to show more. +``` + + +### Retrieve messages within a time range + +Get messages published between specific times: + + +```shell +ably channels history example-channel --start "2025-01-20T09:00:00Z" --end "2025-01-20T10:00:00Z" +``` + + +### Retrieve messages in chronological order + +Get messages from oldest to newest: + + +```shell +ably channels history example-channel --direction forwards --limit 5 +``` + + +### Retrieve messages from encrypted channel + +Get history from a channel that uses message encryption: + + +```shell +ably channels history example-encrypted-channel --cipher "0123456789abcdef" +``` + + +### Get all available history + +Retrieve the maximum number of messages (up to 1000): + + +```shell +ably channels history example-channel --limit 1000 +``` + + + diff --git a/src/pages/docs/cli/channels/index.mdx b/src/pages/docs/cli/channels/index.mdx new file mode 100644 index 0000000000..1962134f64 --- /dev/null +++ b/src/pages/docs/cli/channels/index.mdx @@ -0,0 +1,41 @@ +--- +title: "ably channels" +meta_description: "Manage Ably channels using the CLI - publish, subscribe, view history, and monitor occupancy and presence." +meta_keywords: "ably cli, cli, channel management, pubsub, pub/sub, realtime messaging, ably channels" +--- + +Use the `ably channels` command group to manage [Ably Pub/Sub](/docs/pub-sub) channels. + +## Subcommands + +The following commands are used to publish and subscribe to channels: + +| Command | Description | +| ------- | ----------- | +| [`ably channels subscribe`](/docs/cli/channels/subscribe) | Subscribe to messages on one or more channels. | +| [`ably channels publish`](/docs/cli/channels/publish) | Publish messages to a channel. | +| [`ably channels batch-publish`](/docs/cli/channels/batch-publish) | Publish messages to multiple channels in a single request. | +| [`ably channels history`](/docs/cli/channels/history) | Retrieve message history for a channel. | + +The following commands are used to enter and view the presence of clients on a channel: + +| Command | Description | +| ------- | ----------- | +| [`ably channels presence`](/docs/cli/channels/presence) | Manage the presence set of a channel. | +| [`ably channels presence enter`](/docs/cli/channels/presence/enter) | Enter presence on a channel and listen for events. | +| [`ably channels presence subscribe`](/docs/cli/channels/presence/subscribe) | Subscribe to presence events on a channel. | + +The following commands are used to view the occupancy metrics of a channel: + +| Command | Description | +| ------- | ----------- | +| [`ably channels occupancy`](/docs/cli/channels/occupancy) | Manage the occupancy of a channel. | +| [`ably channels occupancy get`](/docs/cli/channels/occupancy/get) | Get current occupancy metrics for a channel. | +| [`ably channels occupancy subscribe`](/docs/cli/channels/occupancy/subscribe) | Subscribe to occupancy events on a channel. | + +The following commands are used to observe the channels in your app: + +| Command | Description | +| ------- | ----------- | +| [`ably channels list`](/docs/cli/channels/list) | List the active channels in your app. | +| [`ably channels logs`](/docs/cli/channels/logs) | Subscribe to channel lifecycle logs. | diff --git a/src/pages/docs/cli/channels/list.mdx b/src/pages/docs/cli/channels/list.mdx new file mode 100644 index 0000000000..c15a402341 --- /dev/null +++ b/src/pages/docs/cli/channels/list.mdx @@ -0,0 +1,135 @@ +--- +title: "ably channels list" +meta_description: "List active channels in your Ably app using the CLI." +meta_keywords: "ably cli, cli, command, channel enumeration, active channels, channel list" +--- + + +```shell +ably channels list [flags] +``` + + +Use the `ably channels list` command to list the active channels in your app. + +## Flags + +You can optionally pass the following flags to the `ably channels list` command: + +### `--limit` + +Maximum number of channels to return. The default is `100`. Maximum allowed is `1000`. + +### `--prefix | -p` + +Filter channels by prefix. Only channels whose names start with the specified prefix will be returned. + +## Global flags + +The following global flags are supported using the `ably channels list` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +For each active channel, the following metrics are displayed: + +| Metric | Description | +| ------ | ----------- | +| connections | The number of connections. | +| publishers | The number of connections that are authorized to publish. | +| subscribers | The number of connections that are authorized to subscribe to messages. | +| presenceSubscribers | The number of connections that are authorized to subscribe to presence messages. | +| presenceConnections | The number of connections that are authorized to enter members into the presence channel. | +| presenceMembers | The number of members currently entered into the presence channel. | +| objectPublishers | The number of connections that are authorized to publish updates to objects on the channel. | +| objectSubscribers | The number of connections that are authorized to subscribe to objects on the channel. | + +## Examples + +### List all active channels + +Get a list of all currently active channels: + + +```shell +ably channels list +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Found 1 active channels: +example-channel + Connections: 1 + Publishers: 1 + Subscribers: 1 + Presence Connections: 1 + Presence Members: 0 +``` + + +### List channels with a limit + +Get only the first 5 active channels: + + +```shell +ably channels list --limit 5 +``` + + +### Filter channels by prefix + +List only channels that start with "game-": + + +```shell +ably channels list --prefix "game-" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Found 2 active channels: +game-room-1 + Connections: 5 + Publishers: 2 + Subscribers: 3 + Presence Connections: 5 + Presence Members: 4 + +game-room-2 + Connections: 3 + Publishers: 1 + Subscribers: 2 + Presence Connections: 3 + Presence Members: 2 +``` + + +### Filter with prefix and limit + +Get the first 3 channels starting with "chat-": + + +```shell +ably channels list --prefix "chat-" --limit 3 +``` + + diff --git a/src/pages/docs/cli/channels/logs.mdx b/src/pages/docs/cli/channels/logs.mdx new file mode 100644 index 0000000000..b1ad488fb8 --- /dev/null +++ b/src/pages/docs/cli/channels/logs.mdx @@ -0,0 +1,173 @@ +--- +title: "ably channels logs" +meta_description: "Subscribe to channel lifecycle logs using the Ably CLI." +meta_keywords: "ably cli, cli, command, channel logs, lifecycle logs, monitoring, debugging" +--- + + +```shell +ably channels logs [flags] +``` + + +Use the `ably channels logs` command to subscribe to channel lifecycle logs. + +Channel lifecycle logs provide realtime information about channel state changes and occupancy metrics for all channels within your app. + + + +## Arguments + +You can optionally pass the following argument to the `ably channels logs` command: + +### `` + +The log topic to subscribe to. Currently only `channel-lifecycle` is supported. This is the default if no topic is specified. + +## Flags + +You can optionally pass the following flags to the `ably channels logs` command: + +### `--json` + +Output results as JSON format. The default is `false`. + +### `--rewind` + +Number of messages to rewind by. This will fetch a certain number of messages that were sent to the channel before you subscribed to it. The default is `0`. + +## Global flags + +The following global flags are supported using the `ably channels logs` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The following information is returned from channel lifecycle logs relating to a channel's state: + +| Event Type | Description | +| ---------- | ----------- | +| channel.region.active | A channel has become active in a specific region. | +| channel.region.inactive | A channel has become inactive in a specific region. | +| channel.opened | A channel has been opened for the first time. | +| channel.closed | A channel has been closed and is no longer active. | + +The following occupancy metrics are returned for each channel: + +| Metric | Description | +| ------ | ----------- | +| connections | The number of connections. | +| publishers | The number of connections that are authorized to publish. | +| subscribers | The number of connections that are authorized to subscribe to messages. | +| presenceSubscribers | The number of connections that are authorized to subscribe to presence messages. | +| presenceConnections | The number of connections that are authorized to enter members into the presence channel. | +| presenceMembers | The number of members currently entered into the presence channel. | +| objectPublishers | The number of connections that are authorized to publish updates to objects on the channel. | +| objectSubscribers | The number of connections that are authorized to subscribe to objects on the channel. | + +## Examples + +### Subscribe to channel lifecycle logs + +Subscribe to real-time channel lifecycle events: + + +```shell +ably channels logs +``` + + +You can test this by publishing a message in another terminal instance to trigger channel events: + + +```shell +ably channels publish example-channel "Hello World" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Subscribing to [meta]channel.lifecycle... +Press Ctrl+C to exit + +[2025-09-17T17:03:42.691Z] Channel: [meta]channel.lifecycle | Event: channel.region.active +Data: +{ + "name": "example-channel", + "channelId": "example-channel", + "status": { + "isActive": true, + "occupancy": { + "metrics": { + "connections": 0, + "publishers": 0, + "subscribers": 0, + "presenceConnections": 0, + "presenceMembers": 0, + "presenceSubscribers": 0, + "objectSubscribers": 0, + "objectPublishers": 0 + } + } + }, + "region": "eu-central-1-A" +} + +[2025-09-17T17:03:42.942Z] Channel: [meta]channel.lifecycle | Event: channel.opened +Data: +{ + "name": "example-channel", + "channelId": "example-channel", + "status": { + "isActive": true, + "occupancy": { + "metrics": { + "connections": 0, + "publishers": 0, + "subscribers": 0, + "presenceConnections": 0, + "presenceMembers": 0, + "presenceSubscribers": 0, + "objectSubscribers": 0, + "objectPublishers": 0 + } + } + } +} +``` + + +### Subscribe with message rewind + +Get the last 10 log entries plus any new ones: + + +```shell +ably channels logs --rewind 10 +``` + + +### Explicitly specify topic + +Subscribe to channel lifecycle logs (same as default): + + +```shell +ably channels logs channel-lifecycle +``` + diff --git a/src/pages/docs/cli/channels/occupancy/get.mdx b/src/pages/docs/cli/channels/occupancy/get.mdx new file mode 100644 index 0000000000..944adf55f2 --- /dev/null +++ b/src/pages/docs/cli/channels/occupancy/get.mdx @@ -0,0 +1,79 @@ +--- +title: "ably channels occupancy get" +meta_description: "Get current occupancy metrics for an Ably channel using the CLI." +meta_keywords: "ably cli, cli, command, occupancy, channel occupancy, realtime metrics, connection count" +--- + + +```shell +ably channels occupancy get +``` + + +Use the `ably channels occupancy get` command to get current occupancy metrics for a channel. Occupancy metrics display high-level metrics about the clients attached to a channel, such as the number of connections. + +## Arguments + +Pass the following argument to the `ably channels occupancy get` command: + +### `` + +The channel name to get occupancy metrics for, for example: `example-channel`. + +## Global flags + +The following global flags are supported using the `ably channels occupancy get` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +Each occupancy event includes the following metrics: + +| Metric | Description | +| ------ | ----------- | +| connections | The number of connections. | +| publishers | The number of connections that are authorized to publish. | +| subscribers | The number of connections that are authorized to subscribe to messages. | +| presenceSubscribers | The number of connections that are authorized to subscribe to presence messages. | +| presenceConnections | The number of connections that are authorized to enter members into the presence channel. | +| presenceMembers | The number of members currently entered into the presence channel. | +| objectPublishers | The number of connections that are authorized to publish updates to objects on the channel. | +| objectSubscribers | The number of connections that are authorized to subscribe to objects on the channel. | + +## Examples + +### Get occupancy for a channel + +Get the current occupancy metrics: + + +```shell +ably channels occupancy get example-channel +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Occupancy metrics for channel 'example-channel': + +Connections: 0 +Publishers: 0 +Subscribers: 0 +Presence Connections: 0 +Presence Members: 0 +Presence Subscribers: 0 +``` + diff --git a/src/pages/docs/cli/channels/occupancy/index.mdx b/src/pages/docs/cli/channels/occupancy/index.mdx new file mode 100644 index 0000000000..0fbe5c3cdf --- /dev/null +++ b/src/pages/docs/cli/channels/occupancy/index.mdx @@ -0,0 +1,14 @@ +--- +title: "ably channels occupancy" +meta_description: "Manage the occupancy of a channel using the Ably CLI." +meta_keywords: "ably cli, cli, occupancy, channel occupancy, realtime metrics, connection count" +--- + +Use the `ably channels occupancy` command group to manage the [occupancy](/docs/presence-occupancy/occupancy) of a channel. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably channels occupancy get`](/docs/cli/channels/occupancy/get) | Get current occupancy metrics for a channel. | +| [`ably channels occupancy subscribe`](/docs/cli/channels/occupancy/subscribe) | Subscribe to occupancy events on a channel. | diff --git a/src/pages/docs/cli/channels/occupancy/subscribe.mdx b/src/pages/docs/cli/channels/occupancy/subscribe.mdx new file mode 100644 index 0000000000..249a4a7b56 --- /dev/null +++ b/src/pages/docs/cli/channels/occupancy/subscribe.mdx @@ -0,0 +1,106 @@ +--- +title: "ably channels occupancy subscribe" +meta_description: "Subscribe to occupancy events on an Ably channel using the CLI." +meta_keywords: "ably cli, cli, command, occupancy subscribe, realtime occupancy, channel monitoring" +--- + + +```shell +ably channels occupancy subscribe [flags] +``` + + +Use the `ably channels occupancy subscribe` command to subscribe to occupancy metrics for a channel. Occupancy metrics display high-level metrics about the clients attached to a channel, such as the number of connections. + +## Arguments + +Pass the following argument to the `ably channels occupancy subscribe` command: + +### `` + +The channel name to subscribe to occupancy events for, for example: `example-channel`. + +## Flags + +You can optionally pass the following flag to the `ably channels occupancy subscribe` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Set to `0` to run indefinitely. The default is `0`. + +## Global flags + +The following global flags are supported using the `ably channels occupancy subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +Each occupancy event includes the following metrics: + +| Metric | Description | +| ------ | ----------- | +| connections | The number of connections. | +| publishers | The number of connections that are authorized to publish. | +| subscribers | The number of connections that are authorized to subscribe to messages. | +| presenceSubscribers | The number of connections that are authorized to subscribe to presence messages. | +| presenceConnections | The number of connections that are authorized to enter members into the presence channel. | +| presenceMembers | The number of members currently entered into the presence channel. | +| objectPublishers | The number of connections that are authorized to publish updates to objects on the channel. | +| objectSubscribers | The number of connections that are authorized to subscribe to objects on the channel. | + +## Examples + +### Subscribe to occupancy events + +Monitor occupancy changes on a channel: + + +```shell +ably channels occupancy subscribe example-channel +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Subscribing to occupancy events on channel: example-channel +Listening for occupancy events. Press Ctrl+C to exit. +[2025-01-20T14:09:29.426Z] Channel: example-channel | Occupancy Update +Occupancy Data: { + "metrics": { + "connections": 2, + "publishers": 2, + "subscribers": 2, + "presenceConnections": 2, + "presenceMembers": 0, + "presenceSubscribers": 2, + "objectSubscribers": 0, + "objectPublishers": 0 + } +} +``` + + +The command will continue to show occupancy updates as they occur. + +### Subscribe with automatic exit + +Monitor occupancy for 30 seconds then exit: + + +```shell +ably channels occupancy subscribe example-channel --duration 30 +``` + diff --git a/src/pages/docs/cli/channels/presence/enter.mdx b/src/pages/docs/cli/channels/presence/enter.mdx new file mode 100644 index 0000000000..5b57c4d99e --- /dev/null +++ b/src/pages/docs/cli/channels/presence/enter.mdx @@ -0,0 +1,143 @@ +--- +title: "ably channels presence enter" +meta_description: "Enter presence on an Ably channel and listen for presence events using the CLI." +meta_keywords: "ably cli, cli, command, presence, enter presence, online status, realtime presence" +--- + + +```shell +ably channels presence enter [flags] +``` + + +Use the `ably channels presence enter` command to enter the presence set of a channel. Presence is used to indicate the 'online status' or 'presence' of a client to other clients on the channel. + +Use another terminal instance and the [`ably channels presence subscribe`](/docs/cli/channels/presence/subscribe) command to monitor presence events. + +## Arguments + +Pass the following argument to the `ably channels presence enter` command: + +### `` + +The channel name to enter presence on, for example: `example-channel`. + +## Flags + +You can optionally pass the following flags to the `ably channels presence enter` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Set to `0` to run indefinitely. The default is `0`. + +### `--data` + +Optional JSON data to associate with the presence entry, for example: `{"status":"online","role":"admin"}`. + +## Global flags + +The following global flags are supported using the `ably channels presence enter` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When you enter the presence set of a channel using the CLI, you'll see a list of members currently present. + +The actions associated with each event are: + +| Action | Description | +| ------ | ----------- | +| Enter | A client has entered the presence set. | +| Update | A client has updated their presence data. | +| Leave | A client has left the presence set. | +| Present | A client is currently present. This is used to list the members currently in the presence set when a client first joins. | + +## Examples + +### Enter presence without data + +Enter presence on a channel: + + +```shell +ably channels presence enter example-channel +``` + + +You can monitor presence activity by subscribing to presence events in another terminal instance: + + +```shell +ably channels presence subscribe example-channel +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +[2025-01-20T14:08:33.148Z] Channel: example-channel | Action: present | Client: ably-cli-e78fa50e + +[2025-01-20T14:08:33.148Z] Channel: example-channel | Action: enter | Client: ably-cli-fabf6fbb + +✓ Entered channel example-channel as client ably-cli-fabf6fbb + +Current presence members (2): + Client: ably-cli-e78fa50e + Client: ably-cli-fabf6fbb + +Listening for presence events until terminated. Press Ctrl+C to exit. +``` + + +### Enter presence with data + +Enter presence with custom status data: + + +```shell +ably channels presence enter example-channel --data '{"role":"moderator"}' +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +[2025-01-20T14:08:33.148Z] Channel: example-channel | Action: enter | Client: ably-cli-e78fa50e +Data: +{ + "role": "moderator" +} + +✓ Entered channel example-channel as client ably-cli-e78fa50e + +Current presence members (1): + Client: ably-cli-e78fa50e | Data: {"role":"moderator"} + +Listening for presence events until terminated. Press Ctrl+C to exit. +``` + + +### Enter presence for limited time + +Enter presence for 60 seconds then automatically exit: + + +```shell +ably channels presence enter example-channel --duration 60 --data '{"status":"available"}' +``` + + diff --git a/src/pages/docs/cli/channels/presence/index.mdx b/src/pages/docs/cli/channels/presence/index.mdx new file mode 100644 index 0000000000..0a573c8513 --- /dev/null +++ b/src/pages/docs/cli/channels/presence/index.mdx @@ -0,0 +1,14 @@ +--- +title: "ably channels presence" +meta_description: "Manage the presence set of a channel using the Ably CLI." +meta_keywords: "ably cli, cli, presence, channel presence, realtime presence, online users" +--- + +Use the `ably channels presence` command group to manage the [presence set](/docs/presence-occupancy/presence) of a channel. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably channels presence enter`](/docs/cli/channels/presence/enter) | Enter presence on a channel and listen for events. | +| [`ably channels presence subscribe`](/docs/cli/channels/presence/subscribe) | Subscribe to presence events on a channel. | diff --git a/src/pages/docs/cli/channels/presence/subscribe.mdx b/src/pages/docs/cli/channels/presence/subscribe.mdx new file mode 100644 index 0000000000..e92e76afef --- /dev/null +++ b/src/pages/docs/cli/channels/presence/subscribe.mdx @@ -0,0 +1,105 @@ +--- +title: "ably channels presence subscribe" +meta_description: "Subscribe to presence events on an Ably channel using the CLI." +meta_keywords: "ably cli, cli, command, presence subscribe, presence events, realtime presence monitoring" +--- + + +```shell +ably channels presence subscribe [flags] +``` + + +Use the `ably channels presence subscribe` command to subscribe to presence events on a channel and monitor who enters, leaves, or updates their presence data. + +Use another terminal instance and the [`ably channels presence enter`](/docs/cli/channels/presence/enter) command to see a client join the presence set and emit an enter event. + +## Arguments + +Pass the following argument to the `ably channels presence subscribe` command: + +### `` + +The channel name to subscribe to presence events for, for example: `example-channel`. + +## Flags + +You can optionally pass the following flag to the `ably channels presence subscribe` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Set to `0` to run indefinitely. The default is `0`. + +## Global flags + +The following global flags are supported using the `ably channels presence subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When you subscribe to the presence set of a channel using the CLI, you'll see a list of members currently present. + +The actions associated with each event are: + +| Action | Description | +| ------ | ----------- | +| Enter | A client has entered the presence set. | +| Update | A client has updated their presence data. | +| Leave | A client has left the presence set. | +| Present | A client is currently present. This is used to list the members currently in the presence set when a client first joins. | + +## Examples + +### Subscribe to presence events + +Subscribe to all presence activity on a channel: + + +```shell +ably channels presence subscribe example-channel +``` + + +You can test this by entering presence in other terminal instances: + + +```shell +ably channels presence enter example-channel +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Subscribing to presence events on channel: example-channel +Listening for presence events. Press Ctrl+C to exit. +[2025-01-20T14:08:33.148Z] Channel: example-channel | Action: present | ably-cli-e78fa50e + +[2025-01-20T14:08:45.234Z] Channel: example-channel | Action: enter | ably-cli-1as2434 + +[2025-01-20T14:09:12.567Z] Channel: example-channel | Action: leave | ably-cli-1as2434 +``` + + +### Subscribe with automatic exit + +Subscribe to presence events for 30 seconds then exit: + + +```shell +ably channels presence subscribe example-channel --duration 30 +``` + + diff --git a/src/pages/docs/cli/channels/publish.mdx b/src/pages/docs/cli/channels/publish.mdx new file mode 100644 index 0000000000..6851227d27 --- /dev/null +++ b/src/pages/docs/cli/channels/publish.mdx @@ -0,0 +1,150 @@ +--- +title: "ably channels publish" +meta_description: "Publish messages to a channel using the Ably CLI." +meta_keywords: "ably cli, cli, command, pubsub, pub/sub, channel, ably channels, channel publish, publish" +--- + + +```shell +ably channels publish [flags] +``` + + +Use the `ably channels publish` command to publish a message to a channel. + +Use another terminal instance to subscribe to the channel using the [`ably channels subscribe`](/docs/cli/channels/subscribe) command in order to receive published messages. + +You can also use the [`ably channels batch-publish`](/docs/cli/channels/batch-publish) command to publish to multiple channels in a single request. + +## Arguments + +Pass the following arguments to the `ably channels publish` command: + +### `` + +The channel name to publish to, for example: `example-channel`. + +### `` + +The message to publish in plain text or JSON format, for example: + +* `"Hello!"` +* `{"name":"my-event","data":"Hello!"}` + +You can also use interpolation in the message body: + +* `{{.Count}}` will display the message number, for example: `Message {{.Count}} of 5`. +* `{{.Timestamp}}` will display the current Unix timestamp in milliseconds, for example: `Message sent at {{.Timestamp}}`. + +## Flags + +You can optionally pass the following flags to the `ably channels publish` command: + +### `--count | -c` + +The number of messages to publish. The default is `1`. + +### `--delay | -d` + +The delay between messages being published, in milliseconds. The default is `40`. + +### `--encoding | -e` + +The encoding of the message. Common encodings include `json`, `utf-8`, and `base64`. + +### `--name | -n` + +The event name for the message, if not specified in the message JSON. + +### `--transport` + +The transport method to use to publish the message. Options are `rest` or `realtime`. The default is `rest`. + +## Global flags + +The following global flags are supported using the `ably channels publish` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Publish a plain text message + +Publish a simple text message: + + +```shell +ably channels publish example-channel "Hello!" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +✓ Message published successfully to channel "example-channel". +``` + + +### Publish a JSON message + +Publish a JSON message with an event name specified: + + +```shell +ably channels publish example-channel '{"name":"my-event","data":"Hello!"}' +``` + + +Specify the event name separately using the `--name` flag: + + +```shell +ably channels publish --name my-event example-channel '{"data":"Hello!"}' +``` + + +### Publish multiple messages + +Publish 3 messages using the `--count` flag: + + +```shell +ably channels publish --count 3 example-channel "Message {{.Count}} at {{.Timestamp}}" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Publishing 3 messages with 40ms delay... +✓ Message 1 published successfully to channel "example-channel". +Progress: 1/3 messages published (0 errors) +✓ Message 2 published successfully to channel "example-channel". +Progress: 2/3 messages published (0 errors) +✓ Message 3 published successfully to channel "example-channel". +✓ 3/3 messages published successfully. +``` + + +### Publish with custom delay + +Publish messages with a 1 second delay between them: + + +```shell +ably channels publish --count 5 --delay 1000 example-channel "Delayed message {{.Count}}" +``` + diff --git a/src/pages/docs/cli/channels/subscribe.mdx b/src/pages/docs/cli/channels/subscribe.mdx new file mode 100644 index 0000000000..a66499debb --- /dev/null +++ b/src/pages/docs/cli/channels/subscribe.mdx @@ -0,0 +1,144 @@ +--- +title: "ably channels subscribe" +meta_description: "Subscribe to messages published on Ably channels using the CLI." +meta_keywords: "ably cli, cli, command, pubsub, pub/sub, channel, subscribe, realtime messaging" +--- + + +```shell +ably channels subscribe [flags] +``` + + +Subscribe to messages published on one or more Ably channels. + +Use the [`ably channels publish`](/docs/cli/channels/publish) in another terminal instance to publish messages that will be received by the subscriber. + +The subscriber will run continuously unless you specify a [`--duration`](#duration), or you stop it using `Ctrl+C`. + +## Arguments + +### `` + +One or more channel names to subscribe to, for example: + +* `example-channel` +* `example-channel-1 example-channel-2` + +## Flags + +In addition to the [global flags](/docs/cli#global-flags), the `ably channels subscribe` command supports: + +### `--cipher-algorithm` + +Encryption algorithm to use for decrypting messages. The default is `aes`. + +### `--cipher-key` + +Encryption key for decrypting messages, provided as a hex-encoded string. + +### `--cipher-key-length` + +Length of the encryption key in bits. The default is `256`. + +### `--cipher-mode` + +Cipher mode to use for decryption. The default is `cbc`. + +### `--delta` + +Enable [delta compression](/docs/channels/options/deltas) for messages. When delta compression is enabled, message payloads will only contain the difference between the present and previous message sent to the channel. Set to `true` to enable. The default is `false`. + +### `--duration | -D` + +Automatically stop subscribing after the given number of seconds. Set to `0` to run indefinitely. The default is `0`. + +### `--rewind` + +Number of messages to rewind by. This will fetch a certain number of messages that were sent to the channel before you subscribed to it. The default is `0`. + +## Examples + +### Subscribe to a single channel + +Subscribe to receive messages on a channel: + + +```shell +ably channels subscribe example-channel +``` + + +You can test this functionality by publishing a message in another terminal instance: + + +```shell +ably channels publish example-channel "Hello from terminal 2!" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Subscribing to channel: example-channel +✓ Successfully subscribed. Waiting for messages... (Press Ctrl+C to exit) + +[2025-01-20T10:30:45.123Z] example-channel +Event: (none) +Client ID: ably-cli-abc123 +Data: +Hello from terminal 2! +``` + + +### Subscribe to multiple channels + +Subscribe to messages on multiple channels simultaneously: + + +```shell +ably channels subscribe example-channel-1 example-channel-2 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Subscribing to channels: example-channel-1, example-channel-2 +✓ Successfully subscribed. Waiting for messages... (Press Ctrl+C to exit) +``` + + +### Subscribe with automatic exit + +Subscribe for 30 seconds then automatically exit: + + +```shell +ably channels subscribe --duration 30 example-channel +``` + + +### Subscribe with message rewind + +Subscribe and receive the last 5 messages from the channel: + + +```shell +ably channels subscribe --rewind 5 example-channel +``` + + +### Subscribe to encrypted channel + +Subscribe to a channel that uses message encryption: + + +```shell +ably channels subscribe --cipher-key "0123456789abcdef0123456789abcdef" example-encrypted-channel +``` + diff --git a/src/pages/docs/cli/config.mdx b/src/pages/docs/cli/config.mdx new file mode 100644 index 0000000000..96e0951d67 --- /dev/null +++ b/src/pages/docs/cli/config.mdx @@ -0,0 +1,64 @@ +--- +title: "ably config" +meta_description: "Open the Ably CLI configuration file for editing." +meta_keywords: "ably cli, cli, config, configuration, ably config" +--- + + +```shell +ably config [flags] +``` + + +Use the `ably config` command to open the Ably CLI configuration file in your default text editor. The configuration file stores settings like default API keys, environments, and other CLI preferences. + +## Flags + +You can optionally pass the following flags to the `ably config` command: + +### `--editor | -e` + +The text editor to use to open the configuration file. If not specified, uses the `$EDITOR` environment variable or falls back to the system default. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably config` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Open the configuration file in the default editor: + + +```shell +ably config +``` + + +Open the configuration file in a specific editor: + + +```shell +ably config --editor vim +``` + + + +```shell +ably config -e nano +``` + diff --git a/src/pages/docs/cli/connections/index.mdx b/src/pages/docs/cli/connections/index.mdx new file mode 100644 index 0000000000..0ca7951343 --- /dev/null +++ b/src/pages/docs/cli/connections/index.mdx @@ -0,0 +1,21 @@ +--- +title: "ably connections" +meta_description: "Interact with Ably Pub/Sub connections using the CLI." +meta_keywords: "ably cli, cli, connections, connection management, ably connections" +--- + +Use the `ably connections` command group to interact with [Ably Pub/Sub connections](/docs/connections). These commands allow you to monitor connection statistics, view connection logs, and test connectivity to Ably services. + +## Subcommands + +The following commands are used to manage connections: + +| Command | Description | +| ------- | ----------- | +| [`ably connections logs`](/docs/cli/connections/logs) | Alias for connection lifecycle log subscription. | +| [`ably connections stats`](/docs/cli/connections/stats) | View connection statistics for an Ably app. | +| [`ably connections test`](/docs/cli/connections/test) | Test connection to Ably services. | + + \ No newline at end of file diff --git a/src/pages/docs/cli/connections/logs.mdx b/src/pages/docs/cli/connections/logs.mdx new file mode 100644 index 0000000000..ea376cab2b --- /dev/null +++ b/src/pages/docs/cli/connections/logs.mdx @@ -0,0 +1,54 @@ +--- +title: "ably connections logs" +meta_description: "Alias for connection lifecycle log subscription using the CLI." +meta_keywords: "ably cli, cli, connections, connection logs, lifecycle logs, ably connections logs" +--- + + +```shell +ably connections logs [flags] +``` + + +Use the `ably connections logs` command to subscribe to connection lifecycle logs. This command provides information about connection events such as connections opening, closing, and status changes. + + + +For complete documentation on connection lifecycle logs, see [`ably logs connection-lifecycle subscribe`](/docs/cli/logs/connection-lifecycle/subscribe). + +## Flags + +You can optionally pass the following flags to the `ably connections logs` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably connections logs` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Subscribe to connection lifecycle logs: + + +```shell +ably connections logs +``` + + +For more examples and detailed usage, see [`ably logs connection-lifecycle subscribe`](/docs/cli/logs/connection-lifecycle/subscribe). diff --git a/src/pages/docs/cli/connections/stats.mdx b/src/pages/docs/cli/connections/stats.mdx new file mode 100644 index 0000000000..4d62d3a1b2 --- /dev/null +++ b/src/pages/docs/cli/connections/stats.mdx @@ -0,0 +1,98 @@ +--- +title: "ably connections stats" +meta_description: "View connection statistics for an Ably app using the CLI." +meta_keywords: "ably cli, cli, connections, connection stats, statistics, ably connections stats" +--- + + +```shell +ably connections stats [flags] +``` + + +Use the `ably connections stats` command to view detailed [connection statistics](/docs/connections) for your Ably app. This provides metrics on connection activity, including connection counts, rates, and trends over time. + +## Flags + +You can optionally pass the following flags to the `ably connections stats` command: + +### `--start` + +Start time in milliseconds since epoch for historical stats retrieval. + +### `--end` + +End time in milliseconds since epoch for historical stats retrieval. + +### `--unit` + +Time unit for statistics aggregation. Options are `minute`, `hour`, `day`, or `month`. The default is `minute`. + +### `--limit` + +Maximum number of statistics records to return. The default is `10`. + +### `--live` + +Subscribe to live statistics updates using minute intervals. + +### `--interval` + +Polling interval in seconds when using `--live` mode. The default is `6` seconds. + +### `--debug` + +Show debug information for live statistics polling. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably connections stats` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Get recent connection statistics: + + +```shell +ably connections stats +``` + + +Get hourly connection statistics: + + +```shell +ably connections stats --unit hour +``` + + +Get connection statistics for a specific time range: + + +```shell +ably connections stats --start 1618005600000 --end 1618091999999 +``` + + +Subscribe to live connection statistics: + + +```shell +ably connections stats --live +``` + diff --git a/src/pages/docs/cli/connections/test.mdx b/src/pages/docs/cli/connections/test.mdx new file mode 100644 index 0000000000..c3b7ddc1e7 --- /dev/null +++ b/src/pages/docs/cli/connections/test.mdx @@ -0,0 +1,69 @@ +--- +title: "ably connections test" +meta_description: "Test connection to Ably services using the CLI." +meta_keywords: "ably cli, cli, connections, connection test, connectivity, ably connections test" +--- + + +```shell +ably connections test [flags] +``` + + +Use the `ably connections test` command to test connectivity to Ably services. This helps diagnose connection issues and verify that your network configuration allows proper communication with Ably's realtime infrastructure. + +## Flags + +You can optionally pass the following flags to the `ably connections test` command: + +### `--transport` + +Transport protocol to test. Options are: +- `ws` - Test WebSocket connections only +- `xhr` - Test HTTP/XHR connections only +- `all` - Test all transport protocols (default) + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably connections test` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Test all connection transports: + + +```shell +ably connections test +``` + + +Test WebSocket connections only: + + +```shell +ably connections test --transport ws +``` + + +Test HTTP/XHR connections only: + + +```shell +ably connections test --transport xhr +``` + diff --git a/src/pages/docs/cli/help.mdx b/src/pages/docs/cli/help.mdx new file mode 100644 index 0000000000..41143bc639 --- /dev/null +++ b/src/pages/docs/cli/help.mdx @@ -0,0 +1,102 @@ +--- +title: "ably help" +meta_description: "Display help information for the Ably CLI commands." +meta_keywords: "ably cli, cli, help, command help, ably help" +--- + + +```shell +ably help [COMMAND] +``` + + +Use the `ably help` command to display help information for Ably CLI commands. When run without arguments, it shows the main help with all available command groups. When run with a specific command, it shows detailed help for that command. + +## Arguments + +Pass the following arguments to the `ably help` command: + +### `[COMMAND]` + +The command to display help for, for example: `ably help channels publish`. + +If no command is specified, displays the main help with all available command groups. + +## Flags + +You can optionally pass the following flags to the `ably help` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably help` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When run without arguments, the `ably help` command displays: + +| Property | Description | +| -------- | ----------- | +| **CLI Description** | Brief description of the Ably CLI | +| **Usage** | Basic usage syntax | +| **Commands** | List of all available command groups with brief descriptions | + +When run with a specific command, it displays detailed help for that command including usage, description, arguments, flags, and examples. + +## Examples + +Display the main help: + + +```shell +ably help +``` + + +**Output:** + +```text +ably.com CLI for Pub/Sub, Chat and Spaces + +USAGE + $ ably [COMMAND] + +COMMANDS +accounts Manage Ably accounts and your configured access tokens +apps Manage Ably apps +auth Manage authentication, keys and tokens +channels Interact with Ably Pub/Sub channels +config Open the Ably config file in the default text editor +... +``` + + +Display help for a specific command: + + +```shell +ably help channels publish +``` + + +Display help for a command group: + + +```shell +ably help channels +``` + diff --git a/src/pages/docs/cli/index.mdx b/src/pages/docs/cli/index.mdx new file mode 100644 index 0000000000..4bbc7ba68b --- /dev/null +++ b/src/pages/docs/cli/index.mdx @@ -0,0 +1,119 @@ +--- +title: "Ably CLI" +meta_description: "Command-line interface for Ably realtime messaging platform." +meta_keywords: "ably cli, cli, command line, realtime messaging, pub/sub, chat, spaces" +--- + +The Ably CLI provides a command-line interface for interacting with the Ably realtime messaging platform. Use it to manage your accounts, apps, channels, authentication, and more. + +## Installation + +Install the Ably CLI using npm: + +```shell +npm install -g @ably/cli +``` + +## Authentication + +Before using the CLI, authenticate with your Ably account: + +```shell +ably login +``` + +## Global flags + +The following global flags are supported by most CLI commands: + +### `--access-token` + +Override the access token used for the Control API. + +### `--api-key` + +Override the API key used for product APIs. + +### `--client-id` + +Override the default client ID for API authentication. + +### `--env` + +Override the environment for all product API calls. + +### `--endpoint` + +Override the endpoint for all product API calls. + +### `--host` + +Override the host endpoint for all product API calls. + +### `--json` + +Output results in JSON format. + +### `--pretty-json` + +Output results in formatted JSON. + +### `--token` + +Authenticate using an Ably Token or JWT Token. + +### `--verbose` + +Enable verbose logging. + +## Command Groups + +### Account and App Management + +| Command Group | Description | +| ------------- | ----------- | +| [`ably accounts`](/docs/cli/accounts) | Manage Ably accounts and configured access tokens | +| [`ably apps`](/docs/cli/apps) | Manage Ably applications | +| [`ably auth`](/docs/cli/auth) | Manage authentication, API keys and tokens | + +### Realtime Communication + +| Command Group | Description | +| ------------- | ----------- | +| [`ably channels`](/docs/cli/channels) | Interact with Ably Pub/Sub channels | +| [`ably rooms`](/docs/cli/rooms) | Interact with Ably Chat rooms | +| [`ably spaces`](/docs/cli/spaces) | Interact with Ably Spaces | + +### Infrastructure and Monitoring + +| Command Group | Description | +| ------------- | ----------- | +| [`ably connections`](/docs/cli/connections) | Interact with Ably Pub/Sub connections | +| [`ably integrations`](/docs/cli/integrations) | Manage Ably integrations with external services | +| [`ably logs`](/docs/cli/logs) | Stream and retrieve logs from Ably | +| [`ably queues`](/docs/cli/queues) | Manage Ably Queues | + +### Utilities and Tools + +| Command Group | Description | +| ------------- | ----------- | +| [`ably bench`](/docs/cli/bench) | Performance benchmarking commands | +| [`ably support`](/docs/cli/support) | Get support and help from Ably | +| [`ably test`](/docs/cli/test) | Testing utilities | + +### Legacy Commands + +| Command Group | Description | +| ------------- | ----------- | +| [`ably channel-rule`](/docs/cli/channel-rule) | Legacy channel rule commands (use `ably apps channel-rules` instead) | + +## Standalone Commands + +| Command | Description | +| ------- | ----------- | +| [`ably config`](/docs/cli/config) | Open the Ably config file in the default text editor | +| [`ably help`](/docs/cli/help) | Display help for ably commands | +| [`ably interactive`](/docs/cli/interactive) | Launch interactive Ably shell | +| [`ably login`](/docs/cli/login) | Log in to your Ably account | +| [`ably status`](/docs/cli/status) | Check the status of Ably services | +| [`ably version`](/docs/cli/version) | Display the CLI version | diff --git a/src/pages/docs/cli/integrations/create.mdx b/src/pages/docs/cli/integrations/create.mdx new file mode 100644 index 0000000000..25fc3f3a87 --- /dev/null +++ b/src/pages/docs/cli/integrations/create.mdx @@ -0,0 +1,108 @@ +--- +title: "ably integrations create" +meta_description: "Create an integration rule using the CLI." +meta_keywords: "ably cli, cli, integrations, create rule, ably integrations create" +--- + + +```shell +ably integrations create --rule-type --source-type [flags] +``` + + +Use the `ably integrations create` command to create a new [integration rule](/docs/integrations). Integration rules automatically forward messages, presence events, and channel lifecycle events to external systems and services. + +## Flags + +You can optionally pass the following flags to the `ably integrations create` command: + +### `--rule-type` + +The type of integration rule to create. Available options: +- `http` - HTTP webhook integration +- `amqp` - AMQP message queue integration +- `kinesis` - Amazon Kinesis integration +- `firehose` - Amazon Kinesis Data Firehose integration +- `pulsar` - Apache Pulsar integration +- `kafka` - Apache Kafka integration +- `azure` - Microsoft Azure Service Bus integration +- `azure-functions` - Azure Functions integration +- `mqtt` - MQTT integration +- `cloudmqtt` - CloudMQTT integration + +### `--source-type` + +The event source type to integrate. Available options: +- `channel.message` - Channel messages +- `channel.presence` - Channel presence events +- `channel.lifecycle` - Channel lifecycle events +- `presence.message` - Presence messages + +### `--app` + +App ID or name to create the integration rule in. If not specified, uses the current app from your CLI configuration. + +### `--channel-filter` + +Channel filter pattern to specify which channels this rule applies to. For example: `chat:*` or `notifications:*`. + +### `--target-url` + +Target URL for HTTP-based integrations. Required when using `--rule-type http`. + +### `--request-mode` + +Request mode for the integration rule. Options: +- `single` - Send individual requests for each event (default) +- `batch` - Batch multiple events into single requests + +### `--status` + +Initial status of the integration rule. Options: +- `enabled` - Rule is active (default) +- `disabled` - Rule is inactive + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably integrations create` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Create an HTTP webhook integration: + + +```shell +ably integrations create --rule-type "http" --source-type "channel.message" --target-url "https://example.com/webhook" +``` + + +Create an AMQP integration with channel filter: + + +```shell +ably integrations create --rule-type "amqp" --source-type "channel.message" --channel-filter "chat:*" +``` + + +Create a disabled integration rule: + + +```shell +ably integrations create --rule-type "http" --source-type "channel.presence" --target-url "https://example.com/presence" --status "disabled" +``` + diff --git a/src/pages/docs/cli/integrations/delete.mdx b/src/pages/docs/cli/integrations/delete.mdx new file mode 100644 index 0000000000..55dfeabca8 --- /dev/null +++ b/src/pages/docs/cli/integrations/delete.mdx @@ -0,0 +1,78 @@ +--- +title: "ably integrations delete" +meta_description: "Delete an integration rule using the CLI." +meta_keywords: "ably cli, cli, integrations, delete rule, ably integrations delete" +--- + + +```shell +ably integrations delete [flags] +``` + + +Use the `ably integrations delete` command to permanently remove an [integration rule](/docs/integrations). This action cannot be undone and will stop all event forwarding configured by the rule. + +## Arguments + +Pass the following arguments to the `ably integrations delete` command: + +### `` + +The rule ID to delete, for example: `jdDbmQ`. + +## Flags + +You can optionally pass the following flags to the `ably integrations delete` command: + +### `--app` + +App ID or name to delete the integration rule from. If not specified, uses the current app from your CLI configuration. + +### `--force | -f` + +Force deletion without confirmation prompt. Use with caution as this action is irreversible. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably integrations delete` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Delete an integration rule with confirmation: + + +```shell +ably integrations delete rule123 +``` + + +Delete a rule from a specific app: + + +```shell +ably integrations delete rule123 --app "My App" +``` + + +Delete a rule without confirmation: + + +```shell +ably integrations delete rule123 --force +``` + diff --git a/src/pages/docs/cli/integrations/get.mdx b/src/pages/docs/cli/integrations/get.mdx new file mode 100644 index 0000000000..4b9baa106a --- /dev/null +++ b/src/pages/docs/cli/integrations/get.mdx @@ -0,0 +1,66 @@ +--- +title: "ably integrations get" +meta_description: "Get an integration rule by ID using the CLI." +meta_keywords: "ably cli, cli, integrations, get rule, ably integrations get" +--- + + +```shell +ably integrations get [flags] +``` + + +Use the `ably integrations get` command to retrieve detailed information about a specific [integration rule](/docs/integrations) by its ID. This shows the complete configuration and status of the integration. + +## Arguments + +Pass the following arguments to the `ably integrations get` command: + +### `` + +The rule ID to retrieve information for, for example: `jdDbmQ`. + +## Flags + +You can optionally pass the following flags to the `ably integrations get` command: + +### `--app` + +App ID or name to get the integration rule from. If not specified, uses the current app from your CLI configuration. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably integrations get` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Get details for a specific integration rule: + + +```shell +ably integrations get rule123 +``` + + +Get integration rule from a specific app: + + +```shell +ably integrations get rule123 --app "My App" +``` + diff --git a/src/pages/docs/cli/integrations/index.mdx b/src/pages/docs/cli/integrations/index.mdx new file mode 100644 index 0000000000..6a9a177b12 --- /dev/null +++ b/src/pages/docs/cli/integrations/index.mdx @@ -0,0 +1,19 @@ +--- +title: "ably integrations" +meta_description: "Manage Ably integrations using the CLI." +meta_keywords: "ably cli, cli, integrations, integration rules, ably integrations" +--- + +Use the `ably integrations` command group to manage [Ably integrations](/docs/integrations) with external services. Integration rules allow you to automatically forward messages, presence events, and channel lifecycle events to external systems. + +## Subcommands + +The following commands are used to manage integration rules: + +| Command | Description | +| ------- | ----------- | +| [`ably integrations create`](/docs/cli/integrations/create) | Create an integration rule. | +| [`ably integrations delete`](/docs/cli/integrations/delete) | Delete an integration rule. | +| [`ably integrations get`](/docs/cli/integrations/get) | Get an integration rule by ID. | +| [`ably integrations list`](/docs/cli/integrations/list) | List all integration rules. | +| [`ably integrations update`](/docs/cli/integrations/update) | Update an integration rule. | \ No newline at end of file diff --git a/src/pages/docs/cli/integrations/list.mdx b/src/pages/docs/cli/integrations/list.mdx new file mode 100644 index 0000000000..e4395861fb --- /dev/null +++ b/src/pages/docs/cli/integrations/list.mdx @@ -0,0 +1,104 @@ +--- +title: "ably integrations list" +meta_description: "List all integration rules using the CLI." +meta_keywords: "ably cli, cli, integrations, list rules, ably integrations list" +--- + + +```shell +ably integrations list [flags] +``` + + +Use the `ably integrations list` command to display all [integration rules](/docs/integrations) configured for your Ably app. This shows details about each rule including type, source, target configuration, and status. + +## Flags + +You can optionally pass the following flags to the `ably integrations list` command: + +### `--app` + +App ID or name to list integration rules for. If not specified, uses the current app from your CLI configuration. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably integrations list` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably integrations list` command displays: + +| Property | Description | +| -------- | ----------- | +| **Context** | Current account information | +| **Rule Count** | Total number of integration rules found | +| **Rule ID** | Unique identifier for each rule | +| **App ID** | The app the rule belongs to | +| **Type** | Integration type (http, amqp, kinesis, etc.) | +| **Request Mode** | Whether requests are sent as single messages or batches | +| **Source Type** | The event source type being integrated | +| **Channel Filter** | Channel pattern filter (if any) | +| **Target** | Integration target configuration | +| **Version** | Rule version | +| **Created** | When the rule was created | +| **Updated** | When the rule was last updated | + +## Examples + +List all integration rules for the current app: + + +```shell +ably integrations list +``` + + +**Output:** + +```text +Using: Account=Ably (a12B3c) + +Found 1 integration rules: + +Rule ID: jdDbmQ + App ID: Ab1CdE + Type: http + Request Mode: single + Source Type: channel.message + Channel Filter: (none) + Target: { + "url": "https://test.com", + "signingKeyId": null, + "enveloped": true, + "format": "", + "headers": [] + } + Version: 1.0 + Created: 11/21/2024, 2:28:17 PM + Updated: 11/21/2024, 2:28:17 PM +``` + + +List integration rules for a specific app: + + +```shell +ably integrations list --app "My App" +``` + + diff --git a/src/pages/docs/cli/integrations/update.mdx b/src/pages/docs/cli/integrations/update.mdx new file mode 100644 index 0000000000..cf136ce2a2 --- /dev/null +++ b/src/pages/docs/cli/integrations/update.mdx @@ -0,0 +1,100 @@ +--- +title: "ably integrations update" +meta_description: "Update an integration rule using the CLI." +meta_keywords: "ably cli, cli, integrations, update rule, ably integrations update" +--- + + +```shell +ably integrations update [flags] +``` + + +Use the `ably integrations update` command to modify an existing [integration rule](/docs/integrations). You can update various settings including channel filters, status, target URLs, and other configuration options. + +## Arguments + +Pass the following arguments to the `ably integrations update` command: + +### `` + +The rule ID to update, for example: `jdDbmQ`. + +## Flags + +You can optionally pass the following flags to the `ably integrations update` command: + +### `--app` + +App ID or name containing the integration rule. If not specified, uses the current app from your CLI configuration. + +### `--channel-filter` + +Update the channel filter pattern to specify which channels this rule applies to. + +### `--target-url` + +Update the target URL for HTTP-based integrations. + +### `--status` + +Update the status of the integration rule. Options: +- `enabled` - Activate the rule +- `disabled` - Deactivate the rule + +### `--request-mode` + +Update the request mode for the integration rule. + +### `--source` + +Update the source configuration of the rule. + +### `--target` + +Update the target configuration of the rule. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably integrations update` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Disable an integration rule: + + +```shell +ably integrations update rule123 --status disabled +``` + + +Update the channel filter: + + +```shell +ably integrations update rule123 --channel-filter "chat:*" +``` + + +Update the target URL for an HTTP integration: + + +```shell +ably integrations update rule123 --target-url "https://new-example.com/webhook" +``` + diff --git a/src/pages/docs/cli/interactive.mdx b/src/pages/docs/cli/interactive.mdx new file mode 100644 index 0000000000..06b5554eec --- /dev/null +++ b/src/pages/docs/cli/interactive.mdx @@ -0,0 +1,49 @@ +--- +title: "ably interactive" +meta_description: "Launch the interactive Ably CLI shell (ALPHA feature)." +meta_keywords: "ably cli, cli, interactive, shell, ably interactive" +--- + + +```shell +ably interactive +``` + + +Use the `ably interactive` command to launch an interactive Ably CLI shell. This allows you to run multiple CLI commands in sequence without needing to type `ably` before each command. + + + +## Global flags + +The following global flags are supported using the `ably interactive` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Launch the interactive shell: + +```shell +ably interactive +``` + +Once in the interactive shell, you can run commands without the `ably` prefix: + +``` +ably> channels publish example-channel "Hello World" +ably> spaces list +ably> help +ably> exit +``` diff --git a/src/pages/docs/cli/login.mdx b/src/pages/docs/cli/login.mdx new file mode 100644 index 0000000000..814574c191 --- /dev/null +++ b/src/pages/docs/cli/login.mdx @@ -0,0 +1,84 @@ +--- +title: "ably login" +meta_description: "Log in to your Ably account using the CLI." +meta_keywords: "ably cli, cli, login, authentication, ably login" +--- + + +```shell +ably login [TOKEN] [flags] +``` + + +Use the `ably login` command to authenticate with your Ably account. This command is an alias for [`ably accounts login`](/docs/cli/accounts/login) and provides the same functionality. + + + +## Arguments + +Pass the following arguments to the `ably login` command: + +### `[TOKEN]` + +The access token for your Ably account, for example: `eyJ0eXAiOiJKV1Qi...`. + +If not provided, the CLI will prompt you to enter it or open a browser for authentication. + +## Flags + +You can optionally pass the following flags to the `ably login` command: + +### `--alias | -a` + +An alias name for this account configuration. If not specified, this becomes the default account. + +### `--no-browser` + +Prevent the CLI from automatically opening a browser for authentication. Use this flag if you prefer to handle authentication manually or in headless environments. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably login` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Log in with interactive authentication: + +```shell +ably login +``` + +Log in with a specific access token: + +```shell +ably login eyJ0eXAiOiJKV1Qi... +``` + +Log in with an alias for the account: + +```shell +ably login --alias mycompany +``` + +Log in without opening a browser: + +```shell +ably login --no-browser +``` diff --git a/src/pages/docs/cli/logs/index.mdx b/src/pages/docs/cli/logs/index.mdx new file mode 100644 index 0000000000..088f1c51e2 --- /dev/null +++ b/src/pages/docs/cli/logs/index.mdx @@ -0,0 +1,25 @@ +--- +title: "ably logs" +meta_description: "Stream and retrieve logs from Ably using the CLI." +meta_keywords: "ably cli, cli, logs, logging, monitoring, ably logs" +--- + +Use the `ably logs` command group to stream and retrieve logs from Ably. These commands provide access to various log types including app logs, channel lifecycle events, connection events, and push notification logs. + +## Subcommands + +The following commands are used to manage logs: + +| Command | Description | +| ------- | ----------- | +| [`ably logs app`](/docs/cli/logs/app) | Stream or retrieve logs from the app-wide meta channel. | +| [`ably logs app history`](/docs/cli/logs/app/history) | Get app log history. | +| [`ably logs app subscribe`](/docs/cli/logs/app/subscribe) | Subscribe to app logs. | +| [`ably logs channel-lifecycle`](/docs/cli/logs/channel-lifecycle) | Stream logs from the channel lifecycle meta channel. | +| [`ably logs channel-lifecycle subscribe`](/docs/cli/logs/channel-lifecycle/subscribe) | Subscribe to channel lifecycle logs. | +| [`ably logs connection-lifecycle`](/docs/cli/logs/connection-lifecycle) | Stream logs from the connection lifecycle meta channel. | +| [`ably logs connection-lifecycle history`](/docs/cli/logs/connection-lifecycle/history) | Get connection lifecycle log history. | +| [`ably logs connection-lifecycle subscribe`](/docs/cli/logs/connection-lifecycle/subscribe) | Subscribe to connection lifecycle logs. | +| [`ably logs push`](/docs/cli/logs/push) | Stream or retrieve push notification logs. | +| [`ably logs push history`](/docs/cli/logs/push/history) | Get push notification log history. | +| [`ably logs push subscribe`](/docs/cli/logs/push/subscribe) | Subscribe to push notification logs. | \ No newline at end of file diff --git a/src/pages/docs/cli/queues/create.mdx b/src/pages/docs/cli/queues/create.mdx new file mode 100644 index 0000000000..a9f8582e96 --- /dev/null +++ b/src/pages/docs/cli/queues/create.mdx @@ -0,0 +1,82 @@ +--- +title: "ably queues create" +meta_description: "Create an Ably Queue using the CLI." +meta_keywords: "ably cli, cli, queues, create queue, ably queues create" +--- + + +```shell +ably queues create --name [flags] +``` + + +Use the `ably queues create` command to create a new [Ably Queue](/docs/queues). Queues provide reliable, ordered message delivery with built-in persistence and replay capabilities for your applications. + +## Flags + +You can optionally pass the following flags to the `ably queues create` command: + +### `--name` + +The name for the new queue. This is a required field that will be used to identify your queue. + +### `--app` + +App ID or name to create the queue in. If not specified, uses the current app from your CLI configuration. + +### `--max-length` + +Maximum number of messages the queue can hold. The default is `10000` messages. + +### `--region` + +AWS region where the queue will be hosted. The default is `us-east-1-a`. + +### `--ttl` + +Time to live for messages in seconds. The default is `60` seconds. This determines how long messages remain in the queue before being automatically removed. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably queues create` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Create a basic queue: + + +```shell +ably queues create --name "my-queue" +``` + + +Create a queue with custom TTL and max length: + + +```shell +ably queues create --name "my-queue" --ttl 3600 --max-length 100000 +``` + + +Create a queue in a specific region and app: + + +```shell +ably queues create --name "my-queue" --region "eu-west-1-a" --app "My App" +``` + diff --git a/src/pages/docs/cli/queues/delete.mdx b/src/pages/docs/cli/queues/delete.mdx new file mode 100644 index 0000000000..e04d736cca --- /dev/null +++ b/src/pages/docs/cli/queues/delete.mdx @@ -0,0 +1,78 @@ +--- +title: "ably queues delete" +meta_description: "Delete an Ably Queue using the CLI." +meta_keywords: "ably cli, cli, queues, delete queue, ably queues delete" +--- + + +```shell +ably queues delete [flags] +``` + + +Use the `ably queues delete` command to permanently remove an [Ably Queue](/docs/queues). This action cannot be undone and will delete all messages and configuration associated with the queue. + +## Arguments + +Pass the following arguments to the `ably queues delete` command: + +### `` + +The name of the queue to delete, for example: `my-queue`. + +## Flags + +You can optionally pass the following flags to the `ably queues delete` command: + +### `--app` + +App ID or name to delete the queue from. If not specified, uses the current app from your CLI configuration. + +### `--force | -f` + +Force deletion without confirmation prompt. Use with caution as this action is irreversible. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably queues delete` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +Delete a queue with confirmation: + + +```shell +ably queues delete my-queue +``` + + +Delete a queue from a specific app: + + +```shell +ably queues delete my-queue --app "My App" +``` + + +Delete a queue without confirmation: + + +```shell +ably queues delete my-queue --force +``` + diff --git a/src/pages/docs/cli/queues/index.mdx b/src/pages/docs/cli/queues/index.mdx new file mode 100644 index 0000000000..0fb9589441 --- /dev/null +++ b/src/pages/docs/cli/queues/index.mdx @@ -0,0 +1,17 @@ +--- +title: "ably queues" +meta_description: "Manage Ably Queues using the CLI." +meta_keywords: "ably cli, cli, queues, message queues, ably queues" +--- + +Use the `ably queues` command group to manage [Ably Queues](/docs/queues). Queues provide reliable, ordered message delivery with built-in persistence and replay capabilities. + +## Subcommands + +The following commands are used to manage queues: + +| Command | Description | +| ------- | ----------- | +| [`ably queues create`](/docs/cli/queues/create) | Create a new queue. | +| [`ably queues delete`](/docs/cli/queues/delete) | Delete an existing queue. | +| [`ably queues list`](/docs/cli/queues/list) | List all queues. | \ No newline at end of file diff --git a/src/pages/docs/cli/queues/list.mdx b/src/pages/docs/cli/queues/list.mdx new file mode 100644 index 0000000000..d24915495f --- /dev/null +++ b/src/pages/docs/cli/queues/list.mdx @@ -0,0 +1,105 @@ +--- +title: "ably queues list" +meta_description: "List all Ably Queues using the CLI." +meta_keywords: "ably cli, cli, queues, list queues, ably queues list" +--- + + +```shell +ably queues list [flags] +``` + + +Use the `ably queues list` command to display all [Ably Queues](/docs/queues) in your current app. This provides comprehensive information about each queue including connection details, message counts, and configuration settings. + +## Flags + +You can optionally pass the following flags to the `ably queues list` command: + +### `--app` + +App ID or name to list queues for. If not specified, uses the current app from your CLI configuration. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably queues list` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably queues list` command displays: + +| Property | Description | +| -------- | ----------- | +| **Context** | Current account, app, and key being used | +| **Queue Count** | Total number of queues found | +| **Queue ID** | Unique identifier for each queue | +| **Name** | The queue name | +| **Region** | AWS region where the queue is hosted | +| **State** | Current operational state of the queue | +| **AMQP Connection** | URI and queue name for AMQP connections | +| **STOMP Connection** | URI, host, and destination for STOMP connections | +| **Message Stats** | Ready, unacknowledged, and total message counts | +| **TTL** | Time to live for messages in seconds | +| **Max Length** | Maximum number of messages the queue can hold | +| **Deadletter Queue ID** | Associated deadletter queue (if any) | + +## Examples + +List all queues for the current app: + + +```shell +ably queues list +``` + + +**Output:** + +```text +Using: Account=Ably (a12B3c) • App=example-app (Ab1CdE) • Key=Root (Ab1CdE.F2ghIJ) + +Found 2 queues: + +Queue ID: Ab1CdE:us-east-1-a:adfsgt + Name: adfsgt + Region: us-east-1-a + State: Running + AMQP: + URI: amqps://us-east-1-a-queue.ably.io:5671/shared + Queue Name: Ab1CdE:adfsgt + STOMP: + URI: stomp://us-east-1-a-queue.ably.io:61614 + Host: shared + Destination: /amqp/queue/Ab1CdE:adfsgt + Messages: + Ready: 0 + Unacknowledged: 0 + Total: 0 + TTL: 60 seconds + Max Length: 10000 messages +``` + + +List queues for a specific app: + + +```shell +ably queues list --app "My App" +``` + + diff --git a/src/pages/docs/cli/rooms/index.mdx b/src/pages/docs/cli/rooms/index.mdx new file mode 100644 index 0000000000..1af7066452 --- /dev/null +++ b/src/pages/docs/cli/rooms/index.mdx @@ -0,0 +1,59 @@ +--- +title: "ably rooms" +meta_description: "Manage Ably Chat rooms using the CLI - send messages, manage presence, and monitor occupancy." +meta_keywords: "ably cli, cli, rooms, chat rooms, ably chat, realtime messaging" +--- + +Use the `ably rooms` command group to manage [Ably Chat](/docs/products/chat) rooms. + +## Subcommands + +The following commands are used to send and subscribe to messages: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms list`](/docs/cli/rooms/list) | List the active chat rooms in your app. | +| [`ably rooms messages send`](/docs/cli/rooms/messages/send) | Send a message to a chat room. | +| [`ably rooms messages subscribe`](/docs/cli/rooms/messages/subscribe) | Subscribe to messages in a chat room. | +| [`ably rooms messages history`](/docs/cli/rooms/messages/history) | Get historical messages from a chat room. | + +The following commands are used to send and subscribe to message reactions: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms messages reactions`](/docs/cli/rooms/messages/reactions) | Manage the message reactions in a chat room. | +| [`ably rooms messages reactions send`](/docs/cli/rooms/messages/reactions/send) | Send a reaction to a message in a chat room. | +| [`ably rooms messages reactions remove`](/docs/cli/rooms/messages/reactions/remove) | Remove a reaction from a message in a chat room. | +| [`ably rooms messages reactions subscribe`](/docs/cli/rooms/messages/reactions/subscribe) | Subscribe to message reactions in a room. | + +The following commands are used to enter and view the presence of members in a room: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms presence`](/docs/cli/rooms/presence) | Manage the presence set of a room. | +| [`ably rooms presence enter`](/docs/cli/rooms/presence/enter) | Enter presence in a chat room and listen for events. | +| [`ably rooms presence subscribe`](/docs/cli/rooms/presence/subscribe) | Subscribe to presence events in a room. | + +The following commands are used to view the occupancy metrics of a room: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms occupancy`](/docs/cli/rooms/occupancy) | Manage the occupancy of a room. | +| [`ably rooms occupancy get`](/docs/cli/rooms/occupancy/get) | Get current occupancy metrics for a room. | +| [`ably rooms occupancy subscribe`](/docs/cli/rooms/occupancy/subscribe) | Subscribe to occupancy events in a room. | + +The following commands are used to send and subscribe to room-level reactions: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms reactions`](/docs/cli/rooms/reactions) | Manage reactions in a room. | +| [`ably rooms reactions send`](/docs/cli/rooms/reactions/send) | Send a reaction in a chat room. | +| [`ably rooms reactions subscribe`](/docs/cli/rooms/reactions/subscribe) | Subscribe to reactions in a room. | + +The following commands are used to manage typing indicators: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms typing`](/docs/cli/rooms/typing) | Manage typing indicators in a room. | +| [`ably rooms typing keystroke`](/docs/cli/rooms/typing/keystroke) | Send a typing indicator in a chat room. | +| [`ably rooms typing subscribe`](/docs/cli/rooms/typing/subscribe) | Subscribe to typing indicators in a room. | diff --git a/src/pages/docs/cli/rooms/list.mdx b/src/pages/docs/cli/rooms/list.mdx new file mode 100644 index 0000000000..1d6534b97d --- /dev/null +++ b/src/pages/docs/cli/rooms/list.mdx @@ -0,0 +1,91 @@ +--- +title: "ably rooms list" +meta_description: "List active chat rooms in your Ably app using the CLI." +meta_keywords: "ably cli, cli, command, chat rooms, room enumeration, active rooms, room list" +--- + + +```shell +ably rooms list [flags] +``` + + +Use the `ably rooms list` command to list the active chat rooms in your app. + +## Flags + +You can optionally pass the following flags to the `ably rooms list` command: + +### `--limit` + +Maximum number of rooms to return. The default is `100`. The maximum is `1000`. + +### `--prefix | -p` + +Filter rooms by prefix. Only rooms whose names start with the specified prefix will be returned. + +## Global flags + +The following global flags are supported using the `ably rooms list` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### List all active chat rooms + +Get a list of all currently active chat rooms: + + +```shell +ably rooms list +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +No active chat rooms found. +``` + + +### List rooms with a limit + +Get only the first 5 active chat rooms: + + +```shell +ably rooms list --limit 5 +``` + + +### Filter rooms by prefix + +List only rooms that start with "game-": + + +```shell +ably rooms list --prefix "game-" +``` + + +### Filter with prefix and limit + +Get the first 3 rooms starting with "chat-": + + +```shell +ably rooms list --prefix "chat-" --limit 3 +``` + diff --git a/src/pages/docs/cli/rooms/messages/history.mdx b/src/pages/docs/cli/rooms/messages/history.mdx new file mode 100644 index 0000000000..9996db21f9 --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/history.mdx @@ -0,0 +1,109 @@ +--- +title: "ably rooms messages history" +meta_description: "Get historical messages from an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, message history, chat history, chat rooms, historical data" +--- + + +```shell +ably rooms messages history [flags] +``` + + +Use the `ably rooms messages history` command to get historical messages from an Ably Chat room. + +Chat messages are stored for 30 days by default. + + + +## Arguments + +Pass the following argument to the `ably rooms messages history` command: + +### `` + +The room to get message history from, for example: `example-room`. + +## Flags + +You can optionally pass the following flags to the `ably rooms messages history` command: + +### `--limit | -l` + +Maximum number of messages to retrieve. The default is `20`. Maximum allowed is `1000`. + +### `--show-metadata` + +Display message metadata if available. Set to `true` to show metadata. The default is `false`. + +## Global flags + +The following global flags are supported using the `ably rooms messages history` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +Each message in the history includes: + +| Property | Description | +| -------- | ----------- | +| Timestamp | When the message was published in ISO 8601 format. | +| Client ID | The client ID of the message sender. | +| Message Content | The text content of the message. | +| Metadata | Additional metadata if available and `--show-metadata` is passed. | + +## Examples + +### Get recent message history + +Get the last 10 messages from a chat room: + + +```shell +ably rooms messages history example-room --limit 10 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Fetching 10 most recent messages from room: example-room +Retrieved 1 messages. +--- +[10:25:03 AM] ably-cli-abc123: Hello from the CLI +``` + + +### Get history with metadata + +Get message history including any metadata: + + +```shell +ably rooms messages history example-room --show-metadata +``` + + +### Get all available history + +Retrieve the restricted number of messages: + + +```shell +ably rooms messages history example-room --limit 5 +``` + diff --git a/src/pages/docs/cli/rooms/messages/index.mdx b/src/pages/docs/cli/rooms/messages/index.mdx new file mode 100644 index 0000000000..52bc7e0fcd --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/index.mdx @@ -0,0 +1,26 @@ +--- +title: "ably rooms messages" +meta_description: "Manage messages in Ably Chat rooms using the CLI." +meta_keywords: "ably cli, cli, chat messages, room messages, chat rooms, realtime messaging" +--- + +Use the `ably rooms messages` command group to manage messages in [Ably Chat](/docs/products/chat) rooms. + +## Subcommands + +The following commands are used to send and subscribe to messages: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms messages send`](/docs/cli/rooms/messages/send) | Send a message to a chat room. | +| [`ably rooms messages subscribe`](/docs/cli/rooms/messages/subscribe) | Subscribe to messages in a chat room. | +| [`ably rooms messages history`](/docs/cli/rooms/messages/history) | Get historical messages from a chat room. | + +The following commands are used to send and subscribe to message reactions: + +| Command | Description | +| ------- | ----------- | +| [`ably rooms messages reactions`](/docs/cli/rooms/messages/reactions) | Manage the message reactions in a chat room. | +| [`ably rooms messages reactions send`](/docs/cli/rooms/messages/reactions/send) | Send a reaction to a message in a chat room. | +| [`ably rooms messages reactions remove`](/docs/cli/rooms/messages/reactions/remove) | Remove a reaction from a message in a chat room. | +| [`ably rooms messages reactions subscribe`](/docs/cli/rooms/messages/reactions/subscribe) | Subscribe to message reactions in a room. | diff --git a/src/pages/docs/cli/rooms/messages/reactions/index.mdx b/src/pages/docs/cli/rooms/messages/reactions/index.mdx new file mode 100644 index 0000000000..915e0b421f --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/reactions/index.mdx @@ -0,0 +1,15 @@ +--- +title: "ably rooms messages reactions" +meta_description: "Manage message reactions in Ably Chat rooms using the CLI." +meta_keywords: "ably cli, cli, message reactions, chat reactions, room reactions, emoji reactions" +--- + +Use the `ably rooms messages reactions` command group to manage reactions on messages in [Ably Chat](/docs/products/chat) rooms. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably rooms messages reactions send`](/docs/cli/rooms/messages/reactions/send) | Send a reaction to a message in a chat room. | +| [`ably rooms messages reactions remove`](/docs/cli/rooms/messages/reactions/remove) | Remove a reaction from a message in a chat room. | +| [`ably rooms messages reactions subscribe`](/docs/cli/rooms/messages/reactions/subscribe) | Subscribe to message reactions in a room. | \ No newline at end of file diff --git a/src/pages/docs/cli/rooms/messages/reactions/remove.mdx b/src/pages/docs/cli/rooms/messages/reactions/remove.mdx new file mode 100644 index 0000000000..56131c4bac --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/reactions/remove.mdx @@ -0,0 +1,87 @@ +--- +title: "ably rooms messages reactions remove" +meta_description: "Remove a reaction from a message in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, message reactions, remove reaction, delete reaction, chat reactions" +--- + + +```shell +ably rooms messages reactions remove [flags] +``` + + +Use the `ably rooms messages reactions remove` command to remove a reaction from a message in a chat room. + +## Arguments + +Pass the following arguments to the `ably rooms messages reactions remove` command: + +### `` + +The room where the message is located, for example: `example-room`. + +### `` + +The serial ID of the message to remove the reaction from. + +### `` + +The reaction to remove, for example: `👍`, `❤️`, or `😂`. + +## Flags + +You can optionally pass the following flags to the `ably rooms messages reactions remove` command: + +### `--type` + +The [type](/docs/chat/rooms/message-reactions#types-of-reactions) of reaction to remove. Options are: + +* `unique` - Remove a unique reaction +* `distinct` - Remove a distinct reaction +* `multiple` - Remove a multiple reaction + +## Global flags + +The following global flags are supported using the `ably rooms messages reactions remove` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Remove a reaction from a message + +Remove a thumbs up reaction from a message with a valid serial: + + +```shell +ably rooms messages reactions remove example-room 108iQRG9AB0LSS@1726651442980-0 👍 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +✓ Removed reaction 👍 from message 108iQRG9AB0LSS@1726651442980-0 in room example-room +``` + + +### Remove reaction with type specification + +Remove a unique reaction from a message: + + +```shell +ably rooms messages reactions remove example-room 108iQRG9AB0LSS@1726651442980-0 👍 --type unique +``` + diff --git a/src/pages/docs/cli/rooms/messages/reactions/send.mdx b/src/pages/docs/cli/rooms/messages/reactions/send.mdx new file mode 100644 index 0000000000..b9b9a7247b --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/reactions/send.mdx @@ -0,0 +1,103 @@ +--- +title: "ably rooms messages reactions send" +meta_description: "Send a reaction to a message in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, message reactions, send reaction, emoji reactions, chat reactions" +--- + + +```shell +ably rooms messages reactions send [flags] +``` + + +Use the `ably rooms messages reactions send` command to send a reaction to a message in a chat room. + +Use another terminal instance and the [`ably rooms messages reactions subscribe`](/docs/cli/rooms/messages/reactions/subscribe) command to monitor reactions in realtime. + +## Arguments + +Pass the following arguments to the `ably rooms messages reactions send` command: + +### `` + +The room where the message is located, for example: `example-room`. + +### `` + +The serial ID of the message to react to, for example: `12345:00`. + +### `` + +The reaction to send, for example: `👍`, `❤️`, or `😂`. + +## Flags + +You can optionally pass the following flags to the `ably rooms messages reactions send` command: + +### `--type` + +The [type](/docs/chat/rooms/message-reactions#types-of-reactions) of reaction to send. Options are: + +* `unique` - Remove a unique reaction +* `distinct` - Remove a distinct reaction +* `multiple` - Remove a multiple reaction + +### `--count` + +Count value for Multiple type reactions. This is used when `--type` is set to `multiple`. + +## Global flags + +The following global flags are supported using the `ably rooms messages reactions send` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Send a basic reaction + +Send a thumbs up reaction to a message: + + +```shell +ably rooms messages reactions send example-room 12345:000 👍 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +✓ Sent reaction 👍 to message 123345:000 in room example-room +``` + + +### Send a reaction with specific type + +Send a heart reaction with unique type: + + +```shell +ably rooms messages reactions send example-room 12345:000 ❤️ --type unique +``` + + +### Send a multiple reaction with count + +Send a reaction that can be counted multiple times: + + +```shell +ably rooms messages reactions send example-room 12345:000 👍 --type multiple --count 5 +``` + diff --git a/src/pages/docs/cli/rooms/messages/reactions/subscribe.mdx b/src/pages/docs/cli/rooms/messages/reactions/subscribe.mdx new file mode 100644 index 0000000000..d8741603c4 --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/reactions/subscribe.mdx @@ -0,0 +1,73 @@ +--- +title: "ably rooms messages reactions subscribe" +meta_description: "Subscribe to reaction events for messages in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, message reactions, reaction events, realtime reactions, chat reactions" +--- + + +```shell +ably rooms messages reactions subscribe +``` + + +Use the `ably rooms messages reactions subscribe` command to subscribe to reaction events for messages in a chat room. This allows you to monitor when reactions are added or removed from messages in realtime. + +Use another terminal instance and the [`ably rooms messages reactions send`](/docs/cli/rooms/messages/reactions/send) command to send reactions that you can see in the subscription. + +## Arguments + +Pass the following argument to the `ably rooms messages reactions subscribe` command: + +### `` + +The room to subscribe to reaction events for, for example: `example-room`. + +## Global flags + +The following global flags are supported using the `ably rooms messages reactions subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Subscribe to reaction events + +Monitor all reaction events in a room: + + +```shell +ably rooms messages reactions subscribe example-room +``` + + +You can test this functionality by sending a message reaction in another terminal instance: + + +```shell +ably rooms messages reactions send example-room 12345:000 👍 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connecting to Ably and subscribing to message reactions in room example-room... +Successfully connected to Ably +Listening for message reactions in room example-room. Press Ctrl+C to exit. + +[2025-09-23T17:28:53.519Z] 📊 Reaction summary for message 12345:000: + Distinct reactions: + 👍: 1 (ably-cli-f28320fa) +``` + diff --git a/src/pages/docs/cli/rooms/messages/send.mdx b/src/pages/docs/cli/rooms/messages/send.mdx new file mode 100644 index 0000000000..ecb78f8dfe --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/send.mdx @@ -0,0 +1,99 @@ +--- +title: "ably rooms messages send" +meta_description: "Send messages to an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, chat messages, send message, chat rooms, messaging" +--- + + +```shell +ably rooms messages send [flags] +``` + + +Use the `ably rooms messages send` command to send a message to an Ably Chat room. + +Use another terminal instance and the [`ably rooms messages subscribe`](/docs/cli/rooms/messages/subscribe) command to receive the sent messages. + +## Arguments + +Pass the following arguments to the `ably rooms messages send` command: + +### `` + +The room to send the message to, for example: `example-room`. + +### `` + +The message text to send, for example: `"Hello everyone!"`. + +## Flags + +You can optionally pass the following flags to the `ably rooms messages send` command: + +### `--count | -c` + +The number of messages to send. The default is `1`. + +### `--delay | -d` + +The delay between messages being sent, in milliseconds. The default is `40`. + +### `--metadata` + +Additional metadata for the message in JSON format, for example: `{"priority":"high","category":"announcement"}`. + +## Global flags + +The following global flags are supported using the `ably rooms messages send` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Send a simple message + +Send a basic message to a chat room: + + +```shell +ably rooms messages send example-room "Hello everyone!" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Message sent successfully. +``` + + +### Send multiple messages + +Send 3 messages with a delay between them: + + +```shell +ably rooms messages send example-room "Countdown message" --count 3 --delay 1000 +``` + + +### Send a message with metadata + +Send a message with additional metadata: + + +```shell +ably rooms messages send example-room "Important announcement" --metadata '{"priority":"high","category":"announcement"}' +``` + diff --git a/src/pages/docs/cli/rooms/messages/subscribe.mdx b/src/pages/docs/cli/rooms/messages/subscribe.mdx new file mode 100644 index 0000000000..ed1d9df49a --- /dev/null +++ b/src/pages/docs/cli/rooms/messages/subscribe.mdx @@ -0,0 +1,105 @@ +--- +title: "ably rooms messages subscribe" +meta_description: "Subscribe to messages in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, subscribe messages, chat rooms, realtime messaging" +--- + + +```shell +ably rooms messages subscribe [flags] +``` + + +Use the `ably rooms messages subscribe` command to subscribe to messages in an Ably Chat room. + +Use another terminal instance and the [`ably rooms messages send`](/docs/cli/rooms/messages/send) command to send messages that will be received by this subscriber. + +The subscriber will run continuously unless you specify a [`--duration`](#duration), or you stop it using `Ctrl+C`. + +## Arguments + +Pass the following argument to the `ably rooms messages subscribe` command: + +### `` + +The room to subscribe to messages from, for example: `example-room`. + +## Flags + +You can optionally pass the following flags to the `ably rooms messages subscribe` command: + +### `--show-metadata` + +Display message metadata if available. Set to `true` to show metadata. The default is `false`. + +### `--duration | -D` + +Automatically stop subscribing after the given number of seconds. Set to `0` to run indefinitely. The default is `0`. + +## Global flags + +The following global flags are supported using the `ably rooms messages subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Subscribe to messages in a room + +Subscribe to receive messages from a chat room: + + +```shell +ably rooms messages subscribe example-room +``` + + +You can test this functionality by sending a message in another terminal instance: + + +```shell +ably rooms messages send example-room "Hello from terminal 2!" +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Attaching to room: example-room... +Connected to room: example-room +✓ Subscribed to room: example-room. Listening for messages... + +[19:09:57] ably-cli-6078837e: Hello from terminal 2! +``` + + +### Show the metadata of sent messages + +Subscribe to messages and display any metadata they contain: + + +```shell +ably rooms messages subscribe example-room --show-metadata +``` + + +### Subscribe with automatic exit + +Subscribe for 30 seconds then automatically exit: + + +```shell +ably rooms messages subscribe example-room --duration 30 +``` + diff --git a/src/pages/docs/cli/rooms/occupancy/get.mdx b/src/pages/docs/cli/rooms/occupancy/get.mdx new file mode 100644 index 0000000000..9c446bdd24 --- /dev/null +++ b/src/pages/docs/cli/rooms/occupancy/get.mdx @@ -0,0 +1,69 @@ +--- +title: "ably rooms occupancy get" +meta_description: "Get current occupancy metrics for an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, occupancy, room occupancy, realtime metrics, connection count" +--- + + +```shell +ably rooms occupancy get +``` + + +Use the `ably rooms occupancy get` command to get current occupancy metrics for a room. Occupancy metrics display high-level metrics about the clients attached to a room, such as the number of connections. + +## Arguments + +Pass the following argument to the `ably rooms occupancy get` command: + +### `` + +The room to get occupancy metrics for, for example: `example-room`. + +## Global flags + +The following global flags are supported using the `ably rooms occupancy get` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +Each occupancy event includes the following metrics: + +| Metric | Description | +| ------ | ----------- | +| Connections | The number of connections. | +| Presence Members | The number of members currently entered into presence in the room. | + +## Examples + +### Get occupancy for a room + +Get the current occupancy metrics: + + +```shell +ably rooms occupancy get example-room +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Occupancy metrics for room 'example-room': + +Connections: 1 +Presence Members: 0 +``` + diff --git a/src/pages/docs/cli/rooms/occupancy/index.mdx b/src/pages/docs/cli/rooms/occupancy/index.mdx new file mode 100644 index 0000000000..65ccebff5d --- /dev/null +++ b/src/pages/docs/cli/rooms/occupancy/index.mdx @@ -0,0 +1,14 @@ +--- +title: "ably rooms occupancy" +meta_description: "Manage the occupancy of a room using the Ably CLI." +meta_keywords: "ably cli, cli, occupancy, room occupancy, realtime metrics, connection count" +--- + +Use the `ably rooms occupancy` command group to manage the [occupancy](/docs/presence-occupancy/occupancy) of a room. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably rooms occupancy get`](/docs/cli/rooms/occupancy/get) | Get current occupancy metrics for a room. | +| [`ably rooms occupancy subscribe`](/docs/cli/rooms/occupancy/subscribe) | Subscribe to occupancy events in a room. | \ No newline at end of file diff --git a/src/pages/docs/cli/rooms/occupancy/subscribe.mdx b/src/pages/docs/cli/rooms/occupancy/subscribe.mdx new file mode 100644 index 0000000000..f4ff3404e3 --- /dev/null +++ b/src/pages/docs/cli/rooms/occupancy/subscribe.mdx @@ -0,0 +1,75 @@ +--- +title: "ably rooms occupancy subscribe" +meta_description: "Subscribe to occupancy events for an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, occupancy, room occupancy, realtime metrics, occupancy events" +--- + + +```shell +ably rooms occupancy subscribe +``` + + +Use the `ably rooms occupancy subscribe` command to subscribe to occupancy events for a room. Occupancy events are emitted when the occupancy metrics change, such as when clients join or leave a room. + +## Arguments + +Pass the following argument to the `ably rooms occupancy subscribe` command: + +### `` + +The room to subscribe to occupancy events for, for example: `example-room`. + +## Global flags + +The following global flags are supported using the `ably rooms occupancy subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +Each occupancy event includes the following metrics: + +| Metric | Description | +| ------ | ----------- | +| Connections | The number of connections. | +| Presence Members | The number of members currently entered into presence in the room. | + +## Examples + +### Subscribe to occupancy events + +Monitor occupancy changes for a room: + + +```shell +ably rooms occupancy subscribe example-room +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully connected to Ably +Subscribing to occupancy events for room 'example-room'... +Listening for occupancy updates. Press Ctrl+C to exit. +[2025-09-18T08:34:19.912Z] Initial occupancy for room 'example-room' + Connections: 1 + Presence Members: 0 + +[2025-09-18T08:34:19.942Z] Occupancy update for room 'example-room' + Connections: 2 + Presence Members: 1 +``` + diff --git a/src/pages/docs/cli/rooms/presence/enter.mdx b/src/pages/docs/cli/rooms/presence/enter.mdx new file mode 100644 index 0000000000..eb3472c9ef --- /dev/null +++ b/src/pages/docs/cli/rooms/presence/enter.mdx @@ -0,0 +1,93 @@ +--- +title: "ably rooms presence enter" +meta_description: "Enter presence in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, presence, room presence, chat presence, online status" +--- + + +```shell +ably rooms presence enter [flags] +``` + + +Use the `ably rooms presence enter` command to enter presence in a chat room and remain present until terminated. This enables other clients to see that you are currently active in the room. + +Use another terminal instance and the [`ably rooms presence subscribe`](/docs/cli/rooms/presence/subscribe) command to subscribe to presence events. + +## Arguments + +Pass the following argument to the `ably rooms presence enter` command: + +### `` + +The room to enter presence in, for example: `example-room`. + +## Flags + +You can optionally pass the following flags to the `ably rooms presence enter` command: + +### `--data` + +Optional presence data to include when entering, as a JSON string. + +## Global flags + +The following global flags are supported using the `ably rooms presence enter` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When you enter the presence set of a channel using the CLI, you'll see a list of members currently present. + +The actions associated with each event are: + +| Action | Description | +| ------ | ----------- | +| Enter | A client has entered the presence set. | +| Update | A client has updated their presence data. | +| Leave | A client has left the presence set. | +| Present | A client is currently present. This is used to list the members currently in the presence set when a client first joins. | + +## Examples + +### Enter presence in a room + +Enter presence in a room and stay active: + + +```shell +ably rooms presence enter example-room +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully connected to room: example-room +✓ Entered room example-room as ably-cli-12asd21 + +Listening for presence events. Press Ctrl+C to exit. +``` + + +### Enter presence with custom data + +Enter presence with additional user information: + + +```shell +ably rooms presence enter example-room --data '{"status": "working", "location": "office"}' +``` + diff --git a/src/pages/docs/cli/rooms/presence/index.mdx b/src/pages/docs/cli/rooms/presence/index.mdx new file mode 100644 index 0000000000..4df13bf656 --- /dev/null +++ b/src/pages/docs/cli/rooms/presence/index.mdx @@ -0,0 +1,14 @@ +--- +title: "ably rooms presence" +meta_description: "Manage presence in Ably Chat rooms using the CLI - enter rooms and subscribe to presence events." +meta_keywords: "ably cli, cli, rooms, presence, ably chat, member presence, online status" +--- + +Use the `ably rooms presence` command group to manage the [presence set](/docs/products/chat/rooms#presence) of a room. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably rooms presence enter`](/docs/cli/rooms/presence/enter) | Enter presence in a chat room and listen for events. | +| [`ably rooms presence subscribe`](/docs/cli/rooms/presence/subscribe) | Subscribe to presence events in a room. | \ No newline at end of file diff --git a/src/pages/docs/cli/rooms/presence/subscribe.mdx b/src/pages/docs/cli/rooms/presence/subscribe.mdx new file mode 100644 index 0000000000..4a31113944 --- /dev/null +++ b/src/pages/docs/cli/rooms/presence/subscribe.mdx @@ -0,0 +1,84 @@ +--- +title: "ably rooms presence subscribe" +meta_description: "Subscribe to presence events in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, presence, presence events, room presence, realtime presence" +--- + + +```shell +ably rooms presence subscribe +``` + + +Use the `ably rooms presence subscribe` command to subscribe to presence events in a chat room. This allows you to be notified when users enter or leave the room. + +Use another terminal instance and the [`ably rooms presence enter`](/docs/cli/rooms/presence/enter) command to enter presence and see the events. + +## Arguments + +Pass the following argument to the `ably rooms presence subscribe` command: + +### `` + +The room to subscribe to presence events for, for example: `example-room`. + +## Global flags + +The following global flags are supported using the `ably rooms presence subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When you enter the presence set of a channel using the CLI, you'll see a list of members currently present. + +The actions associated with each event are: + +| Action | Description | +| ------ | ----------- | +| Enter | A client has entered the presence set. | +| Update | A client has updated their presence data. | +| Leave | A client has left the presence set. | +| Present | A client is currently present. This is used to list the members currently in the presence set when a client first joins. | + +## Examples + +### Subscribe to presence events + +Subscribe to all presence events in a room: + + +```shell +ably rooms presence subscribe example-room +``` + + +You can test this by entering presence in another terminal instances: + + +```shell +ably rooms presence enter example-room +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully connected to room: example-app +[2025-09-23T14:57:22.667Z] • ably-cli-71343df1 present +✓ Entered room example-app as ably-cli-73bc9ef6 + +Listening for presence events. Press Ctrl+C to exit. +``` + diff --git a/src/pages/docs/cli/rooms/reactions/index.mdx b/src/pages/docs/cli/rooms/reactions/index.mdx new file mode 100644 index 0000000000..8d43e8d9ee --- /dev/null +++ b/src/pages/docs/cli/rooms/reactions/index.mdx @@ -0,0 +1,14 @@ +--- +title: "ably rooms reactions" +meta_description: "Manage reactions in Ably Chat rooms using the CLI - send reactions and subscribe to reaction events." +meta_keywords: "ably cli, cli, rooms, reactions, ably chat, emoji reactions, realtime reactions" +--- + +Use the `ably rooms reactions` command group to manage [room-level reactions](/docs/products/chat/rooms#reactions) in an Ably Chat room. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably rooms reactions send`](/docs/cli/rooms/reactions/send) | Send a reaction in a chat room. | +| [`ably rooms reactions subscribe`](/docs/cli/rooms/reactions/subscribe) | Subscribe to reactions in a room. | diff --git a/src/pages/docs/cli/rooms/reactions/send.mdx b/src/pages/docs/cli/rooms/reactions/send.mdx new file mode 100644 index 0000000000..30ea59ac96 --- /dev/null +++ b/src/pages/docs/cli/rooms/reactions/send.mdx @@ -0,0 +1,116 @@ +--- +title: "ably rooms reactions send" +meta_description: "Send a reaction in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, rooms, reactions, emoji, reaction send, ably chat" +--- + + +```shell +ably rooms reactions send [flags] +``` + + +Use the `ably rooms reactions send` command to send a reaction in a chat room. Room reactions are not tied to a specific message, and are for users to show their sentiment as to what is happening within the room. + +Use another terminal instance and the [`ably rooms reactions subscribe`](/docs/cli/rooms/reactions/subscribe) command to view reactions as they are sent. + +## Arguments + +### `` + +The room to send the reaction to, for example: `example-room`. + +### `` + +The emoji reaction to send, for example: `👍`, `❤️`, or `😂`. + +## Flags + +You can optionally pass the following flags to the `ably rooms reactions send` command: + +### `--metadata` + +Additional metadata to send with the reaction as a JSON string, for example: `{"source":"cli","timestamp":123456789}`. + +## Global flags + +The following global flags are supported using the `ably rooms reactions send` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Send a basic reaction + +Send a thumbs up reaction to a room: + + +```shell +ably rooms reactions send example-room 👍 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +✓ Sent reaction 👍 in room example-room +``` + + +### Send a reaction with metadata + +Send a reaction with additional metadata: + + +```shell +ably rooms reactions send example-room ❤️ --metadata '{"source":"cli","timestamp":123456789}' +``` + + +### Send a reaction with JSON output + +Send a reaction and receive structured JSON response: + + +```shell +ably rooms reactions send example-room ❤️ --metadata '{"source":"cli","timestamp":123456789}' --json +``` + + +**Output:** + +```json +{ + "emoji": "❤️", + "metadata": { + "source": "cli", + "timestamp": 123456789 + }, + "room": "example-room", + "success": true +} +``` + + +### Send different emoji reactions + +Send various emoji reactions: + + +```shell +ably rooms reactions send example-room 🎉 +ably rooms reactions send example-room 😂 +ably rooms reactions send example-room 🔥 +``` + diff --git a/src/pages/docs/cli/rooms/reactions/subscribe.mdx b/src/pages/docs/cli/rooms/reactions/subscribe.mdx new file mode 100644 index 0000000000..a238371ed7 --- /dev/null +++ b/src/pages/docs/cli/rooms/reactions/subscribe.mdx @@ -0,0 +1,68 @@ +--- +title: "ably rooms reactions subscribe" +meta_description: "Subscribe to reactions in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, rooms, reactions, reaction subscribe, reaction events, ably chat" +--- + + +```shell +ably rooms reactions subscribe [flags] +``` + + +Use the `ably rooms reactions subscribe` command to subscribe to reactions in a chat room. Room reactions are not tied to a specific message, and are for users to show their sentiment as to what is happening within the room. + +Use another terminal instance and the [`ably rooms reactions send`](/docs/cli/rooms/reactions/send) command to send reactions that will be received by this subscription. + +## Arguments + +### `` + +The room to subscribe to reactions in, for example: `example-room`. + +## Global flags + +The following global flags are supported using the `ably rooms reactions subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Subscribe to reactions + +Subscribe to all reactions in a room: + + +```shell +ably rooms reactions subscribe example-room +``` + + +You can test this functionality by sending a room reaction in another terminal instance: + + +```shell +ably rooms reactions send example-room 🎉 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connecting to Ably and subscribing to reactions in room example-room... +Successfully connected to Ably +Listening for reactions in room example-room. Press Ctrl+C to exit. +[2025-09-18T09:30:14.418Z] ⚡ ably-cli-4a22e34a reacted with 🎉 +``` + diff --git a/src/pages/docs/cli/rooms/typing/index.mdx b/src/pages/docs/cli/rooms/typing/index.mdx new file mode 100644 index 0000000000..7038082dfe --- /dev/null +++ b/src/pages/docs/cli/rooms/typing/index.mdx @@ -0,0 +1,14 @@ +--- +title: "ably rooms typing" +meta_description: "Manage typing indicators in Ably Chat rooms using the CLI - send typing indicators and subscribe to typing events." +meta_keywords: "ably cli, cli, rooms, typing, typing indicators, ably chat, realtime typing" +--- + +Use the `ably rooms typing` command group to manage [typing indicators](/docs/products/chat/rooms#typing-indicators) in a room. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably rooms typing keystroke`](/docs/cli/rooms/typing/keystroke) | Send a typing indicator in a chat room. | +| [`ably rooms typing subscribe`](/docs/cli/rooms/typing/subscribe) | Subscribe to typing indicators in a room. | \ No newline at end of file diff --git a/src/pages/docs/cli/rooms/typing/keystroke.mdx b/src/pages/docs/cli/rooms/typing/keystroke.mdx new file mode 100644 index 0000000000..d376f53772 --- /dev/null +++ b/src/pages/docs/cli/rooms/typing/keystroke.mdx @@ -0,0 +1,88 @@ +--- +title: "ably rooms typing keystroke" +meta_description: "Send a typing indicator in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, rooms, typing, typing keystroke, typing indicators, ably chat" +--- + + +```shell +ably rooms typing keystroke [flags] +``` + + +Use the `ably rooms typing keystroke` command to emit a typing event update in an Ably Chat room. + +Use another terminal instance and the [`ably rooms typing subscribe`](/docs/cli/rooms/typing/subscribe) command to view typing events as they are sent. + +## Arguments + +### `` + +The room to start typing in, for example: `example-room`. + +## Flags + +You can optionally pass the following flags to the `ably rooms typing keystroke` command: + +### `--autoType` + +Automatically keep a typing indicator active by repeatedly sending typing events until the command is terminated. Without this flag, only a single typing event is sent. + +## Global flags + +The following global flags are supported using the `ably rooms typing keystroke` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Send a single typing indicator event + +Send a single typing keystroke event: + + +```shell +ably rooms typing keystroke example-room +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connected to room: example-room +Started typing in room. +Sent a single typing indicator. Use --autoType flag to keep typing automatically. Press Ctrl+C to exit. +``` + + +### Send continuous typing indicator events + +Send continuous typing events until terminated: + + +```shell +ably rooms typing keystroke example-room --autoType +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connected to room: example-room +Started typing in room. +Will automatically remain typing until this command is terminated. Press Ctrl+C to exit. +``` + diff --git a/src/pages/docs/cli/rooms/typing/subscribe.mdx b/src/pages/docs/cli/rooms/typing/subscribe.mdx new file mode 100644 index 0000000000..be984906d9 --- /dev/null +++ b/src/pages/docs/cli/rooms/typing/subscribe.mdx @@ -0,0 +1,67 @@ +--- +title: "ably rooms typing subscribe" +meta_description: "Subscribe to typing indicators in an Ably Chat room using the CLI." +meta_keywords: "ably cli, cli, command, rooms, typing, typing subscribe, typing indicators, ably chat" +--- + + +```shell +ably rooms typing subscribe [flags] +``` + + +Use the `ably rooms typing subscribe` command to subscribe to typing indicators in an Ably Chat room. + +Use another terminal instance and the [`ably rooms typing keystroke`](/docs/cli/rooms/typing/keystroke) command to send typing indicator events that will be received by this subscription. + +## Arguments + +### `` + +The room to subscribe to typing indicators from, for example: `example-room`. + +## Global flags + +The following global flags are supported using the `ably rooms typing subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Examples + +### Subscribe to typing indicators + +Subscribe to all typing indicators in a room: + + +```shell +ably rooms typing subscribe example-room +``` + + +You can test this functionality by sending a typing indicator event in another terminal instance: + + +```shell +ably rooms typing keystroke example-room +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connected to room: example-room +Listening for typing indicators. Press Ctrl+C to exit. +ably-cli-2850ab20 is typing... +``` + diff --git a/src/pages/docs/cli/spaces/cursors/get-all.mdx b/src/pages/docs/cli/spaces/cursors/get-all.mdx new file mode 100644 index 0000000000..26468203c0 --- /dev/null +++ b/src/pages/docs/cli/spaces/cursors/get-all.mdx @@ -0,0 +1,112 @@ +--- +title: "ably spaces cursors get-all" +meta_description: "Get all current cursors in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, cursors, cursor get-all, cursor positions, ably spaces" +--- + + +```shell +ably spaces cursors get-all [flags] +``` + + +Use the `ably spaces cursors get-all` command to get all current cursors in a space. + +Use the [`ably spaces cursors set`](/docs/cli/spaces/cursors/set) command to create cursor positions that can then be retrieved with this command. + +## Arguments + +### `` + +The space name to get cursors from, for example: `example-space`. + +## Global flags + +The following global flags are supported using the `ably spaces cursors get-all` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +For each cursor found in the space, the following information is displayed: + +| Property | Description | +| -------- | ----------- | +| Client ID | The unique identifier for the client that set the cursor | +| X | The x coordinate of the cursor position | +| Y | The y coordinate of the cursor position | +| Connection | The connection ID associated with the cursor | +| Additional Data | Any additional data associated with the cursor | + +## Examples + +### Get all cursors + +Get all current cursor positions in a space: + + +```shell +ably spaces cursors get-all example-space +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connecting to space: example-space... +Successfully entered space: example-space +Collecting cursor positions for 5 seconds... +──────────────────────────────────────────────────────────── +──────────────────────────────────────────────────────────── + +Cursor Summary - 1 cursor found: + +┌──────────────────────┬──────────┬──────────┬──────────────────────┐ +│ Client ID │ X │ Y │ Connection │ +├──────────────────────┼──────────┼──────────┼──────────────────────┤ +│ ably-cli-8c251ff3 │ 300 │ 400 │ sa4NcG809y │ +└──────────────────────┴──────────┴──────────┴──────────────────────┘ + +Additional Data: + ably-cli-8c251ff3: {"color":"red","name":"TestCursor"} +``` + + +### Get all cursors with JSON output + +Get all cursors with structured JSON output: + + +```shell +ably spaces cursors get-all example-space --json +``` + + +**Output:** + +```json +{ + "connectionId": "WycVWgoUWe", + "space": "example-space", + "status": "connected", + "success": true +} +{ + "cursors": [], + "space": "example-space", + "success": true, + "cursorUpdateReceived": false +} +``` + diff --git a/src/pages/docs/cli/spaces/cursors/index.mdx b/src/pages/docs/cli/spaces/cursors/index.mdx new file mode 100644 index 0000000000..e6f96734e7 --- /dev/null +++ b/src/pages/docs/cli/spaces/cursors/index.mdx @@ -0,0 +1,15 @@ +--- +title: "ably spaces cursors" +meta_description: "Manage cursors in Ably Spaces using the CLI - set positions, subscribe to movements, and get current cursors." +meta_keywords: "ably cli, cli, spaces, cursors, ably spaces, cursor tracking, realtime cursors, collaborative experiences" +--- + +Use the `ably spaces cursors` command group to manage [cursors](/docs/products/spaces/features/cursors) in a space. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably spaces cursors set`](/docs/cli/spaces/cursors/set) | Set a cursor with position data in a space. | +| [`ably spaces cursors subscribe`](/docs/cli/spaces/cursors/subscribe) | Subscribe to cursor movements in a space. | +| [`ably spaces cursors get-all`](/docs/cli/spaces/cursors/get-all) | Get all current cursors in a space. | \ No newline at end of file diff --git a/src/pages/docs/cli/spaces/cursors/set.mdx b/src/pages/docs/cli/spaces/cursors/set.mdx new file mode 100644 index 0000000000..ae1f1c7812 --- /dev/null +++ b/src/pages/docs/cli/spaces/cursors/set.mdx @@ -0,0 +1,129 @@ +--- +title: "ably spaces cursors set" +meta_description: "Set a cursor with position data in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, cursors, cursor set, position, ably spaces" +--- + + +```shell +ably spaces cursors set [flags] +``` + + +Use the `ably spaces cursors set` command to set a cursor with position data in a space. + +Use another terminal instance and the [`ably spaces cursors subscribe`](/docs/cli/spaces/cursors/subscribe) command to view cursor movements as they occur, or use [`ably spaces cursors get-all`](/docs/cli/spaces/cursors/get-all) to view all current cursor positions. + +## Arguments + +### `` + +The space name to set cursor in, for example: `example-space`. + +## Flags + +You can optionally pass the following flags to the `ably spaces cursors set` command: + +### `--x` + +The x coordinate for cursor position. + +### `--y` + +The y coordinate for cursor position. + +### `--data` + +The cursor data to set as a JSON string, for example: `{"name": "John", "color": "#ff0000"}`. + +### `--simulate` + +Simulate cursor movement every 250ms with random positions. + +### `--duration | -D` + +Automatically exit after the given number of seconds. Use `0` to exit immediately after setting the cursor (default behavior). + +## Global flags + +The following global flags are supported using the `ably spaces cursors set` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When setting a cursor, you will see confirmation that the cursor has been set with the specified data and position information. + +## Examples + +### Set a cursor with coordinates + +Set a cursor at position x:100, y:200: + + +```shell +ably spaces cursors set example-space --x 100 --y 200 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Entered space: example-space +✓ Set cursor in space example-space with data: {"position":{"x":100,"y":200}} +Cursor set. Press Ctrl+C to exit. +``` + + +### Set a cursor with additional data + +Set a cursor with position and additional metadata: + + +```shell +ably spaces cursors set example-space --x 300 --y 400 --data '{"color":"red","name":"TestCursor"}' +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Entered space: example-space +✓ Set cursor in space example-space with data: {"position":{"x":300,"y":400},"data":{"color":"red","name":"TestCursor"}} +Waiting 2s before exiting… Press Ctrl+C to exit sooner. +Duration elapsed – command finished cleanly. +``` + + +### Set a cursor with automatic exit + +Set a cursor and exit after 5 seconds: + + +```shell +ably spaces cursors set example-space --x 150 --y 250 --duration 5 +``` + + +### Simulate cursor movement + +Simulate random cursor movement: + + +```shell +ably spaces cursors set example-space --simulate +``` + diff --git a/src/pages/docs/cli/spaces/cursors/subscribe.mdx b/src/pages/docs/cli/spaces/cursors/subscribe.mdx new file mode 100644 index 0000000000..6dd15bbf5b --- /dev/null +++ b/src/pages/docs/cli/spaces/cursors/subscribe.mdx @@ -0,0 +1,90 @@ +--- +title: "ably spaces cursors subscribe" +meta_description: "Subscribe to cursor movements in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, cursors, cursor subscribe, cursor tracking, ably spaces" +--- + + +```shell +ably spaces cursors subscribe [flags] +``` + + +Use the `ably spaces cursors subscribe` command to subscribe to cursor movements in a space. + +Use another terminal instance and the [`ably spaces cursors set`](/docs/cli/spaces/cursors/set) command to generate cursor events that will be received by this subscription. + +## Arguments + +### `` + +The space name to subscribe to cursors for, for example: `example-space`. + +## Flags + +You can optionally pass the following flags to the `ably spaces cursors subscribe` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Use `0` to run indefinitely (default behavior). + +## Global flags + +The following global flags are supported using the `ably spaces cursors subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When subscribing to cursor movements, you will see notifications as cursors are moved by other clients in the space. + +## Examples + +### Subscribe to cursor movements + +Subscribe to cursor movements in a space: + + +```shell +ably spaces cursors subscribe example-space +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Subscribing to cursor movements +✓ Subscribed to space: example-space. Listening for cursor movements... +``` + + +### Subscribe with JSON output + +Subscribe to cursor movements with structured JSON output: + + +```shell +ably spaces cursors subscribe example-space --json +``` + + +### Subscribe for a limited time + +Subscribe to cursor movements for 30 seconds then exit: + + +```shell +ably spaces cursors subscribe example-space --duration 30 +``` + diff --git a/src/pages/docs/cli/spaces/index.mdx b/src/pages/docs/cli/spaces/index.mdx new file mode 100644 index 0000000000..5cbc4cffc0 --- /dev/null +++ b/src/pages/docs/cli/spaces/index.mdx @@ -0,0 +1,51 @@ +--- +title: "ably spaces" +meta_description: "Manage Ably Spaces using the CLI - manage members, cursors, locations, and locks." +meta_keywords: "ably cli, cli, spaces, ably spaces, collaborative experiences, realtime collaboration" +--- + +Use the `ably spaces` command group to manage [Ably Spaces](/docs/products/spaces). + +## Subcommands + +The following command is used to list spaces: + +| Command | Description | +| ------- | ----------- | +| [`ably spaces list`](/docs/cli/spaces/list) | List the active spaces in your app. | + +The following commands are used to manage members in spaces: + +| Command | Description | +| ------- | ----------- | +| [`ably spaces members`](/docs/cli/spaces/members) | Manage members in a space. | +| [`ably spaces members enter`](/docs/cli/spaces/members/enter) | Enter a space and remain present until terminated. | +| [`ably spaces members subscribe`](/docs/cli/spaces/members/subscribe) | Subscribe to member presence events in a space. | + +The following commands are used to manage cursors in spaces: + +| Command | Description | +| ------- | ----------- | +| [`ably spaces cursors`](/docs/cli/spaces/cursors) | Manage cursors in a space. | +| [`ably spaces cursors set`](/docs/cli/spaces/cursors/set) | Set a cursor with position data in a space. | +| [`ably spaces cursors subscribe`](/docs/cli/spaces/cursors/subscribe) | Subscribe to cursor movements in a space. | +| [`ably spaces cursors get-all`](/docs/cli/spaces/cursors/get-all) | Get all current cursors in a space. | + +The following commands are used to manage locations in spaces: + +| Command | Description | +| ------- | ----------- | +| [`ably spaces locations`](/docs/cli/spaces/locations) | Manage locations in a space. | +| [`ably spaces locations set`](/docs/cli/spaces/locations/set) | Set your location in a space. | +| [`ably spaces locations subscribe`](/docs/cli/spaces/locations/subscribe) | Subscribe to location updates in a space. | +| [`ably spaces locations get-all`](/docs/cli/spaces/locations/get-all) | Get all current locations in a space. | + +The following commands are used to manage locks in spaces: + +| Command | Description | +| ------- | ----------- | +| [`ably spaces locks`](/docs/cli/spaces/locks) | Manage locks in a space. | +| [`ably spaces locks acquire`](/docs/cli/spaces/locks/acquire) | Acquire a lock in a space. | +| [`ably spaces locks subscribe`](/docs/cli/spaces/locks/subscribe) | Subscribe to lock changes in a space. | +| [`ably spaces locks get`](/docs/cli/spaces/locks/get) | Get information about a specific lock. | +| [`ably spaces locks get-all`](/docs/cli/spaces/locks/get-all) | Get all current locks in a space. | \ No newline at end of file diff --git a/src/pages/docs/cli/spaces/list.mdx b/src/pages/docs/cli/spaces/list.mdx new file mode 100644 index 0000000000..e4ec102e4e --- /dev/null +++ b/src/pages/docs/cli/spaces/list.mdx @@ -0,0 +1,99 @@ +--- +title: "ably spaces list" +meta_description: "List active spaces in your Ably app using the CLI." +meta_keywords: "ably cli, cli, command, spaces, space enumeration, active spaces, space list" +--- + + +```shell +ably spaces list [flags] +``` + + +Use the `ably spaces list` command to list the active spaces in your app. + +## Flags + +You can optionally pass the following flags to the `ably spaces list` command: + +### `--limit` + +Maximum number of spaces to return. The default is `100`. Maximum allowed is `1000`. + +### `--prefix | -p` + +Filter spaces by prefix. Only spaces whose names start with the specified prefix will be returned. + +## Global flags + +The following global flags are supported using the `ably spaces list` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +For each active space, the following information is displayed: + +| Property | Description | +| -------- | ----------- | +| Space | The unique name of each space. | + +## Examples + +### List all active spaces + +Get a list of all currently active spaces: + + +```shell +ably spaces list +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +No active spaces found. +``` + + +### List spaces with a limit + +Get only the first 5 active spaces: + + +```shell +ably spaces list --limit 5 +``` + + +### Filter spaces by prefix + +List only spaces that start with "game-": + + +```shell +ably spaces list --prefix "game-" +``` + + +### Filter with prefix and limit + +Get the first 3 spaces starting with "collab-": + + +```shell +ably spaces list --prefix "collab-" --limit 3 +``` + diff --git a/src/pages/docs/cli/spaces/locations/get-all.mdx b/src/pages/docs/cli/spaces/locations/get-all.mdx new file mode 100644 index 0000000000..67cdcbb32c --- /dev/null +++ b/src/pages/docs/cli/spaces/locations/get-all.mdx @@ -0,0 +1,84 @@ +--- +title: "ably spaces locations get-all" +meta_description: "Get all current locations in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, locations, location get-all, member locations, ably spaces" +--- + + +```shell +ably spaces locations get-all [flags] +``` + + +Use the `ably spaces locations get-all` command to get all current locations in a space. + +Use the [`ably spaces locations set`](/docs/cli/spaces/locations/set) command to create member locations that can then be retrieved with this command. + +## Arguments + +### `` + +The space name to get locations from, for example: `example-space`. + +## Flags + +You can optionally pass the following flags to the `ably spaces locations get-all` command: + +### `--format | -f` + +Output format. Options are `text` (default) or `json`. + +## Global flags + +The following global flags are supported using the `ably spaces locations get-all` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +For each member with a location set in the space, the location information is displayed. If no locations are currently set, a message indicating this will be shown. + +## Examples + +### Get all locations + +Get all current member locations in a space: + + +```shell +ably spaces locations get-all example-space +``` + + +**Output when no locations are set:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connecting to space: example-space... +Connected to space: example-space +Fetching locations for space example-space... +No locations are currently set in this space. + +Successfully disconnected. +``` + + +### Get all locations with JSON output + +Get all locations with structured JSON output: + + +```shell +ably spaces locations get-all example-space --json +``` + diff --git a/src/pages/docs/cli/spaces/locations/index.mdx b/src/pages/docs/cli/spaces/locations/index.mdx new file mode 100644 index 0000000000..85ce0cdf0b --- /dev/null +++ b/src/pages/docs/cli/spaces/locations/index.mdx @@ -0,0 +1,15 @@ +--- +title: "ably spaces locations" +meta_description: "Manage locations in Ably Spaces using the CLI - set member locations, subscribe to updates, and get current locations." +meta_keywords: "ably cli, cli, spaces, locations, ably spaces, location tracking, member locations, collaborative experiences" +--- + +Use the `ably spaces locations` command group to manage [member locations](/docs/products/spaces/features/member-location) in a space. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably spaces locations set`](/docs/cli/spaces/locations/set) | Set your location in a space. | +| [`ably spaces locations subscribe`](/docs/cli/spaces/locations/subscribe) | Subscribe to location updates in a space. | +| [`ably spaces locations get-all`](/docs/cli/spaces/locations/get-all) | Get all current locations in a space. | \ No newline at end of file diff --git a/src/pages/docs/cli/spaces/locations/set.mdx b/src/pages/docs/cli/spaces/locations/set.mdx new file mode 100644 index 0000000000..e531d6c5a5 --- /dev/null +++ b/src/pages/docs/cli/spaces/locations/set.mdx @@ -0,0 +1,127 @@ +--- +title: "ably spaces locations set" +meta_description: "Set your location in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, locations, location set, member location, ably spaces" +--- + + +```shell +ably spaces locations set --location [flags] +``` + + +Use the `ably spaces locations set` command to set your location in a space. + +Use another terminal instance and the [`ably spaces locations subscribe`](/docs/cli/spaces/locations/subscribe) command to view location updates as they occur, or use [`ably spaces locations get-all`](/docs/cli/spaces/locations/get-all) to view all current member locations. + +## Arguments + +### `` + +The space name to set location in, for example: `example-space`. + +## Flags + +Pass the following argument to the `ably spaces locations set` command: + +### `--location` + +Location data to set in JSON format. This is required and can contain any location information relevant to your application, for example: +- `{"x":10,"y":20}` for coordinates +- `{"sectionId":"section1","page":3}` for document sections +- `{"room":"A","floor":2}` for physical locations + +You can optionally pass the following flags to the `ably spaces locations set` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Use `0` to exit immediately after setting location (default behavior). + +## Global flags + +The following global flags are supported using the `ably spaces locations set` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When setting a location, you will see confirmation that the location has been successfully set with the specified data. + +## Examples + +### Set coordinates location + +Set your location using x,y coordinates: + + +```shell +ably spaces locations set example-space --location '{"x":10,"y":20}' +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully set location: { + "x": 10, + "y": 20 +} + +Watching for other location changes. Press Ctrl+C to exit. +``` + + +### Set document section location + +Set your location within a document using section ID and page: + + +```shell +ably spaces locations set example-space --location '{"sectionId":"section1","page":3}' +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully set location: { + "sectionId": "section1", + "page": 3 +} + +Watching for other location changes. Press Ctrl+C to exit. +``` + + +### Set physical location + +Set your location using room and floor information: + + +```shell +ably spaces locations set example-space --location '{"room":"A","floor":2}' +``` + + +### Set location with automatic exit + +Set your location and exit after 5 seconds: + + +```shell +ably spaces locations set example-space --location '{"x":50,"y":75}' --duration 5 +``` + diff --git a/src/pages/docs/cli/spaces/locations/subscribe.mdx b/src/pages/docs/cli/spaces/locations/subscribe.mdx new file mode 100644 index 0000000000..f8809e6c8f --- /dev/null +++ b/src/pages/docs/cli/spaces/locations/subscribe.mdx @@ -0,0 +1,103 @@ +--- +title: "ably spaces locations subscribe" +meta_description: "Subscribe to location updates for members in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, locations, location subscribe, location updates, ably spaces" +--- + + +```shell +ably spaces locations subscribe [flags] +``` + + +Use the `ably spaces locations subscribe` command to subscribe to location updates for members in a space. + +Use another terminal instance and the [`ably spaces locations set`](/docs/cli/spaces/locations/set) command to generate location events that will be received by this subscription. + +## Arguments + +### `` + +The space name to subscribe to locations for, for example: `example-space`. + +## Flags + +You can optionally pass the following flags to the `ably spaces locations subscribe` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Use `0` to run indefinitely (default behavior). + +## Global flags + +The following global flags are supported using the `ably spaces locations subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When subscribing to location updates, you will see the current locations and any subsequent location changes as they occur. + +| Property | Description | +| -------- | ----------- | +| Connection ID | The connection ID of the member | +| Location | The location data for the member (null if not set) | + +## Examples + +### Subscribe to location updates + +Subscribe to location updates in a space: + + +```shell +ably spaces locations subscribe example-space +``` + + +**Output:** + +```text +Subscribing to location updates +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connecting to space: example-space... +Fetching current locations for space example-space... + +Current locations (1): + +- Connection ID: rLiwkbW-4y + Location: null + +Subscribing to location updates. Press Ctrl+C to exit. +``` + + +### Subscribe with JSON output + +Subscribe to location updates with structured JSON output: + + +```shell +ably spaces locations subscribe example-space --json +``` + + +### Subscribe for a limited time + +Subscribe to location updates for 30 seconds then exit: + + +```shell +ably spaces locations subscribe example-space --duration 30 +``` + diff --git a/src/pages/docs/cli/spaces/locks/acquire.mdx b/src/pages/docs/cli/spaces/locks/acquire.mdx new file mode 100644 index 0000000000..3a30fe028f --- /dev/null +++ b/src/pages/docs/cli/spaces/locks/acquire.mdx @@ -0,0 +1,101 @@ +--- +title: "ably spaces locks acquire" +meta_description: "Acquire a lock in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, locks, lock acquire, component locking, ably spaces" +--- + + +```shell +ably spaces locks acquire [flags] +``` + + +Use the `ably spaces locks acquire` command to acquire a lock in a space. + +Use another terminal instance and the [`ably spaces locks subscribe`](/docs/cli/spaces/locks/subscribe) command to view lock events as they occur, or use [`ably spaces locks get`](/docs/cli/spaces/locks/get) to view information about a specific lock. + +## Arguments + +### `` + +The space name to acquire lock in, for example: `example-space`. + +### `` + +The ID of the lock to acquire, for example: `test-lock-1`. + +## Flags + +You can optionally pass the following flags to the `ably spaces locks acquire` command: + +### `--data` + +Optional data to associate with the lock in JSON format, for example: `{"type":"editor","priority":"high"}`. + +## Global flags + +The following global flags are supported using the `ably spaces locks acquire` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When acquiring a lock, you will see confirmation that the lock has been successfully acquired along with the lock details including status and timestamp information. + +| Property | Description | +| -------- | ----------- | +| lockId | The unique identifier for the lock | +| member | Information about the member who acquired the lock | +| status | The current status of the lock (pending, locked, etc.) | +| timestamp | When the lock was acquired | + +## Examples + +### Acquire a basic lock + +Acquire a lock without additional data: + + +```shell +ably spaces locks acquire example-space test-lock-1 +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully acquired lock: test-lock-1 +Lock details: { + "lockId": "test-lock-1", + "member": { + "clientId": "ably-cli-3007cc5b", + "connectionId": "qnKw9-Ud4c" + }, + "status": "pending", + "timestamp": 1758185980770 +} + +Holding lock. Press Ctrl+C to release and exit. +``` + + +### Acquire a lock with data + +Acquire a lock with additional metadata: + + +```shell +ably spaces locks acquire example-space test-lock-2 --data '{"type":"editor","priority":"high"}' +``` + diff --git a/src/pages/docs/cli/spaces/locks/get-all.mdx b/src/pages/docs/cli/spaces/locks/get-all.mdx new file mode 100644 index 0000000000..69aaf47489 --- /dev/null +++ b/src/pages/docs/cli/spaces/locks/get-all.mdx @@ -0,0 +1,111 @@ +--- +title: "ably spaces locks get-all" +meta_description: "Get all current locks in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, locks, lock get-all, all locks, ably spaces" +--- + + +```shell +ably spaces locks get-all [flags] +``` + + +Use the `ably spaces locks get-all` command to get all current locks in a space. + +Use the [`ably spaces locks acquire`](/docs/cli/spaces/locks/acquire) command to create locks that can then be retrieved with this command. + +## Arguments + +### `` + +The space name to get locks from, for example: `example-space`. + +## Global flags + +The following global flags are supported using the `ably spaces locks get-all` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +For each lock found in the space, information is displayed including the lock ID, status, and holder details. + +| Property | Description | +| -------- | ----------- | +| Lock ID | The unique identifier for the lock | +| Status | The current status of the lock (locked, pending, etc.) | +| Holder | The client ID of the member holding the lock | + +## Examples + +### Get all locks + +Get all current locks in a space: + + +```shell +ably spaces locks get-all example-space +``` + + +**Output:** + +```text +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Connecting to space: example-space... +Connected to space: example-space +Fetching locks for space example-space... + +Current locks (1): + +- test-lock-2: + Status: locked + Holder: ably-cli-3a147ce2 + +Successfully disconnected. +``` + + +### Get all locks with JSON output + +Get all locks with structured JSON output: + + +```shell +ably spaces locks get-all example-space --json +``` + + +**Output:** + +```json +{ + "locks": [ + { + "attributes": {}, + "holder": "ably-cli-3a147ce2", + "id": "test-lock-2", + "status": "locked" + } + ], + "space": "example-space", + "success": true, + "timestamp": "2025-09-18T09:07:22.568Z" +} +{ + "space": "example-space", + "status": "left", + "success": true +} +``` + diff --git a/src/pages/docs/cli/spaces/locks/get.mdx b/src/pages/docs/cli/spaces/locks/get.mdx new file mode 100644 index 0000000000..da338cd316 --- /dev/null +++ b/src/pages/docs/cli/spaces/locks/get.mdx @@ -0,0 +1,95 @@ +--- +title: "ably spaces locks get" +meta_description: "Get information about a specific lock in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, locks, lock get, lock information, ably spaces" +--- + + +```shell +ably spaces locks get [flags] +``` + + +Use the `ably spaces locks get` command to get information about a specific lock in a space. + +Use the [`ably spaces locks acquire`](/docs/cli/spaces/locks/acquire) command to create locks that can then be retrieved with this command. + +## Arguments + +### `` + +The space name to get lock from, for example: `example-space`. + +### `` + +The lock ID to get information about, for example: `test-lock-1`. + +## Global flags + +The following global flags are supported using the `ably spaces locks get` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +Information about the specified lock is displayed, including its status, holder, and timestamp details. + +| Property | Description | +| -------- | ----------- | +| status | The current status of the lock (locked, pending, etc.) | +| timestamp | When the lock was last updated | +| member | Information about the member holding the lock | +| id | The unique identifier for the lock | + +## Examples + +### Get lock information + +Get information about a specific lock: + + +```shell +ably spaces locks get example-space test-lock-2 +``` + + +**Output:** + +```json +{ + "status": "locked", + "timestamp": 1758186271761, + "member": { + "clientId": "ably-cli-3a147ce2", + "connectionId": "5CbuSem5_1", + "isConnected": true, + "profileData": null, + "location": null, + "lastEvent": { + "name": "present", + "timestamp": 1758186272096 + } + }, + "id": "test-lock-2" +} +``` + + +### Get lock information with JSON output + +Get lock information with structured JSON output: + + +```shell +ably spaces locks get example-space test-lock-1 --json +``` + diff --git a/src/pages/docs/cli/spaces/locks/index.mdx b/src/pages/docs/cli/spaces/locks/index.mdx new file mode 100644 index 0000000000..4cf18abf9f --- /dev/null +++ b/src/pages/docs/cli/spaces/locks/index.mdx @@ -0,0 +1,16 @@ +--- +title: "ably spaces locks" +meta_description: "Manage locks in Ably Spaces using the CLI - acquire locks, subscribe to changes, and get lock information." +meta_keywords: "ably cli, cli, spaces, locks, ably spaces, component locking, collaborative experiences" +--- + +Use the `ably spaces locks` command group to manage [component locking](/docs/products/spaces/features/locking) in a space. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably spaces locks acquire`](/docs/cli/spaces/locks/acquire) | Acquire a lock in a space. | +| [`ably spaces locks subscribe`](/docs/cli/spaces/locks/subscribe) | Subscribe to lock changes in a space. | +| [`ably spaces locks get`](/docs/cli/spaces/locks/get) | Get information about a specific lock. | +| [`ably spaces locks get-all`](/docs/cli/spaces/locks/get-all) | Get all current locks in a space. | \ No newline at end of file diff --git a/src/pages/docs/cli/spaces/locks/subscribe.mdx b/src/pages/docs/cli/spaces/locks/subscribe.mdx new file mode 100644 index 0000000000..e9c99b9a46 --- /dev/null +++ b/src/pages/docs/cli/spaces/locks/subscribe.mdx @@ -0,0 +1,80 @@ +--- +title: "ably spaces locks subscribe" +meta_description: "Subscribe to lock events in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, locks, lock subscribe, lock events, ably spaces" +--- + + +```shell +ably spaces locks subscribe [flags] +``` + + +Use the `ably spaces locks subscribe` command to subscribe to lock events in a space. + +Use another terminal instance and the [`ably spaces locks acquire`](/docs/cli/spaces/locks/acquire) command to generate lock events that will be received by this subscription. + +## Arguments + +### `` + +The space name to subscribe to locks for, for example: `example-space`. + +## Flags + +You can optionally pass the following flags to the `ably spaces locks subscribe` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Use `0` to run indefinitely (default behavior). + +## Global flags + +The following global flags are supported using the `ably spaces locks subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When subscribing to lock events, you will see notifications as locks are acquired, released, or modified by other clients in the space. + +## Examples + +### Subscribe to lock events + +Subscribe to lock events in a space: + + +```shell +ably spaces locks subscribe example-space +``` + + +### Subscribe with JSON output + +Subscribe to lock events with structured JSON output: + + +```shell +ably spaces locks subscribe example-space --json +``` + + +### Subscribe for a limited time + +Subscribe to lock events for 30 seconds then exit: + + +```shell +ably spaces locks subscribe example-space --duration 30 +``` + diff --git a/src/pages/docs/cli/spaces/members/enter.mdx b/src/pages/docs/cli/spaces/members/enter.mdx new file mode 100644 index 0000000000..47c80c57a9 --- /dev/null +++ b/src/pages/docs/cli/spaces/members/enter.mdx @@ -0,0 +1,112 @@ +--- +title: "ably spaces members enter" +meta_description: "Enter an Ably Space and remain present until terminated using the CLI." +meta_keywords: "ably cli, cli, command, spaces, members, space enter, presence, ably spaces" +--- + + +```shell +ably spaces members enter [flags] +``` + + +Use the `ably spaces members enter` command to enter a space and remain present as a member until the process is terminated. + +Use another terminal instance and the [`ably spaces members subscribe`](/docs/cli/spaces/members/subscribe) command to view member events as they occur. + +## Arguments + +### `` + +The space name to enter, for example: `example-space`. + +## Flags + +You can optionally pass the following flags to the `ably spaces members enter` command: + +### `--profile` + +Optional profile data to include with the member in JSON format, for example: `{"name":"User","status":"active"}`. + +### `--duration | -D` + +Automatically exit after the given number of seconds. Use `0` to run indefinitely (default behavior). + +## Global flags + +The following global flags are supported using the `ably spaces members enter` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When entering a space, you will see confirmation that you have successfully entered, and the command will continue running to maintain your presence until terminated. + +## Examples + +### Enter a space + +Enter a space and remain present: + + +```shell +ably spaces members enter example-space +``` + + +**Output:** + +```text +Entering space. Press Ctrl+C to exit. +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully entered space: example-space + +Watching for other members. Press Ctrl+C to exit. +``` + + +### Enter a space with profile data + +Enter a space with additional profile information: + + +```shell +ably spaces members enter example-space --profile '{"name":"TestUser","role":"admin"}' +``` + + +**Output:** + +```text +Entering space. Press Ctrl+C to exit. +Using: App=example-app (Ab1CdE) • Key=example-key (Ab1CdE.FgHiJk) + +Successfully entered space: example-space +Profile: { + "name": "TestUser", + "role": "admin" +} + +Watching for other members. Press Ctrl+C to exit. +``` + + +### Enter a space with automatic exit + +Enter a space for 30 seconds then exit automatically: + + +```shell +ably spaces members enter example-space --duration 30 +``` + diff --git a/src/pages/docs/cli/spaces/members/index.mdx b/src/pages/docs/cli/spaces/members/index.mdx new file mode 100644 index 0000000000..0c28983cc6 --- /dev/null +++ b/src/pages/docs/cli/spaces/members/index.mdx @@ -0,0 +1,14 @@ +--- +title: "ably spaces members" +meta_description: "Manage members in Ably Spaces using the CLI - enter spaces and subscribe to member events." +meta_keywords: "ably cli, cli, spaces, members, ably spaces, presence, member management, collaborative experiences" +--- + +Use the `ably spaces members` command group to manage the [member presence set](/docs/products/spaces/features/member-location) of a space. + +## Subcommands + +| Command | Description | +| ------- | ----------- | +| [`ably spaces members enter`](/docs/cli/spaces/members/enter) | Enter a space and remain present until terminated. | +| [`ably spaces members subscribe`](/docs/cli/spaces/members/subscribe) | Subscribe to member presence events in a space. | \ No newline at end of file diff --git a/src/pages/docs/cli/spaces/members/subscribe.mdx b/src/pages/docs/cli/spaces/members/subscribe.mdx new file mode 100644 index 0000000000..5300a8d58b --- /dev/null +++ b/src/pages/docs/cli/spaces/members/subscribe.mdx @@ -0,0 +1,112 @@ +--- +title: "ably spaces members subscribe" +meta_description: "Subscribe to member presence events in an Ably Space using the CLI." +meta_keywords: "ably cli, cli, command, spaces, members, member subscribe, presence, ably spaces" +--- + + +```shell +ably spaces members subscribe [flags] +``` + + +Use the `ably spaces members subscribe` command to subscribe to member presence events in a space. + +Use another terminal instance and the [`ably spaces members enter`](/docs/cli/spaces/members/enter) command to generate member events that will be received by this subscription. + +## Arguments + +### `` + +The space name to subscribe to members for, for example: `example-space`. + +## Flags + +You can optionally pass the following flags to the `ably spaces members subscribe` command: + +### `--duration | -D` + +Automatically exit after the given number of seconds. Use `0` to run indefinitely (default behavior). + +## Global flags + +The following global flags are supported using the `ably spaces members subscribe` command: + +* [`--token`](/docs/cli#token) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--endpoint`](/docs/cli#endpoint) +* [`--verbose`](/docs/cli#verbose) + +## Output + +When subscribing to member events, you will see the current members list and any subsequent member presence events as they occur. + +| Property | Description | +| -------- | ----------- | +| clientId | The client ID of the member | +| connectionId | The connection ID of the member | +| isConnected | Whether the member is currently connected | +| profileData | Any profile data associated with the member | + +## Examples + +### Subscribe to member events + +Subscribe to member presence events in a space: + + +```shell +ably spaces members subscribe example-space +``` + + +### Subscribe with JSON output + +Subscribe to member events with structured JSON output: + + +```shell +ably spaces members subscribe example-space --json +``` + + +**Output:** + +```json +{ + "members": [ + { + "clientId": "ably-cli-03c3c24b", + "connectionId": "z3husHyGx6", + "isConnected": true, + "profileData": null + }, + { + "clientId": "ably-cli-b1525ee7", + "connectionId": "Z4GF9Wsyu5", + "isConnected": true, + "profileData": null + } + ], + "space": "example-space", + "status": "connected", + "success": true +} +``` + + +### Subscribe for a limited time + +Subscribe to member events for 30 seconds then exit: + + +```shell +ably spaces members subscribe example-space --duration 30 +``` + diff --git a/src/pages/docs/cli/status.mdx b/src/pages/docs/cli/status.mdx new file mode 100644 index 0000000000..008d9f4a41 --- /dev/null +++ b/src/pages/docs/cli/status.mdx @@ -0,0 +1,53 @@ +--- +title: "ably status" +meta_description: "Check the operational status of Ably services." +meta_keywords: "ably cli, cli, status, service status, ably status" +--- + + +```shell +ably status +``` + + +Use the `ably status` command to check the current operational status of Ably services. This command queries the Ably status page to provide information about service availability and any ongoing incidents. + +## Global flags + +The following global flags are supported using the `ably status` command: + +* [`--access-token`](/docs/cli#access-token) +* [`--api-key`](/docs/cli#api-key) +* [`--client-id`](/docs/cli#client-id) +* [`--env`](/docs/cli#env) +* [`--endpoint`](/docs/cli#endpoint) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably status` command displays: + +| Property | Description | +| -------- | ----------- | +| **Service Status** | Overall operational status of Ably services | +| **Incidents** | Information about any current incidents | +| **Status URL** | Link to the detailed status page | + +## Examples + +Check the status of Ably services: + +```shell +ably status +``` + +``` +✓ Ably services are operational +No incidents currently reported + +For detailed status information, visit https://status.ably.com +``` diff --git a/src/pages/docs/cli/support/ask.mdx b/src/pages/docs/cli/support/ask.mdx new file mode 100644 index 0000000000..20eeaf9570 --- /dev/null +++ b/src/pages/docs/cli/support/ask.mdx @@ -0,0 +1,115 @@ +--- +title: "ably support ask" +meta_description: "Ask a question to the Ably AI agent for help using the CLI." +meta_keywords: "ably cli, cli, support, ai agent, ask question, ably support ask" +--- + + +```shell +ably support ask [flags] +``` + + +Use the `ably support ask` command to get help from the Ably AI agent. The AI agent can answer questions about Ably features, provide code examples, and guide you through implementation details. + +## Arguments + +Pass the following arguments to the `ably support ask` command: + +### `` + +The question to ask the Ably AI agent, for example: `"How do I publish to a channel?"`. + +## Flags + +You can optionally pass the following flags to the `ably support ask` command: + +### `--continue` + +Continue the previous conversation with the Ably AI agent. This maintains context from your previous questions and allows for follow-up queries. + +### `--help | -h` + +Show CLI help for this command. + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably support ask` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably support ask` command displays: + +| Property | Description | +| -------- | ----------- | +| **AI Response** | Detailed answer from the Ably AI agent | +| **Code Examples** | Relevant code snippets when applicable | +| **Helpful Links** | Related documentation and resources | +| **Follow-up Instructions** | How to continue the conversation | + +## Examples + +Ask a basic question: + + +```shell +ably support ask "How do I get started with Ably?" +``` + + +Ask about specific features: + + +```shell +ably support ask "What are the available capabilities for tokens?" +``` + + +Ask a technical question: + + +```shell +ably support ask "How do I publish to a channel?" +``` + + +**Output:** + +```text +To publish to a channel in Ably, first create a channel instance and then use the publish method. Here's how to do it: + + const realtime = new Ably.Realtime('xVLyHw.DovQSg:*'); + const channel = realtime.channels.get('cod-paw-mic'); + await channel.publish('example', 'message data'); + +You can publish a single message or multiple messages at once. When publishing multiple messages, they are published atomically, meaning either all messages will be published successfully or none of them will be. + +Helpful Links: +1. Ably Pub/Sub | Basic pub-sub - https://ably.com/docs/pub-sub +2. API References | Channels - https://ably.com/docs/api/rest-sdk/channels +``` + + +Continue a previous conversation: + + +```shell +ably support ask --continue "Can you explain more about token capabilities?" +``` + + diff --git a/src/pages/docs/cli/support/contact.mdx b/src/pages/docs/cli/support/contact.mdx new file mode 100644 index 0000000000..1e83693b2c --- /dev/null +++ b/src/pages/docs/cli/support/contact.mdx @@ -0,0 +1,47 @@ +--- +title: "ably support contact" +meta_description: "Contact Ably for assistance using the CLI." +meta_keywords: "ably cli, cli, support, contact, assistance, ably support contact" +--- + + +```shell +ably support contact [flags] +``` + + +Use the `ably support contact` command to access Ably's contact information and support channels. This command opens your default web browser to the Ably contact page where you can find various ways to get in touch with the Ably support team. + +## Flags + +You can optionally pass the following flags to the `ably support contact` command: + +### `--help | -h` + +Show CLI help for this command. + +## Output + +The `ably support contact` command: + +| Action | Description | +| ------ | ----------- | +| **Browser Opening** | Opens the Ably contact page in your default browser | +| **Contact Information** | Provides access to multiple support channels | + +## Examples + +Open the Ably contact page: + + +```shell +ably support contact +``` + + +**Output:** + +```text +Opening https://ably.com/contact in your browser... +``` + diff --git a/src/pages/docs/cli/support/index.mdx b/src/pages/docs/cli/support/index.mdx new file mode 100644 index 0000000000..05a52a5e6b --- /dev/null +++ b/src/pages/docs/cli/support/index.mdx @@ -0,0 +1,17 @@ +--- +title: "ably support" +meta_description: "Get support and help from Ably using the CLI." +meta_keywords: "ably cli, cli, support, help, assistance, ably support" +--- + +Use the `ably support` command group to get support and help from Ably. These commands provide access to AI assistance, contact information, and support resources. + +## Subcommands + +The following commands are available for support: + +| Command | Description | +| ------- | ----------- | +| [`ably support ask`](/docs/cli/support/ask) | Ask a question to the Ably AI agent for help. | +| [`ably support contact`](/docs/cli/support/contact) | Contact Ably for assistance. | +| [`ably support info`](/docs/cli/support/info) | General support resources and documentation links. | \ No newline at end of file diff --git a/src/pages/docs/cli/version.mdx b/src/pages/docs/cli/version.mdx new file mode 100644 index 0000000000..a941f7703d --- /dev/null +++ b/src/pages/docs/cli/version.mdx @@ -0,0 +1,63 @@ +--- +title: "ably version" +meta_description: "Display the version of the Ably CLI." +meta_keywords: "ably cli, cli, version, ably version" +--- + + +```shell +ably version +``` + + +Use the `ably version` command to display the version information of the Ably CLI, including the CLI version, platform architecture, and Node.js version. + +## Flags + +You can optionally pass the following flags to the `ably version` command: + +### `--help | -h` + +Show CLI help for this command. + +## Global flags + +The following global flags are supported using the `ably version` command: + +* [`--api-key`](/docs/cli#api-key) +* [`--access-token`](/docs/cli#access-token) +* [`--client-id`](/docs/cli#client-id) +* [`--endpoint`](/docs/cli#endpoint) +* [`--env`](/docs/cli#env) +* [`--host`](/docs/cli#host) +* [`--json`](/docs/cli#json) +* [`--pretty-json`](/docs/cli#pretty-json) +* [`--token`](/docs/cli#token) +* [`--verbose`](/docs/cli#verbose) + +## Output + +The `ably version` command displays: + +| Property | Description | +| -------- | ----------- | +| **CLI Version** | The version of the Ably CLI package | +| **Platform** | The operating system and architecture | +| **Node Version** | The Node.js version being used | + +## Examples + +Display the CLI version information: + + +```shell +ably version +``` + + +**Output:** + +```text +@ably/cli/0.12.0 darwin-arm64 v22.14.0 +``` +