Skip to content

content/applescript: name override and markdown table formatting #495

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paaloeye wants to merge 2 commits into
base: main
Choose a base branch
from
Open

content/applescript: name override and markdown table formatting #495

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
058278d
content/script: document name override property
paaloeye Oct 28, 2026
c4f3840
content/applescript: format markdown tables
paaloeye Oct 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 34 additions & 33 deletions docs/features/applescript.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,12 @@ Ghostty's AppleScript model is hierarchical:
application -> windows -> tabs -> terminals
```

| Object | Key Properties | Key Elements |
| ------ | -------------- | ------------ |
| `application` | `name`, `frontmost`, `front window`, `version` | `windows`, `terminals` |
| `window` | `id`, `name`, `selected tab` | `tabs`, `terminals` |
| `tab` | `id`, `name`, `index`, `selected`, `focused terminal` | `terminals` |
| `terminal` | `id`, `name`, `working directory` | None |
| Object | Key Properties | Key Elements |
| ------------- | ---------------------------------------------------------------------- | ---------------------- |
| `application` | `name`, `frontmost`, `front window`, `version` | `windows`, `terminals` |
| `window` | `id`, `name`, `selected tab` | `tabs`, `terminals` |
| `tab` | `id`, `name`, `index`, `selected`, `focused terminal`, `name override` | `terminals` |
| `terminal` | `id`, `name`,`working directory`, `name override` | None |

`front window` returns the frontmost Ghostty window. `focused terminal`
returns the active terminal in a tab, which is useful for scripts that
Expand Down Expand Up @@ -86,36 +86,36 @@ end tell

### Creation and Layout

| Command | Purpose | Example Syntax |
| ------- | ------- | -------------- |
| `new surface configuration` | Create a reusable surface configuration record. | `set cfg to new surface configuration` |
| `new window` | Create a new window. | `set win to new window with configuration cfg` |
| `new tab` | Create a new tab in an optional target window. | `set t to new tab in win with configuration cfg` |
| `split` | Split a terminal and return the new terminal. | `set t2 to split t1 direction right with configuration cfg` |
| Command | Purpose | Example Syntax |
| --------------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
| `new surface configuration` | Create a reusable surface configuration record. | `set cfg to new surface configuration` |
| `new window` | Create a new window. | `set win to new window with configuration cfg` |
| `new tab` | Create a new tab in an optional target window. | `set t to new tab in win with configuration cfg` |
| `split` | Split a terminal and return the new terminal. | `set t2 to split t1 direction right with configuration cfg` |

`split direction` values are `right`, `left`, `down`, and `up`.

### Focus, Selection, and Lifecycle

| Command | Purpose | Example Syntax |
| ------- | ------- | -------------- |
| `focus` | Focus a terminal and bring its window to front. | `focus t1` |
| `activate window` | Bring a window to the front. | `activate window (window 1)` |
| `select tab` | Select a tab. | `select tab (tab 2 of window 1)` |
| `close` | Close a terminal. | `close (terminal 2 of selected tab of window 1)` |
| `close tab` | Close a tab. | `close tab (tab 2 of window 1)` |
| `close window` | Close a window. | `close window (window 1)` |
| Command | Purpose | Example Syntax |
| ----------------- | ----------------------------------------------- | ------------------------------------------------ |
| `focus` | Focus a terminal and bring its window to front. | `focus t1` |
| `activate window` | Bring a window to the front. | `activate window (window 1)` |
| `select tab` | Select a tab. | `select tab (tab 2 of window 1)` |
| `close` | Close a terminal. | `close (terminal 2 of selected tab of window 1)` |
| `close tab` | Close a tab. | `close tab (tab 2 of window 1)` |
| `close window` | Close a window. | `close window (window 1)` |

### Input and Actions

| Command | Purpose | Example Syntax |
| ------- | ------- | -------------- |
| `input text` | Send paste-style text input to a terminal. | `input text "echo hello" to t1` |
| `send key` | Send key press/release events with optional modifiers. | `send key "enter" to t1` |
| `send mouse button` | Send mouse button events. | `send mouse button left button to t1` |
| `send mouse position` | Send pointer position updates. | `send mouse position x 240 y 120 to t1` |
| `send mouse scroll` | Send scroll events with precision/momentum options. | `send mouse scroll x 0 y -8 precision true to t1` |
| `perform action` | Execute a Ghostty action string on a terminal. | `perform action "toggle_fullscreen" on t1` |
| Command | Purpose | Example Syntax |
| --------------------- | ------------------------------------------------------ | ------------------------------------------------- |
| `input text` | Send paste-style text input to a terminal. | `input text "echo hello" to t1` |
| `send key` | Send key press/release events with optional modifiers. | `send key "enter" to t1` |
| `send mouse button` | Send mouse button events. | `send mouse button left button to t1` |
| `send mouse position` | Send pointer position updates. | `send mouse position x 240 y 120 to t1` |
| `send mouse scroll` | Send scroll events with precision/momentum options. | `send mouse scroll x 0 y -8 precision true to t1` |
| `perform action` | Execute a Ghostty action string on a terminal. | `perform action "toggle_fullscreen" on t1` |

For `send key` and `send mouse button`, `action` can be `press` or
`release`. `modifiers` is a comma-separated string containing any of:
Expand Down Expand Up @@ -215,21 +215,22 @@ tell application "Ghostty"
end tell
```

### Set Tab Titles
### Set Tab and Terminal Titles

Use `perform action` with `set_tab_title` to label tabs from a script.
Both `tab` and `terminal` objects expose a read-write `name override` property.
Setting it overrides the automatically reported title, and setting it to an
empty string (`""`) clears the override.

An example of creating a new tab and setting the title:
An example of creating a new tab and setting its title override:

```AppleScript
tell application "Ghostty"
set win to front window
set cfg to new surface configuration

set t1 to new tab in win with configuration cfg
perform action "set_tab_title:Editor" on focused terminal of t1
set name override of t1 to "Editor"
input text "nvim .\n" to focused terminal of t1

end tell
```

Expand Down