Terminal Documentation

YEN works without an account. Dictation behavior depends on macOS and available speech assets; see Speech-to-Text.

YEN starts with a native macOS terminal and layers IDE workflows around it. Settings and workspace panels use native macOS UI; browser preview uses Apple WebKit. Editor commands can open your configured external editor.

The terminal renders with Metal. Windows, tabs, split layouts, and positions restore on relaunch; this does not resume running commands. Use the shortcut reference for tabs, splits, Quick Terminal, and window screenshots.

• Scratchpad: one locally saved notes buffer shared across windows. It supports copy, paste, and copy-on-select when enabled.
• Layouts: ten presets in Settings > Workspace. Single Pane requires a second invocation to confirm closing other panes.
• Bundled tools: fd, rg, fzf, zoxide, bat, jq, and other terminal helpers. IDE integrations can require additional tools; see IDE Workflows.
• Shell integration: automatic detection supports bash, zsh, fish, elvish, and nushell. YEN command wrappers and cd-on-quit are supplied for bash and zsh.

Approach comparison

This is a conceptual comparison; editor features vary by product. YEN keeps the terminal as the primary workspace.

With the default bindings, Cmd + C copies the terminal selection and Cmd + V uses the native paste action, including in terminal applications. Custom bindings are respected; applications still control how pasted text is handled.

Copy on Select can be disabled in Settings > General. File URLs paste as paths; image-only clipboards become temporary image files.

YEN adds IDE workflows directly to the terminal. The yen ide commands cover workspace trust, search, debugging, local LSP, verification, adapters, and PR review without pushing you into a separate editor UI.

Start with project status:

$ yen ide doctor
yen ide trust status
yen ide test status
yen ide workflow discover
yen ide lsp status
yen ide --help

$ yen ide test run --runner node-test --watch --watch-interval 0.5 --max-runs 3
yen ide workflow run --native package.json:test --dry-run
yen ide workflow run --native package.json:test --watch --watch-interval 0.5 --max-runs 2

On macOS, Cmd + Shift + P opens the command palette for actions and project search. It can jump straight to matching files and lines, and in trusted local repos it also launches dedicated PR review and merge-conflict workspaces.

Remote targets are supported by detect, doctor, trust status, verify status, workflow, devcontainer, debug, and share. Use ssh://user@host/absolute/path and check the command's help for supported options. SSH probes need Python 3 on the remote host. Local-only options such as --watch remain blocked instead of silently degrading.

Grant Accessibility, Microphone, and Speech Recognition in Settings > Sounds > Speech Permissions. Focus a text field, hold Option + Space, speak, and release to paste. On macOS 26+, transcription uses Apple's on-device SpeechAnalyzer. On older versions, YEN requests on-device recognition when Apple reports it is available; otherwise Apple's Speech framework can use its network service. YEN does not send your audio or transcript to a YEN service. Read more on the blog.

Works on macOS 13+. On macOS 26+, YEN uses Apple's SpeechAnalyzer with DictationTranscriber, has no YEN-imposed 60-second timer, and can ask macOS to install missing language packs while Settings is frontmost. Apple can still end a session after an input, asset, or system-resource failure. If the analyzer is unavailable, YEN can fall back to the legacy recognizer, which stops after 60 seconds and inserts the available result.

While YEN listens, a layered rainbow waveform responds to your microphone beside the status text. Reduce Motion keeps the live level feedback but freezes the waveform's flowing phase.

In-app paste restores your previous clipboard shortly after paste; cross-app paste always leaves the dictated text on the clipboard because delivery cannot be confirmed. Live Transcript Preview is available in the overlay. Translate-on-Dictate requires macOS 26+, is off by default, is tied to the recognizer locale for that capture, and runs only when the selected language pair is already installed. If translation fails, YEN inserts the original transcript.

Choose a microphone in Settings > Sounds > Dictation. System Default follows macOS; an unavailable selected device falls back to it. A change during recording stops that capture; select a device before restarting.

Secure Input blocks both clipboard writes and automatic insertion. If the target changes or automatic paste fails, YEN leaves the transcript on the clipboard for manual paste and shows a recovery notification.

Pro tip: On older macOS, release and press again for longer content. Enable Launch at Login in Settings> General > Startup for dictation without a terminal window open.

