Komla CLI

Let your agent launch other agents, open browser previews, report its progress, and manage workspaces through the terminal.

komla is already available in Komla-managed terminals, including local and SSH sessions. Keep Komla running and run these commands from a terminal inside your workspace. No separate CLI installation or MCP setup is needed.

Start with a prompt

Ask your agent: “Use the Komla CLI to open a new workspace and investigate the failing build.” It can discover the available commands with komla --help.

Launch an agent

Start a separate task in a new workspace:

komla launch "Investigate the failing build"

Git projects get a separate worktree and branch. Directory-backed projects share their directory.

To open another agent tab in the current workspace, add --here:

komla launch "Review these changes" --here

The new tab uses the same working directory, so both agents see the same files. Launches use the default agent from Komla CLI launch defaults in Settings. To choose another, list your configured agents with komla agent presets --json and pass one with --preset, adding --mode for one of its launch modes.

By default agents can start modes that still ask before acting anywhere, and modes that skip permission prompts, such as --yolo, only on an SSH host you marked Treat as isolated. The robot button on each mode in Settings → Agents changes where agents may start it: anywhere, only on an isolated SSH host, or never. Agents may always start the launch mode you pin in the launch defaults.

New workspaces branch from the project's base branch. Add --from-current-branch to branch from the current workspace instead, or --branch to name the branch. --name and --description set the new workspace's sidebar title, and --project starts it in another project. For a long prompt, pass --prompt-file with a path, or - to read it from standard input.

To let the user check the task first, add --draft. It starts nothing: it opens New Workspace with the prompt, project, agent and mode filled in, for the user to change and start.

komla launch --draft "Investigate the failing build"

Work with the agents you started

An agent that opened another with komla launch --here can steer it and collect its result without sleeping and polling. These commands act on the current workspace's terminals, named by id or by a tab name only one terminal has:

komla terminals
komla wait review
komla read review --lines 100
komla send --wait review "Recheck the error path"

komla terminals lists them with what each agent is doing: working, blocked (waiting for you), done, error, idle or exited. komla wait returns when the agent's turn ends, it needs you, or it exits; it checks in after 180 seconds (--timeout, up to 3600) and the agent goes on. With --output "ready in" it waits for a dev server's line instead. komla read prints the terminal's screen as text, with up to --lines of history above it. komla send types a message and presses Enter, and --wait then waits for the turn it starts.

An agent can't send to its own terminal, and send refuses an agent that waits for you, such as on a permission prompt, so it asks you instead of answering for you. You can turn these commands off in Settings → Integrations & MCP.

Open a browser preview

Start your development server first, then open its actual URL in Komla:

komla preview http://localhost:3000

Replace port 3000 with the port your server uses. This opens a preview; it does not start a server.

Open a folder

komla open ~/notes

Opens a folder on this computer in Komla, as Open Folder does: in a workspace of its own, or the one already open there. Without a path it opens the current folder. No agent starts. It works in local terminals only; folders on an SSH host open with New Workspace.

Update a workspace title

komla title "Build investigation" --description "Trace the failing build"

Use a title that describes the overall task so the workspace is easy to find in the sidebar.

Snooze a workspace

Move the current workspace to the sidebar's Snoozed shelf until later, such as while it waits on a slow job:

komla snooze 2h

Pass a duration (30m, 2h, 1d), a time (17:30, tomorrow if it has passed today), or a date and time ("2026-11-02 09:00"). Times are in the time zone of the computer running Komla, even in an SSH terminal. The workspace comes back marked Woke, or sooner if an agent in it needs input or fails. While an agent there already needs input or has failed, the workspace can't be snoozed. komla wake ends the snooze now, such as when the job finishes.

To snooze until something happens, add --until-notified: the workspace also wakes at its next notification, such as an agent's turn ending there, komla notify, or a background Quick Command. With it, the time is optional:

komla snooze --until-notified

Tag a workspace

Say on the workspace's sidebar card what it waits on, such as a review after opening a pull request:

komla tag "Waiting for review"

The tag shows while no agent is busy there, until it's taken off or replaced; a workspace has one tag. komla tags lists the tags you already have, so agents can reuse one before making another. A new tag joins your tag list, which holds up to 50, with --tone (neutral, info, attention, success, warning or error), and --icon in place of the tag glyph; a tag you have keeps the look you gave it in Settings. --tooltip adds hover text.

--if changes only a workspace that has that tag, and untag with a tag takes off only that one, so a script that finishes late leaves alone a tag put on since. You can remove any tag from the card's Tag menu.

Show progress and markers

A script can show work under way, such as CI, with a spinner on the workspace's card, and anything else it wants beside the tag, such as a pull request's number:

komla progress "CI running" --tone info --tooltip "build 7 of 9"
komla mark pr "PR #12" --tone info --tooltip "Fix the login redirect"
komla progress --clear "CI running"
komla tag "CI failed" --tone error --if "CI running"
komla unmark pr

The card shows progress first, then a marker, in the tag's place while no agent is busy there, and the workspace keeps its tag. Neither joins your tag list. A marker has a key of the script's own, such as pr or deploy, so scripts using different keys never replace each other's, and a workspace holds up to 5 besides its progress. progress --clear with a label, and --if <label> on mark and unmark, change only what still shows that label, so a script that finishes late leaves alone what another run put on since. komla unmark --all takes every marker off and leaves the tag be. Progress ends when Komla quits. You can remove any of them from the card's menu.

Trash a workspace when done

komla trash

Moves the current workspace to the Trash once the agent's turn finishes, stopping its terminals. You can restore it for 7 days. It stays when the turn is interrupted, fails, ends with a question for you, or runs longer than 30 minutes, or when an agent in another tab is working, waiting for input, or failed. Agents run it as their last step.

