workspaces, ws
Usage
Subcommands
There is no
create or start subcommand. Workspaces are created automatically at the size selected for a task, and connect starts or resumes a stopped workspace.<id> arguments accept the first 8 characters of the workspace UUID instead of the full ID. An ambiguous prefix fails loudly and asks for a longer one.
Display States
The CLI shows a workspace’s current display state in theSTATUS column and in get.
aether workspace list
List one page of your workspaces, most recently updated first. With a default project selected, only that project’s workspaces are listed; otherwise the workspaces of the organization the command acts in (see--org) are listed and a PROJECT column is added. When more workspaces follow, the output ends with a Next cursor: line; pass it to --cursor to read the next page.
ID, STATUS, PROJECT, HARDWARE, UPDATED. With --json, the output is the page itself: {"items": [...], "next_cursor": "..."}, where next_cursor is null on the last page.
aether workspace get
Show details for one workspace.error, the error message is shown.
aether workspace connect
Start or resume a workspace and wait until it is running. This is how you start a stopped (idle, stopped, or suspended) workspace. While the workspace starts, each step it waits on is printed to stderr.
--json to return the workspace’s ID, its task’s ID, the live protocol, and the preview URL template.
aether workspace update
Update a workspace’s VM size or keep-active setting. Only the flags you pass are changed; at least one is required.aether workspace stop
Stop a running workspace. The workspace keeps its persistent storage and can be resumed withconnect. By default the command waits until the workspace reaches a stopped state.
aether workspace delete
Delete a workspace and its persistent storage.aether workspace ssh
Open an interactive raw-mode terminal session in a workspace over the WebSocket connection. Requires an interactive terminal (TTY) and handles window resizing. If no workspace is given, the command uses the project’s single running workspace.exit or press Ctrl+D to disconnect. The command also exits zero when the server closes the connection normally (close code 1000). Any other close ends it non-zero with the close’s name (for example going_away); it does not reconnect, since a new connection would open a fresh shell.
aether workspace ports
List the active preview ports for a workspace. The command connects to the workspace, waits for a port snapshot, and prints a preview URL for each port when the workspace’s ports can be reached.aether workspace port kill
Kill an active preview port (1–65535).aether workspace preview-url
Print the preview URL for a workspace port.--authed to run the repository’s preview auth hook. A URL result is
printed directly. A local_storage result prints an explanation to stderr and
the complete JSON result to stdout so a script can apply it client-side.
aether config set preview_domain <domain> or the AETHER_PREVIEW_DOMAIN environment variable), over https, or http when that domain is localhost. When the workspace’s ports cannot be reached, ports prints only port numbers and preview-url fails.