Press Cmd + , to open Settings. General, Sounds, Workspace, Themes, and Keyboard share search, import, export, and reset controls. Most changes apply across open tabs immediately; background opacity requires an app restart.

YEN includes curated bundled themes with live previews. Font, cursor, background image, opacity, and padding stay independent from theme selection (background opacity takes effect after an app restart). General also includes Window Border with manual numeric fields for width and radius, plus a background-image picker that imports PNG and JPEG assets into app-managed storage. The scope toggle below the import button sets whether the wallpaper renders per split (Each Split, the default) or as one shared backdrop behind the entire split tree (Whole Window). Workspace also exposes Tab Sidebar (Cmd + Shift + B) and Scratchpad (Cmd + Shift + J), plus Browser toggles for explicit terminal link capture and split targeting.

Sounds combines speech permissions, local speech readiness, Translate-on-Dictate controls, and per-stream notifications for General and Build. Each stream has its own sound, volume, and delivery mode (Off, Banner Only, Sound Only, Banner + Sound).

Keyboard lets you inspect conflicts and re-record editable shortcuts inline. Fixed shortcuts and duplicate-action rows stay read-only, and imported settings are validated before they apply.

Export and import include both config.yen and the Settings-managed preferences kept outside it, including workspace toggles, Browser link/split settings, theme-browser mode, Window Border, dictation preview/translation state, and notification routing. Portable exports intentionally exclude machine-local assets such as background images.

Machine-local state such as permission grants, Launch at Login, background images, and installed user themes stays on the current Mac.

In the command palette, search Settings: Themes, Settings: Sounds, Settings: Workspace, or Settings: Keyboard to open a specific tab.

Advanced configuration:

~/Library/Application Support/com.yenchat.yen/config.yen

Press Cmd + Shift + B to open the Tab Sidebar. In transient mode it slides in over the left edge of the active terminal window. Use the header pin button, command palette, or Settings > Workspace to switch it into the persistent docked rail.

When YEN cannot trust the focused split's local path context (terminal multiplexers, remote sessions, detached commands, or empty project state), the sidebar omits cwd and git summaries instead of showing guessed metadata.

Each split pane can have a custom label displayed as a themed pill at the bottom-left corner. Turn it on in Settings → Workspace → Split Labels → Enabled; it is off by default, and the rename command stays hidden until it is on. Then open the command palette (Cmd + Shift + P) and search Rename Split Label to set or clear a label.

Press Cmd + Shift + O to open the file browser in the active terminal. It does not open as a floating window or global sidebar, and it will not steal focus from another window. Browse directories, preview files, and manage the project without leaving the terminal.

Open the command palette with Cmd + Shift + P, search Browser, web preview, localhost, or dev server, and press Enter. Search terminal browser for Browser Split. YEN opens a native WebKit window or explicit split for docs, HTTPS pages, and localhost/loopback development servers.

yen web open https://yen.chat/docs
yen web open --split http://localhost:3000
yen web reload --target window
yen web status
yen web close

On macOS 14+, YEN also exposes actions in Apple Shortcuts. The macos-shortcuts config accepts ask, allow, or deny. The default asks for permission by action scope. Action invocation is limited to YEN's approved command catalog.

YEN ships a branded AppleScript dictionary for local macOS automation. It is enabled by default and can be disabled in config.yen with macos-applescript = false. Target YEN by absolute bundle path when scripting a specific build.

AppleScript can create windows, tabs, and splits with an initial working directory and input. YEN-native overlays such as layout presets, scratchpad, tab sidebar, and PR review workspaces remain command-palette or config-driven instead of being cloned into a second scripting model.

send key does not derive text from your active keyboard layout. Use input text to send literal text.

on yenNewWindow(appPath, surfaceConfig)
	tell application appPath
		return «event GhstNWin» given «class GNwS»:surfaceConfig
	end tell
end yenNewWindow

set appPath to "/Applications/YEN.app"
set projectRoot to "/absolute/path/to/project"
set windowRef to yenNewWindow(appPath, {initial working directory:projectRoot, initial input:"git status" & linefeed})

tell application appPath
	get tty of terminal 1 of windowRef
end tell

Default shortcuts are listed below. Editable bindings can change in Settings > Keyboard.

Keyboard shortcuts:

