Command line and links

Layout comes with a command, layoutctl, and answers getlayout:// links. Both reach the Layout that’s running, so a terminal, a script, a launcher or an agent can move you between workspaces.

Install layoutctl

Open Settings › Integrations and click Install…. Layout links layoutctl into /usr/local/bin; macOS asks for your password when that folder isn’t yours. If you installed Layout with Homebrew, layoutctl is already there.

The command lives inside the app, so updates keep it current. It talks to the Layout it came with, over a connection only your user account can open.

Commands

Command	What it does
layoutctl list	Every workspace, in the sidebar’s order. * marks the one you’re in.
layoutctl current	The name of the workspace you’re in.
layoutctl switch api	Switches to a workspace. - goes back to the previous one, General included.
layoutctl launch api	Launches a workspace: its apps, its layout, its terminal commands.
layoutctl stop api	Stops a workspace: its terminal commands end, its windows close, its apps quit.
layoutctl subscribe	Prints the workspace you’re in, then a line each time it changes, until you stop it.
layoutctl notify	Marks a workspace as waiting for you. See below.
layoutctl help	Lists the commands and their options.
layoutctl version	The version of Layout the command came with.

A workspace is named the way you’d type it: case and accents don’t matter, and the start of a name is enough when only one workspace begins that way. layoutctl switch sco goes to Scopebook. The id that list --json gives works too.

list and current take --json, for scripts: each workspace comes with its id, its section, its window count, its shortcut, its project folder, and whether an agent waits there.

stop doesn’t ask first, unlike Stop Workspace… in the menus. It returns once the commands ended and the windows closed, and exits with 1 when a window stayed open, for example to ask about unsaved work. See Stop a workspace.

switch returns once the workspace is in front. When Layout can’t switch, for example from a full-screen app or while it’s paused, it says why and exits with 1.

subscribe prints one JSON line per change: each switch, but also a pause, a resume, and a workspace marked or cleared.

layoutctl exits with 0 once done, 1 when Layout refused, 2 when the command or an option is wrong, and 3 when Layout isn’t running.

Mark a workspace

layoutctl notify marks the workspace that holds a folder as waiting for you, with a notification. The workspace is the one whose project, chats, editors or terminals open that folder, the deepest one winning, and a git worktree counts as its repository.

Option	What it does
--cwd <folder>	The folder to look for. The current one by default.
--kind <kind>	needs-input, the default, for an amber mark that waits for you, or done, for a green one.
--message <text>	What the notification says.
--agent <name>	claude, codex or cursor: reads what the agent’s hook passes, as Settings › Integrations sets it up.

notify always exits with 0, even when Layout isn’t running or an option is wrong, which it then reports on standard error: an agent’s hook must never fail because of Layout. See Agents waiting for you.

Ideas

• Raycast: a Script Command that runs layoutctl switch "$1" switches by name from Raycast’s search.
• A status bar: layoutctl subscribe prints one JSON line per change, which SketchyBar or any bar can read to show the workspace’s name.
• A key remapper: Karabiner’s shell_command can run layoutctl switch -.
• Your scripts: a script that opens a pull request can end with layoutctl launch review.

Links

A getlayout:// link switches workspace from anywhere that opens links: Raycast quicklinks, Alfred, a Stream Deck button, a note or a task.

getlayout://switch?workspace=Scopebook

The name works like layoutctl switch. Settings › Integrations shows the link to the workspace you’re in, ready to copy. While Layout is paused, links do nothing.

A link only switches. Launching a workspace runs its terminal commands, and a web page must never be able to do that, so launching stays with Layout’s own shortcuts, its menus and layoutctl.