dirijor CLI

dirijor is diri's command-line tool. It talks to the same background Engine as the app, so anything you script with it shows up in the window. Agents use it too: diri's hooks and MCP server run through it.

#Where it lives

The Engine also keeps a copy in ~/Library/Application Support/Dirijor/bin/dirijor on macOS. Agents that diri starts get its path in $DIRIJOR_CLI, along with $DIRIJOR_SESSION_ID for their own session.

To use it from your own terminal on macOS, link it onto your PATH:

mkdir -p ~/.local/bin
ln -sf /Applications/diri.app/Contents/Resources/bin/dirijor ~/.local/bin/dirijor

The CLI finds the Engine through its socket. Set DIRIJOR_SOCKET to point at a different one.

#Conventions

• Targets. Most commands take a target: a full session id, a unique id prefix, or a unique part of the session title (case-insensitive). Commands documented with ID need the id itself. Every terminal diri opens has its own id in $DIRIJOR_SESSION_ID.
• --json. Prints one line of JSON instead of a table.
• Arguments are literal. session run passes everything after -- as separate arguments. Nothing is run through a shell.

#Exit codes

run --wait is the exception: it exits with the command's own status (128 + N when signal N ended it), 124 when --timeout passes, and 125 when dirijor itself fails.

#Overview

dirijor hook, dirijor notify JSON and dirijor mcp-stdio are called by agents that diri launches. You do not need to run them.

#Cheat sheet

Every command people type, with its options. dirijor help COMMAND prints the same thing for one command.

<!-- generated by dirijor help --markdown: start -->

<!-- generated by dirijor help --markdown: end -->

#Scripting

Short verbs for shell scripts, modelled on tmux. They do the same things as the session commands below.

send key names (case-insensitive): Enter, Tab, Escape, BSpace, Space, Up, Down, Left, Right, Home, End, PageUp, PageDown, Insert, Delete, F1 to F12. Prefix C- for Control, M- for Alt and S- for Shift, for example C-c, M-b or S-Tab. Anything else is typed as text.

id=$(dirijor new --cwd ~/code/app)
dirijor send "$id" "npm run dev" Enter
dirijor capture "$id" --lines 5
dirijor send "$id" C-c
dirijor run --wait --rm -- cargo test --workspace && echo green

#Session verbs

These take a target like every other command. Where the table says so, a left-out target means your own session ($DIRIJOR_SESSION_ID), so dirijor split inside a diri terminal opens a shell beside you.

New panes and tabs from the CLI do not take focus unless you pass --focus, so scripts never pull the window away from you.

id=$(dirijor run -c ~/code/app --label tests --keep-open -- npm test)
dirijor wait "$id" --for 10m --json        # exitCode, or exit 2 if still running
logs=$(dirijor split --edge down --ratio 25 --label logs -- tail -f app.log)
dirijor send-key "$logs" ctrl+c
dirijor zoom "$id" --on
dirijor kill "$logs"

#Stopping sessions from an agent

kill, session close and session release follow the same rule as the MCP release_agent tool when an agent runs them: a root agent may stop sessions in its own project, a delegated agent only its direct children, and no agent its own session. A refusal exits 6 and names the rule. Nothing is gated when you run them yourself: from a terminal outside diri, or at a diri shell prompt with no agent in the foreground.

#Shell completion

dirijor completion SHELL prints a completion script generated from the same command list as --help. It completes commands, options, option values (--until, --edge, key names) and live session ids with their titles.

# fish
dirijor completion fish > ~/.config/fish/completions/dirijor.fish
# zsh (or: source <(dirijor completion zsh) in ~/.zshrc)
dirijor completion zsh > "${fpath[1]}/_dirijor"
# bash
dirijor completion bash > ~/.local/share/bash-completion/completions/dirijor

#Sessions

dirijor session with no action is the same as dirijor session list.

--name is accepted as an alias for --title. --host takes a host id from your remote hosts.

For spawn usage, all supported options, and a local example, run dirijor session spawn --help (or -h). --help anywhere in a spawn command prints help instead, so it never starts a session or creates a worktree, and works without a running Engine. Unknown options are rejected rather than ignored.

#Wait statuses

#Keys

KEY is a single character or one of enter (or return), escape (or esc), tab, backspace, delete, insert, home, end, up, down, left, right, pageup, pagedown, f1 to f12. Use keypad:0 to keypad:9 for the numeric keypad.

#Worktrees

REPO defaults to the current folder.

See Worktrees and review.

#Workspaces, tabs and panes

These commands change the layout the app shows. Each one prints the new layout as JSON. Add --revision N to fail if someone else changed the layout first.

#Events

#Notes

dirijor note TEXT writes a quick note for the current project. The first line is its title.

NOTE is a note id or part of its title.

#Notifications

dirijor notify --title TEXT --body TEXT prints a notification escape sequence to the terminal, so it works in local and remote sessions without a socket. diri shows it like an agent notification.

#MCP from the shell

dirijor mcp-tools prints every tool the MCP server offers. dirijor mcp-call --tool NAME reads the tool's input as JSON from stdin and prints {"ok": ...} or {"error": ...}. Write tools need a live diri session identity, so call them from inside a diri session. See the MCP tool reference and the security model.

#Examples

These work in fish, zsh and bash.

Find sessions waiting for you:

dirijor session list --status needsInput

Start Codex in a new worktree with a task, then wait for it to finish:

dirijor session spawn codex --worktree --branch fix-login --title fix-login --prompt "Fix the failing login test"
dirijor session wait fix-login --until done --until needsInput --timeout 1800

Read the last 20 lines of a session's screen:

dirijor session read fix-login --lines 20

Run tests in their own terminal session and wait until the command exits:

dirijor session run --title tests -- cargo test --workspace
dirijor session wait tests --until exited

Dismiss a prompt with Escape, then send a follow-up. session key needs the exact id from session list; replace SESSION_ID with it:

dirijor session key SESSION_ID escape
dirijor session send fix-login "Use the existing helper instead"

Pipe a file into a new note:

cat plan.md | dirijor note add --title "Release plan" --pin