The Git drawer is a read-only local changes view for the active split: branch/upstream status, grouped changed files, untracked-aware stash file lists, raw unified diff, copy/open actions, clear no-repo/failure notices, and handoff to bundled lazygit. It appears as a bottom overlay, so it does not resize the window or compress split panes. Use yengit for the full terminal Git TUI, the PR review workspace for pull-request review, and the merge-conflict workspace for conflict resolution. With the tab sidebar hidden, a directory change can take up to 15 seconds to appear.

CLI commands:

YEN-launched bash and zsh shells include command wrappers. In an external shell, run yen init zsh or yen init bash to print setup code. Review and add that output to your shell startup file (~/.zshrc, or ~/.bashrc / ~/.bash_profile), then restart the shell. The command does not edit those files. If yen is not on PATH, invoke /Applications/YEN.app/Contents/Resources/bin/yen.

Need the complete command + alias reference? Run yen help. For full file browser shortcuts, press ? inside the file browser.

Custom keybindings:

Shortcut editing lives in Settings > Keyboard. For advanced changes, edit the config file directly.

• App won't open: Right-click YEN.app, then Open, or allow in System Settings > Privacy & Security.
• Commands not found: Follow the shell setup instructions. In YEN, check that shell integration is enabled. Bare command wrappers and y require bash or zsh.
• Speech-to-text not working: Grant Accessibility, Microphone, and Speech Recognition permissions in System Settings > Privacy & Security. Dictation listens to exact Option + Space only (no Cmd/Ctrl/Shift). Click the YEN menu bar extra (a template waveform when idle, or the recording-dot status item while dictation is active) for blocked-state recovery actions, or open Settings > Sounds > Speech Permissions and click Re-check.
• Option + Space conflicts: Check for conflicts with input source, Spotlight, Alfred, or Raycast shortcuts. Use Settings > Keyboard for fixed-shortcut conflict guidance.
• Layout shortcut not firing: Use exact Cmd + Option + 1-0 with no extra modifiers and click a terminal window first. Layout presets are intentionally ignored while Settings or another utility window is key.
• Cursor style / blink not previewing: Changes are applied, but preview appears after you refocus a terminal window (unfocused terminals show a hollow block cursor).
• Opacity slider looks unchanged: Background opacity applies after app restart. Use Window Border for an immediate focus cue.
• File browser not opening: Verify the terminal window is focused, not the Settings panel or another window.
• Browser preview blocks a URL: Use HTTPS for remote pages or localhost / loopback HTTP for local development servers. File, data, JavaScript, blob, unknown-scheme, and non-local HTTP URLs are intentionally blocked.
• "command not found: y": The cd-on-quit wrapper is supplied only in YEN-launched bash and zsh shells. External shells can use yen browse, which does not change the shell directory.
• btop / fastfetch runs a system command: Check the shell setup and restart the shell. YEN's wrappers should resolve the bundled tools.

Back up config.yen before resetting terminal settings:

$ mv "$HOME/Library/Application Support/com.yenchat.yen/config.yen" "$HOME/Library/Application Support/com.yenchat.yen/config.yen.backup-$(date +%s)"

Quit YEN before moving the file, then reopen it. This removes the overrides stored in config.yen (font, cursor, background opacity, padding, theme, keyboard overrides). Preferences kept in macOS UserDefaults — theme-browser mode, Window Border, Workspace and Browser toggles, dictation preview/translation state, and notification routing — survive this. To restore every in-app preference, open Settings (Cmd + ,) and use Reset [section] or Reset All… in the Reset row.

Terminal design has moved from dedicated hardware to software emulation, native desktop tools, web runtimes, and workflow-aware interfaces. These milestones explain the design traditions that YEN builds on.

1. 1978 — VT100

   DEC's VT100 helped establish ANSI terminal control sequences that remain part of terminal compatibility today. Source

2. 1984 — xterm

   xterm brought a software terminal emulator to the X Window System and became a long-running compatibility reference. Source

3. 2014 — iTerm2

   iTerm2 2.0 expanded the macOS terminal with deep tmux integration, triggers, a toolbelt, and extensive customization. Source

4. 2022 — Warp

   Warp entered public beta with a block-oriented interface for commands and their output. Source

5. Today — YEN

   YEN combines a native GPU terminal with Apple speech recognition, local workflow tools, and optional terminal-first IDE features. Source

This is a selective product-design timeline, not a complete history of terminal computing.