Using the CLI in your Shell

Practical recipes for the otty command. For the full reference of every subcommand and flag see Reference → CLI.

Otty CLI options

Install the CLI

The otty CLI ships inside the app. To put it on your PATH, open Settings → Shell → Install CLI. One click:

• symlinks otty into /usr/local/bin (asks for admin if needed),
• installs shell completions for bash, zsh, and fish,
• installs config-file syntax highlighting for Vim/Neovim and bat (only for the editors you already use).

Verify:

otty --version
otty <TAB>          # completions

Basic Usage

otty open — pop a new window

otty open                              # new window in the current directory
otty open ~/projects/api               # new window rooted at a folder
otty open . --command "npm run dev"    # run something on launch
otty open . --title "API"              # name the window

Starts the app if it isn't already running. The path defaults to your current directory; relative paths resolve against it.

otty view / otty edit — open a file or link in a pane

Needs a running Otty window. otty view opens read-only, otty edit opens the same target editable — otherwise identical.

otty view ./README.md            # read-only preview, in a new tab
otty edit src/lib.rs             # editable
otty view https://doc.otty.sh    # http(s) links open as a web pane
otty view user@host:/etc/hosts   # remote paths, over your ssh session

Pick a placement (the default is a new tab):

otty view log.txt --new-window
otty edit notes.md --right       # split the current pane: --left / --right / --top / --bottom

Flip the mode for a single call with --mode view|edit (e.g. edit something even when you typed view). Relative paths resolve against your shell's cwd. See Files and Links.

otty watch — run a command with a progress badge

Wraps any command so the tab shows a spinning badge while it runs, then a ✓ / ✗ badge when it finishes — glance at a long build from another tab without switching to it.

otty watch cargo build --release
otty watch -- make test          # use `--` before commands that take their own flags
otty watch -q ./deploy.sh        # -q: no system notification on finish

The command's exit code passes straight through. Cancelling with Ctrl-C just clears the badge — a deliberate stop isn't flagged as an error.

Waiting on a coding agent

otty watch:claude <session-id> (also watch:codex, watch:opencode) blocks until that agent session goes idle, so you can chain work after it finishes. The session ID is the one from Agent History.

You could create a Skill in code agent to tell them do something after another code agent ended.

otty jump — frecency directory jump

Jumps the focused pane to the highest-ranked directory matching your query (cd-style). Ranking is by frecency — frequency + recency. Needs a running window.

otty jump api    # jump to the best match for "api"
otty jump        # no query → toggle between $HOME and your last jump

Repeat the same query to cycle past your current directory to the next match (jump typora → jump typora lands you in a different Typora dir). It's most useful as a bare jump — see below. For the full picture — how folders get recorded and ranked — see Frequent Folders.

otty learn — teach Otty a folder or command

otty learn feeds a different database depending on what you point it at:

1. A folder → the frecency database behind otty jump and Open Quickly's Folders tab.

otty learn                 # record the current directory
otty learn ~/projects/api  # …or a specific folder

2. A command on your $PATH → Otty probes its --help and learns its flags and subcommands, adding them to autocomplete. For a bare $PATH name it confirms first; pass -y to skip.

otty learn rg                        # a tool on $PATH
otty learn ./target/release/mytool   # …or an executable given by path

3. A script or command string → recorded as a suggestion scoped to the current folder, so it only surfaces in autocomplete where you actually run it.

otty learn ./scripts/deploy.sh   # a project script
otty learn "make test-e2e"       # …or a quoted command string

otty ignore — undo otty learn

otty ignore is the mirror of otty learn — point it at the same thing to take it back:

otty ignore ~/tmp/scratch    # a folder → drop it from jump results
otty ignore "make test-e2e"  # a command/script → forget it for this folder

• A folder (use 1) leaves the frecency rankings and won't come back when you cd into it; if zoxide is installed it also runs zoxide remove.
• A command or script (use 3) is forgotten from the current folder's autocomplete — run otty ignore from the same directory you learned it in, with the same text. This half is purely local; no running app needed.

The one thing it can't drop per-command is a tool's completions learned from --help (use 2) — clear those in Settings → Controls → Clear my data.

Already on zoxide? otty import zoxide pulls your existing history in — see Frequent Folders.

Omit the otty prefix and set aliases

Typing otty before every command gets old. Turn on Settings → Shell → Omit otty prefix and the integration installs shell functions for edit, view, watch, jump, and learn, so you can just type:

jump api
edit src/lib.rs
watch cargo test

The toggle is live — it takes effect at the next prompt in every integrated shell, no restart. By default these wrappers won't clobber a name you've already defined (e.g. Linux's system watch); turn on Allow overwrite to let them win. The jump wrapper additionally cds your shell locally instead of echoing cd '<path>' into the pane, so your history and transcript stay clean.

Custom aliases

Map a short name to any otty subcommand under Settings → Shell → CLI aliases, or in ~/.config/otty/config.toml:

cli-alias = j=jump
cli-alias = v=view
cli-alias = e=edit

Now j api runs otty jump api. An alias that points at a wrapped command (jump / edit / view / watch / learn) goes through that wrapper, so j keeps the clean local-cd behaviour. Custom aliases apply at shell init — open a new shell after changing them.

Run a recipe

otty open ~/work/team.ottyrecipe

Pop the whole workspace. See Recipes.

See also

• CLI Reference — every subcommand and flag.
• Configuration Reference — default-shell, working-directory, etc.