Workspaces

Workspace-level commands. A workspace is an independent layout of panes; switch between them with ⌘1…9 or these commands.

list-workspaces

ht list-workspaces
# ws:0  build       (current)
# ws:1  docs
# ws:2  scratch

Lists workspaces with their id, label, and a (current) marker on the focused one. --json returns the structured form.

current-workspace

ht current-workspace
# ws:0

new-workspace

ht new-workspace --name proj --cwd ~/code

Creates a new workspace. Both flags are optional — without --name the workspace gets an autogenerated label; without --cwd it inherits the user’s home directory.

select-workspace

ht select-workspace --workspace ws:2

close-workspace

ht close-workspace --workspace ws:2

Closes the workspace and all its surfaces. Shells receive SIGHUP; the metadata poller drains them on the next tick.

rename-workspace

ht rename-workspace "my new name"
ht rename-workspace --workspace ws:2 "build"

Without --workspace, renames the current one.

next-workspace / previous-workspace

ht next-workspace
ht previous-workspace

Equivalent to ⌃⌘] / ⌃⌘[.