AppleScript (macOS)

macOS 上的 Ghostty 暴露一個原生的 AppleScript 字典，讓腳本可以查詢和控制終端機視窗、分頁與分割窗格。這讓 Ghostty 可以輕鬆地與 osascript、啟動器工作流程、編輯器外掛和自訂自動化腳本等工具整合。

AppleScript 支援於 Ghostty 1.3.0 中引入。

AppleScript API 的權威來源是 Ghostty 的腳本定義文件：Ghostty.sdef。查看它的最佳方式是將其載入 Script Editor，並用 macOS 圖形介面瀏覽 API。

要從已安裝的應用程式套件檢視此字典：

sdef /Applications/Ghostty.app | less

要驗證腳本功能是否可用：

osascript -e 'tell application "Ghostty" to get version'

Ghostty 的 AppleScript 模型是階層式的：

application -> windows -> tabs -> terminals

物件	關鍵屬性	關鍵元素
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	無

front window 回傳最前面的 Ghostty 視窗。focused terminal 回傳分頁中的活動終端機，這對操作目前擁有焦點之終端機的腳本很有用。

tell application "Ghostty"
    set win to front window
    set tab1 to selected tab of win
    set term1 to focused terminal of tab1
    set allTermsInWin to terminals of win

    set cwdMatches to every terminal whose working directory contains "ghostty"
end tell

這兩個屬性讓操作當前環境的腳本更為簡潔：

tell application "Ghostty"
    set term to focused terminal of selected tab of front window
    input text "pwd\n" to term
end tell

tell application "Ghostty"
    set currentTerm to focused terminal of selected tab of front window
    set newTerm to split currentTerm direction right
    input text "echo split-ready\n" to newTerm
end tell

指令	用途	範例語法
new surface configuration	建立可重用的介面設定記錄。	set cfg to new surface configuration
new window	建立新視窗。	set win to new window with configuration cfg
new tab	在可選的目標視窗中建立新分頁。	set t to new tab in win with configuration cfg
split	分割終端機並回傳新終端機。	set t2 to split t1 direction right with configuration cfg

split direction 的值為 right、left、down 和 up。

指令	用途	範例語法
focus	聚焦終端機並將其視窗帶到最前。	focus t1
activate window	將視窗帶到最前。	activate window (window 1)
select tab	選取一個分頁。	select tab (tab 2 of window 1)
close	關閉終端機。	close (terminal 2 of selected tab of window 1)
close tab	關閉分頁。	close tab (tab 2 of window 1)
close window	關閉視窗。	close window (window 1)

指令	用途	範例語法
input text	對終端機發送貼上樣式的文字輸入。	input text "echo hello" to t1
send key	發送帶有可選修飾鍵的按鍵按下／放開事件。	send key "enter" to t1
send mouse button	發送滑鼠按鍵事件。	send mouse button left button to t1
send mouse position	發送指標位置更新。	send mouse position x 240 y 120 to t1
send mouse scroll	發送帶精度／動量選項的滾動事件。	send mouse scroll x 0 y -8 precision true to t1
perform action	在終端機上執行 Ghostty 動作字串。	perform action "toggle_fullscreen" on t1

對 send key 和 send mouse button 而言，action 可以是 press 或 release。modifiers 是逗號分隔的字串，可包含：shift、control、option、command 中任意組合。

對 perform action 而言，動作字串與鍵位綁定設定中使用的動作名稱一致。參見鍵位綁定動作參考。

new surface configuration 建立一個可重用的值記錄，可以傳給 new window、new tab 和 split。

支援的欄位有：

• font size
• initial working directory
• command
• initial input
• wait after command
• environment variables（KEY=VALUE 字串的清單）

範例：

tell application "Ghostty"
    set cfg to new surface configuration
    set initial working directory of cfg to POSIX path of (path to home folder) & "src/ghostty"
    set font size of cfg to 13
    set environment variables of cfg to {"EDITOR=nvim", "FZF_DEFAULT_OPTS=--height 40%"}

    set win to new window with configuration cfg
end tell

macOS 上預設啟用 AppleScript 支援。macOS 透過自動化權限（TCC）保護應用程式之間的自動化，因此在另一個應用程式可以控制 Ghostty 前，系統會先詢問。

如果你想完全停用 AppleScript 支援，請設定：

macos-applescript = false

set projectDir to POSIX path of (path to home folder) & "src/ghostty"

tell application "Ghostty"
    activate

    set cfg to new surface configuration
    set initial working directory of cfg to projectDir

    set win to new window with configuration cfg
    set paneEditor to terminal 1 of selected tab of win
    set paneBuild to split paneEditor direction right with configuration cfg
    set paneGit to split paneEditor direction down with configuration cfg
    set paneLogs to split paneBuild direction down with configuration cfg

    input text "nvim ." to paneEditor
    send key "enter" to paneEditor

    input text "zig build -Demit-macos-app=false" to paneBuild
    send key "enter" to paneBuild

    input text "git status -sb" to paneGit
    send key "enter" to paneGit

    input text "tail -f /tmp/dev.log" to paneLogs
    send key "enter" to paneLogs

    focus paneEditor
end tell

set cmd to "date"

tell application "Ghostty"
    set allTerms to terminals

    repeat with t in allTerms
        input text cmd to t
        send key "enter" to t
    end repeat

    display dialog ("Broadcasted to " & (count of allTerms) & " terminal(s).")
end tell

使用 perform action 搭配 set_tab_title，可以從腳本為分頁設定標題。

建立新分頁並設定標題的範例：

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
    input text "nvim .\n" to focused terminal of t1

end tell

set needle to "ghostty"

tell application "Ghostty"
    set matches to every terminal whose working directory contains needle

    if (count of matches) = 0 then
        set matches to every terminal whose name contains needle
    end if

    if (count of matches) > 0 then
        set t to item 1 of matches
        focus t
        input text "echo '[focused by AppleScript]'" to t
        send key "enter" to t
    end if
end tell