CLI Reference

Complete reference for the otty command-line tool. For scenario-oriented examples see Using the CLI in your Shell.

otty <subcommand> [flags] [args]

Running otty with no subcommand (or starting with -e) launches the GUI, so otty and otty -e <cmd> behave like xterm / alacritty / ghostty. Many subcommands that inspect or drive the UI (window, tab, pane, view, edit, jump, …) require a running Otty app.

Global flags

Flag	Default	Meaning
--format <fmt>	text	Output format: text or json
--json	—	Shortcut for --format json
--no-headers	—	Drop table headers from text list output
-q, --quiet	—	Suppress non-essential success output
--socket <path>	auto	Override the runtime control socket path
--config-file <path>	auto	Override the config file path
--timeout <ms>	3000	IPC timeout when talking to the running app
-y, --yes	—	Skip destructive-action confirmation prompts
--version	—	Print version and exit
-h, --help	—	Help for the current command

Subcommands

otty open [path] — open a new window

otty open                      # new window
otty open ./projects           # new window in a directory
otty open --command "vim" --title "Editor"

Flag	Meaning
--command <cmd>	Run a command in the new window
--title <title>	Window title

otty view <target> / otty edit <target> — open a file or URL as a pane

otty view ./README.md          # read-only
otty edit src/lib.rs           # editable
otty view https://docs.otty.sh
otty view --right tail.log     # split to the right

view opens read-only; edit opens in edit mode. <target> is a file path or an http(s) URL. Both accept the same flags:

Flag	Meaning
--mode <view|edit>	Override read-only vs. edit
--new-tab	Open in a new tab (default placement)
--new-window	Open in a new window
--left, --right, --top, --bottom	Split the focused pane in that direction

otty config get/set/unset/edit/... — manage configuration

otty config get theme
otty config set theme dracula
otty config set theme dracula --reload   # also reload the running app
otty config set font-size 14 --transient # running app only, don't persist
otty config unset font-size
otty config edit                         # open in $EDITOR
otty config show                         # print normalized config
otty config path                         # print the config file path
otty config validate                     # check for errors
otty config reload                       # reload in the running app

See the Configuration Reference for every key.

otty font list / apply / import — manage fonts

otty font list --monospace
otty font apply "JetBrains Mono"         # writes font-family to config
otty font import ./MyFont.ttf --apply    # copy into ~/.config/otty/fonts/

Flag (on list)	Meaning
--family <name>	Filter by family (substring)
--monospace	Monospace families only
--system / --user	Only system-wide / only user-supplied fonts

otty theme list / import — manage color themes

otty theme list --color dark
otty theme import https://themes.otty.sh/nord.toml --activate

list filters with --color <dark|light|all> (default all). import takes a local path or URL — an Otty .toml, an iTerm2 .itermcolors, or a kitty / alacritty / ghostty color file — and accepts --activate (switch to it) and --overwrite (replace a same-named theme in place). To switch the active theme without importing, use otty config set theme <name>.

otty keybind list — list keybindings

otty keybind list
otty keybind list --action split        # filter by action name (substring)

See the Keybindings Reference for the defaults.

otty window / tab / pane — drive the running app

Inspect and manage windows, tabs, and panes in a running Otty (the plural forms otty windows / otty tabs / otty panes are shortcuts for … list).

otty panes --json
otty tab new --command "cargo watch" --title build
otty pane split --right --command "htop"
otty pane send-keys --pane 3 -- "echo hi" key:Enter
otty pane capture --pane 2 --lines 50
otty tab badge --kind running           # set a tab status badge

Common subcommands across the three: show, list, new, close, focus, rename (window/tab), move (tab). Panes additionally have split, zoom, resize, send-keys, and capture. Badge kinds are running, completed, finished, unread, error, awaiting-input.

otty watch <cmd> — run a command with a progress badge

otty watch make deploy
otty watch -q cargo test

Wraps cmd so the tab shows a spinner while it runs and a success / error badge when it exits (via OSC 9;4), then posts a Notify on Watch Finish notification. See Progress State.

Flag	Meaning
-q, --quiet	Suppress the system notification on finish

otty watch:<agent> <id> — block until an agent is idle

otty watch:claude 9f3c1a2b
otty watch:codex   <id> --timeout-secs 600
otty watch:opencode <id> --interval-ms 2000 -v

Blocks until the named code-agent session (claude / codex / opencode) reaches the idle state, then exits — for orchestrating one agent against another. Exit 0 on idle (or if the session has since closed), 4 if the session ID was never seen, 9 on timeout.

Flag	Default	Meaning
--interval-ms <n>	5000	Poll interval in milliseconds
--timeout-secs <n>	0	Overall timeout; 0 waits forever
-v, --verbose	—	Print state transitions to stderr

otty jump [query] — jump to a frecency-ranked directory

otty jump otty           # cd the focused pane to the best match
otty jump                # toggle between $HOME and the last jump source
otty jump otty --no-cd   # just print the resolved path

Sends cd <path> to the focused pane. --no-cd resolves only and prints the path, so a shell wrapper can cd locally. See Open Quickly & Jump.

otty learn [path] / otty ignore <path> — teach the frecency database

otty learn ./projects/otty    # record a directory visit
otty learn                    # record the focused pane's cwd
otty ignore ./old-project     # forget a directory or learned command

ignore is the undo of learn.

otty import <source> — import from other terminals

otty import zoxide                 # merge zoxide frecency
otty import ghostty                # ~/.config/ghostty/config
otty import kitty ./kitty.conf
otty import alacritty
otty import theme ./nord.toml --activate
otty import https://example.com/MyFont.ttf   # auto-detected → font import

Imports another terminal's config (ghostty / kitty / alacritty), zoxide frecency, or a theme. External-config imports accept --overwrite and --keep. A bare otty import <path-or-url> auto-detects: font files route to font import, theme files to theme import.

otty export <target> — export your config to another terminal

otty export ghostty                # to stdout
otty export kitty -o kitty.conf
otty export alacritty -o alacritty.toml

Flag	Meaning
-o, --output <path>	Write to a file instead of stdout

otty features [name] — try terminal feature samples

otty features list
otty features truecolor          # shorthand for `otty features try truecolor`

Renders demos for colors, emoji, OSC sequences, images, and more.

otty completions <shell>

Prints a shell completion script to stdout. Supported shells: bash, zsh, fish, elvish, powershell.

otty completions zsh  > "${fpath[1]}/_otty"
otty completions fish > ~/.config/fish/completions/otty.fish

Settings → Shell → Install CLI installs these for you. See CLI Usage → Install the CLI.

otty version

Prints version, build hash, and a brief feature/protocol summary.

Hooks & integrations

otty state:<agent> key=value … reports a code-agent's lifecycle state and otty ipc <command> sends a raw control message. These are invoked by Otty's bundled agent hooks and shell integration, not typically by hand. See Multi-agent integration.

See also

• Configuration Reference — every option you can set in config.
• Keybindings Reference — the default key map.
• CLI Usage — task-oriented examples.