Work across workspaces

For a task that spans repositories, such as an app and its API, link the workspaces:

komla workspace link <id>

Each workspace gets a symlink to the other in its linked-workspaces/ folder, which Git ignores, so an agent in either can read and edit both. komla workspace list shows the ids. Local workspaces link to local ones, and SSH workspaces to others on the same host. komla workspace unlink <id> removes the link, as does the workspace card's menu.

Show a status in the status bar

Put a short status, such as test results or a pull request, in Komla's status bar while the workspace is open:

komla status set tests "42 passed" --tone success
komla status set pr "PR #128" --link https://github.com/acme/app/pull/128

Setting the same id again replaces the item. Items can also carry a color (--color), an image icon (--icon, an SVG, PNG, WebP, GIF or JPEG up to 32 KB), a tooltip, or a popover that opens on a click. A popover is an HTML page (--popover or --popover-file), such as a checklist or a CI run's checks, shown in a sandbox where nothing loads from the web and Komla's theme colors are CSS variables, or Markdown (--popover-markdown or --popover-markdown-file); komla skill integrations shows how to make one. The text can include Nerd Font icons and terminal colors. To put icons and colors anywhere in it, pass --segments in place of the text, with a JSON array of parts. Remove one with komla status clear tests, or all of them with komla status clear.

Status bar items you configure with a command, through komla settings apply status-items, run their command on an interval while the workspace is open. komla status refresh <id> runs one of those commands now, such as from a hook when what it shows has changed; items set with komla status set have no command to run.

Get notified when a command finishes

Wrap a long-running command so its tab shows as working, and get a notification when it finishes or fails:

komla notify "Tests" -- npm test

To send a notification for the current workspace yourself, use komla notify "Deploy ready" --body "Staging is up". The title shows on the workspace's sidebar card; --badge shows shorter text there with the title on hover. --kind error marks a failure, --color takes a status color (success, warning, error, info, attention, muted) or any CSS color, and --icon replaces the badge's glyph with an image. --icon-color shows only the image's shape, in foreground, muted, a status color or a hex color:

komla notify "CI failed on main" --badge CI --kind error --icon ci.svg --icon-color foreground

Run a GUI app on an SSH host

On a Linux machine without a display, such as an SSH host, komla desktop run starts the app on a virtual desktop of its own and shows it on your computer:

komla desktop run -- firefox

Komla lists the desktop under the globe button at the top of the window, to open in your VNC app, such as Screen Sharing on macOS, or in a tab of Komla's browser preview. To open it right away, add --app for your VNC app or --browser for a tab, before the app: komla desktop run --browser -- firefox. It stops when the app exits. komla desktop start, status, and stop manage desktops for apps you start yourself.

Change Komla's settings

Agents can read and replace Quick Commands, Workspace Setup, automations, the theme, status bar items, sidebar panels, plugins, hooks, keyboard shortcuts, terminal settings, and agent presets' extra arguments and effort pickers:

komla settings get shortcuts
komla settings apply shortcuts --file shortcuts.json

apply takes JSON on standard input or from --file, and waits for you to confirm the change in Komla. Quick Commands also need --scope global or --scope current-project.

Script every workspace

A script outside any workspace, such as a hook that runs on a timer, can act on any of them by id:

komla workspace list
komla progress "CI running" --workspace <id>

komla workspace list lists the workspaces with their ids, names, branches and tags, and --json adds their paths, project, environment, attention, linked workspaces, markers and progress; --all adds those in the Trash. Run from an SSH host, it lists that host's workspaces only, and --workspace reaches only those. --workspace <id> makes any command that acts on a workspace, such as tag, mark, progress, title, snooze, status set or notify, act on that one instead of the current terminal's. trash and notify -- <command> don't take it.

Teach your agent the CLI

The Komla skill tells your agent what these commands do and how to use them. In Komla, open Settings → Integrations & MCP and turn on Komla skill on this computer, a Lima VM or an SSH host. Komla adds it to ~/.claude/skills and ~/.agents/skills, which Claude Code, Codex, OpenCode and other agents read, and to Antigravity CLI's skills, and keeps it up to date. For another agent, copy the install command under Komla CLI, run it in a terminal and choose your agent.

The skill loads Komla's other guides when a task needs them: komla skill customize for changing Komla itself, such as its theme, Quick Commands, shortcuts, status bar items, agents Komla starts on a schedule, and hooks that run on agent events or on a timer, and komla skill project-setup for recommending workspace setup steps and Quick Commands for a project. komla skill integrations, automations and appearance go deeper on status bar items, sidebar panels and plugins, scheduled agents, and themes. komla skill self-integration prints the guide for connecting an agent CLI that Komla doesn't support out of the box. For a guided tour, choose the Komla CLI demo from Komla's Tips menu.

CLI and MCP

The CLI is the main way agents control Komla: it needs no setup and covers everything on this page. Komla's new features go to the CLI and the Komla skill. Its MCP server stays for agents that only work through MCP tools; it can launch agents, open previews, set workspace titles and show status bar items. Turn it on per agent in Settings. For a client that needs an MCP server command, komla mcp serves Komla's MCP tools over stdio.

More help

Run komla --help or komla launch --help for command options. If the command is unavailable, check that you are in a Komla-managed terminal. Komla also provides its absolute path in the KOMLA_CLI environment variable.

Commands automatically use the current workspace. If you need Komla-specific project or workspace metadata, or want to investigate an unexpected target, use komla context --json.

If an operation is disabled, check Settings → Integrations & MCP → MCP and CLI access.