Skip to content

[DX-964] Add new spaces commands #177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
umair-ably merged 3 commits into from
Mar 20, 2026
Merged

[DX-964] Add new spaces commands #177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0d4446d
[DX-964] Added missing spaces create, get and subscribe
sacOO7 Mar 19, 2026
09f0316
Addressed review comments on the PR
sacOO7 Mar 20, 2026
dfd9360
Fix spaces get numeric action codes, subscribe timestamp placement, a…
umair-ably Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 136 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,10 +201,12 @@ $ ably-interactive
* [`ably rooms typing keystroke ROOM`](#ably-rooms-typing-keystroke-room)
* [`ably rooms typing subscribe ROOM`](#ably-rooms-typing-subscribe-room)
* [`ably spaces`](#ably-spaces)
* [`ably spaces create SPACE_NAME`](#ably-spaces-create-space_name)
* [`ably spaces cursors`](#ably-spaces-cursors)
* [`ably spaces cursors get-all SPACE_NAME`](#ably-spaces-cursors-get-all-space_name)
* [`ably spaces cursors set SPACE_NAME`](#ably-spaces-cursors-set-space_name)
* [`ably spaces cursors subscribe SPACE_NAME`](#ably-spaces-cursors-subscribe-space_name)
* [`ably spaces get SPACE_NAME`](#ably-spaces-get-space_name)
* [`ably spaces list`](#ably-spaces-list)
* [`ably spaces locations`](#ably-spaces-locations)
* [`ably spaces locations get-all SPACE_NAME`](#ably-spaces-locations-get-all-space_name)
Expand All @@ -217,10 +219,12 @@ $ ably-interactive
* [`ably spaces locks subscribe SPACE_NAME`](#ably-spaces-locks-subscribe-space_name)
* [`ably spaces members`](#ably-spaces-members)
* [`ably spaces members enter SPACE_NAME`](#ably-spaces-members-enter-space_name)
* [`ably spaces members get-all SPACE_NAME`](#ably-spaces-members-get-all-space_name)
* [`ably spaces members subscribe SPACE_NAME`](#ably-spaces-members-subscribe-space_name)
* [`ably spaces occupancy`](#ably-spaces-occupancy)
* [`ably spaces occupancy get SPACE_NAME`](#ably-spaces-occupancy-get-space_name)
* [`ably spaces occupancy subscribe SPACE_NAME`](#ably-spaces-occupancy-subscribe-space_name)
* [`ably spaces subscribe SPACE_NAME`](#ably-spaces-subscribe-space_name)
* [`ably stats`](#ably-stats)
* [`ably stats account`](#ably-stats-account)
* [`ably stats app [ID]`](#ably-stats-app-id)
Expand Down Expand Up @@ -4463,21 +4467,61 @@ DESCRIPTION
EXAMPLES
$ ably spaces list

$ ably spaces get my-space

$ ably spaces create my-space

$ ably spaces subscribe my-space

$ ably spaces members enter my-space

$ ably spaces locations set my-space

COMMANDS
ably spaces create Initialize a space without entering it
ably spaces cursors Commands for interacting with Cursors in Ably Spaces
ably spaces get Get the current state of a space
ably spaces list List active spaces
ably spaces locations Commands for location management in Ably Spaces
ably spaces locks Commands for component locking in Ably Spaces
ably spaces members Commands for managing members in Ably Spaces
ably spaces occupancy Commands for working with occupancy in Ably Spaces
ably spaces subscribe Subscribe to both spaces members and location update events
```

_See code: [src/commands/spaces/index.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/index.ts)_

## `ably spaces create SPACE_NAME`

Initialize a space without entering it

```
USAGE
$ ably spaces create SPACE_NAME [-v] [--json | --pretty-json] [--client-id <value>]

ARGUMENTS
SPACE_NAME Name of the space to initialize

FLAGS
-v, --verbose Output verbose logs
--client-id=<value> Overrides any default client ID when using API authentication. Use "none" to explicitly set
no client ID. Not applicable when using token authentication.
--json Output in JSON format
--pretty-json Output in colorized JSON format

DESCRIPTION
Initialize a space without entering it

EXAMPLES
$ ably spaces create my-space

$ ably spaces create my-space --json

$ ably spaces create my-space --client-id my-client
```

_See code: [src/commands/spaces/create.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/create.ts)_

## `ably spaces cursors`

Commands for interacting with Cursors in Ably Spaces
Expand Down Expand Up @@ -4613,6 +4657,35 @@ EXAMPLES

_See code: [src/commands/spaces/cursors/subscribe.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/cursors/subscribe.ts)_

## `ably spaces get SPACE_NAME`

Get the current state of a space

```
USAGE
$ ably spaces get SPACE_NAME [-v] [--json | --pretty-json]

ARGUMENTS
SPACE_NAME Name of the space to get

FLAGS
-v, --verbose Output verbose logs
--json Output in JSON format
--pretty-json Output in colorized JSON format

DESCRIPTION
Get the current state of a space

EXAMPLES
$ ably spaces get my-space

$ ably spaces get my-space --json

$ ably spaces get my-space --pretty-json
```

_See code: [src/commands/spaces/get.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/get.ts)_

## `ably spaces list`

List active spaces
Expand Down Expand Up @@ -4977,6 +5050,35 @@ EXAMPLES

_See code: [src/commands/spaces/members/enter.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/members/enter.ts)_

## `ably spaces members get-all SPACE_NAME`

Get all members in a space

```
USAGE
$ ably spaces members get-all SPACE_NAME [-v] [--json | --pretty-json]

ARGUMENTS
SPACE_NAME Name of the space to get members from

FLAGS
-v, --verbose Output verbose logs
--json Output in JSON format
--pretty-json Output in colorized JSON format

DESCRIPTION
Get all members in a space

EXAMPLES
$ ably spaces members get-all my-space

$ ably spaces members get-all my-space --json

$ ably spaces members get-all my-space --pretty-json
```

_See code: [src/commands/spaces/members/get-all.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/members/get-all.ts)_

## `ably spaces members subscribe SPACE_NAME`

Subscribe to member presence events in a space
Expand Down Expand Up @@ -5091,6 +5193,40 @@ EXAMPLES

_See code: [src/commands/spaces/occupancy/subscribe.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/occupancy/subscribe.ts)_

## `ably spaces subscribe SPACE_NAME`

Subscribe to both spaces members and location update events

```
USAGE
$ ably spaces subscribe SPACE_NAME [-v] [--json | --pretty-json] [--client-id <value>] [-D <value>]

ARGUMENTS
SPACE_NAME Name of the space to subscribe to

FLAGS
-D, --duration=<value> Automatically exit after N seconds
-v, --verbose Output verbose logs
--client-id=<value> Overrides any default client ID when using API authentication. Use "none" to explicitly set
no client ID. Not applicable when using token authentication.
--json Output in JSON format
--pretty-json Output in colorized JSON format

DESCRIPTION
Subscribe to both spaces members and location update events

EXAMPLES
$ ably spaces subscribe my-space

$ ably spaces subscribe my-space --json

$ ably spaces subscribe my-space --pretty-json

$ ably spaces subscribe my-space --duration 30
```

_See code: [src/commands/spaces/subscribe.ts](https://github.com/ably/ably-cli/blob/v0.17.0/src/commands/spaces/subscribe.ts)_

## `ably stats`

View statistics for your Ably account or apps
Expand Down
61 changes: 61 additions & 0 deletions src/commands/spaces/create.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
import { Args } from "@oclif/core";
Copy link
Contributor

@AndyTWF AndyTWF Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this command add any value? Is it misleading?

It essentially just calls spaces.get('foo') which under the hood implicitly attaches the channel. So the channel exists for a very brief period and disappears. Other commands like get will fail because there are no members.

This could be misleading as a create command usually has an air of persistence about it. So I think its better we don't have it.

Copy link
Contributor Author

@sacOO7 sacOO7 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That’s true, but earlier when you looked at spaces, there wasn’t any way to tell how they were created. It also felt quite odd that a space only becomes visible when a member joins it using spaces members enter. At the moment, the spaces create command simply creates an ephemeral space. I had added an explicit description to clarify this, but it was overridden by Umair’s commit (dfd9360).

Now, when you look at the commands, it’s straightforward to create a space using spaces create, and you can also see it listed in spaces list in another terminal

Copy link
Contributor

@AndyTWF AndyTWF Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, you can see it via list - but that's misleading no? If I go and make a cup of tea between running the two commands, then suddenly the space I thought I created is no longer there.

Copy link
Contributor Author

@sacOO7 sacOO7 Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's why we had explicit description on spaces create, I feel we should revert it there or there should be clear way to communicate how spaces are initialised. From my perspective, initialising spaces using spaces members enter feels super odd.
Other way is spaces create should print warning message that, space created is ephemeral and will cease to exist if no member is entered

Copy link
Contributor Author

@sacOO7 sacOO7 Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will be logging as a warning -> #185


import { productApiFlags, clientIdFlag } from "../../flags.js";
import { SpacesBaseCommand } from "../../spaces-base-command.js";
import {
formatProgress,
formatResource,
formatSuccess,
} from "../../utils/output.js";

export default class SpacesCreate extends SpacesBaseCommand {
static override args = {
space_name: Args.string({
description: "Name of the space to initialize",
required: true,
}),
};

static override description = "Initialize a space without entering it";

static override examples = [
"$ ably spaces create my-space",
"$ ably spaces create my-space --json",
"$ ably spaces create my-space --client-id my-client",
];

static override flags = {
...productApiFlags,
...clientIdFlag,
};

async run(): Promise<void> {
const { args, flags } = await this.parse(SpacesCreate);
const spaceName = args.space_name;

try {
if (!this.shouldOutputJson(flags)) {
this.log(
formatProgress(`Initializing space ${formatResource(spaceName)}`),
);
}

await this.initializeSpace(flags, spaceName, {
enterSpace: false,
setupConnectionLogging: false,
});

if (this.shouldOutputJson(flags)) {
this.logJsonResult({ space: { name: spaceName } }, flags);
} else {
this.log(
formatSuccess(
`Space ${formatResource(spaceName)} initialized. Use "ably spaces members enter" to activate it.`,
),
);
}
} catch (error) {
this.fail(error, flags, "spaceCreate");
}
}
}
Loading
Loading