CLI

Skiff CLI

skiff is the command-line client for skiffd. It controls the same sessions and groups as the desktop app.

Install

skiff ships with the app and updates with it.

• The .deb and .rpm packages install it to /usr/bin.
• The AppImage copies it to ~/.local/bin when it starts.
• The macOS app links it into /usr/local/bin, or /opt/homebrew/bin when it can write there. Otherwise, run Help › Install skiff command… once.

To build it from a checkout, run cargo install --path crates/skiff-cli.

A release build uses the installed daemon. A debug build uses the development daemon.

Run skiff status first. If it reports that skiffd is not running, open Skiff or start the daemon.

Session names

Most session commands accept a full session ID, a unique ID prefix, or the name shown in the sidebar. Use a full ID in scripts. Names can change.

Inside a Skiff terminal, . means the current session. For commands that accept a group, . means the group that contains the current session.

skiffd sets two variables in every terminal it starts:

Variable	Value
SKIFF_SESSION	The terminal's session ID.
SKIFF_SOCKET	The socket of the daemon that started the terminal, so skiff reaches that daemon.

Terminal commands

Command	Description
skiff status	Show the daemon version, protocol, process ID, and socket path.
skiff ls [--json]	List sessions.
skiff new [--name NAME] [--cwd DIR]	Start a shell session.
skiff new -- CMD [ARGS...]	Start a program in a terminal.
skiff new --agent ID [--name NAME]	Start an installed agent. Use skiff agents to list IDs.
skiff send SESSION TEXT [--enter]	Type text into a terminal. --enter sends Enter after the text.
skiff send SESSION - --enter < FILE	Send standard input to a terminal.
skiff peek SESSION [-n LINES]	Print the terminal screen. -n includes recent history.
skiff attach SESSION	Connect this terminal to a session. Press Ctrl+\\ to detach.
skiff rename SESSION NAME	Set the session name. An empty name clears it.
skiff seen SESSION	Clear the session unread state.
skiff wait SESSION... --for STATE [--timeout SECONDS]	Wait for idle, waiting, done, or any-not-working.
skiff kill SESSION...	Stop sessions and remove them.

skiff wait exits with code 0 when every session reaches the selected state. It exits with code 1 on timeout, and 2 if a session ends or is removed first.

idle means the terminal has been quiet for a short time. Read the screen with skiff peek before you treat an agent as complete. A program started in a terminal returns to an interactive shell when it exits, so it normally becomes idle. A terminal becomes done only when its shell exits.

Group commands

A group is a named layout with up to four terminal panes. A terminal can belong to one group at a time.

Command	Description
skiff group ls [--json]	List groups and their terminal layouts. skiff g ls is an alias.
skiff group new [--name NAME] [SESSION...]	Create a group. Without --name, it takes its agents' names. An empty group needs --name, and starts its sessions in --cwd DIR or the current folder.
skiff group new SESSION... --dir row	Create a side-by-side group. Use --dir col for a vertical layout.
skiff group add GROUP SESSION [--split SIDE] [--of SESSION]	Move a terminal into a group. The default side is right.
skiff group rm GROUP SESSION	Remove a terminal from a group. The terminal keeps running.
skiff group rename GROUP NAME	Rename a group.
skiff group delete GROUP...	Delete groups. Their terminals keep running.

SIDE is left, right, up, or down. --of SESSION selects the pane to split. Adding a terminal to another group removes it from its previous group.

Configuration commands

Command	Description
skiff agents [--json]	List known agents and whether each is installed and enabled.
skiff projects [--json]	List projects from projects.toml. This command does not need a running daemon.

Theme commands

skiff theme ls [--json] lists available built-in and imported themes. Use the theme ID, such as builtin:ember, in the commands below.

Command	Description
skiff theme app set THEME	Set the app theme.
skiff theme app clear	Clear the app theme. The default applies.
skiff theme project set PROJECT THEME	Set a project's theme.
skiff theme project clear PROJECT	Clear a project's theme. The app theme applies.
skiff theme session set SESSION THEME	Set a terminal theme override. terminal is an alias for session.
skiff theme session clear SESSION	Clear a terminal theme override. The project or app theme applies.

A terminal theme overrides its project theme. A project theme overrides the app theme. Theme commands that change app or project settings write projects.toml. Terminal overrides are saved by skiffd. The app applies a new app or project theme when its window gets focus.

Socket selection

Use --socket PATH before any command to select a daemon socket. Without it, skiff uses SKIFF_SOCKET, then the normal skiffd socket path.

Examples

Start a Codex agent next to the current terminal:

skiff new --agent codex --group . --split right

Send a prompt and read the result:

skiff send SESSION "Review the current diff." --enter
skiff wait SESSION --for idle --timeout 1800
skiff peek SESSION -n 80

Agent skill

The skiff-cli skill teaches Claude Code and Codex to use the CLI. With it, you can ask an agent to "open a codex next to me" or "wait for the reviewer and summarize what it found".

The app does not install the skill. Copy the skiff-cli folder into ~/.claude/skills/ for Claude Code, or ~/.codex/skills/ for Codex.