All pages
Lesson 8.3 · Make it yours · 12 min
The trmnly command and scripting
Drive TRMNLY from the shell, AppleScript and Shortcuts.
After this lesson, you can drive TRMNLY from a shell script, a Makefile or an agent running in a pane. You can name panes, raise a flag when you need a decision, and add cards to the board. You can also run commands in TRMNLY from AppleScript and the Shortcuts app.
Time: 12 minutes · Works on: macOS app
Check the command works
The trmnly command ships inside the app. Every pane exports $TRMNLY_SURFACE_ID, so commands act on the pane you run them in unless you pass --surface.
Open a pane and run:
trmnly identifyIt prints this pane's ids and paths.
If your shell says
command not found, open Settings → AI Agent, find Pane manifests, and press InstalltrmnlyCLI. That adds a symlink in/usr/local/bin.If
trmnlyruns but can't reach the app, runtrmnly doctor. Read itsappline.reachablemeans everything should work. Otherwise it names the reason, and inside a pane the fix is usually to relaunch TRMNLY.
trmnly help lists every command.
Name your panes
With several agents or jobs running, the sidebar shows a row of shells that all look alike. A pane can describe itself:
trmnly set-title "API tests"
trmnly set-description "Running the integration suite; next, fix failures."
trmnly set-status running
trmnly set-progress 0.4
The pane's sidebar row now shows the title, the description underneath, a status pill and a progress bar.
- Title is short and stable. Make the first word differ between panes, because the sidebar cuts long titles from the right.
- Description is what the pane is doing now. Update it when the work moves on.
- Status fades after five minutes. After that the pill shows TRMNLY's own guess, marked with
~, so a stopped job can't look busy forever.
Tip: Put these lines in a long script or ask an agent to call them. They work the same either way.
Ask for a decision with a flag
trmnly raise-flag "Need a call: migrate the schema now or dual-write first?"
The pane is marked as flagged in the sidebar, moves to the front of the attention list, and sends a notification even when TRMNLY isn't the front app. Typing into the pane lowers the flag, because your reply is the answer. trmnly flags lists every flagged pane, oldest first.
Flag only when the work has stopped on a decision a person has to make. "I'm finished" is not a flag.
See every pane
trmnly tree
This lists every window and pane with its title and status. Add --json to use it in a script. trmnly read-screen prints a pane's visible text, and trmnly send "npm test" --submit types into one.
Work the board from the shell
These commands go straight into the project's Tasks board, the same one the agent uses:
trmnly task add "Fix flaky login test"
trmnly task list
trmnly task move "#3" Done
Run from inside a project folder, they act on that project's board. trmnly chat post "deploy is green" posts to the project's chat in the same way.
Call any tool
Every tool the agent has is reachable from the shell:
trmnly tools --grep port
trmnly call ports_list '{}'
The command counts as you typing in your own shell, so it skips the approval prompts that outside apps get. Treat trmnly call in a script with the same care as any other command it runs.
AppleScript
TRMNLY has an AppleScript dictionary. Open Script Editor, choose File → Open Dictionary…, and pick TRMNLY to browse it. It covers windows, tabs and terminals, and commands such as new tab, split, input text and queue command.
Queueing is the reliable way to run commands from a script. Each entry runs when the previous command finishes, instead of being pasted into whatever is running:
tell application "TRMNLY"
queue command "npm test" to terminal 1 of tab 1 of window 1
end tell
Shortcuts
The Shortcuts app lists TRMNLY actions, including Queue Command in Terminal, Run Next Queued Command, Open the Quick Terminal and Invoke Command Palette Action. Terminals appear as items you can pick, so a shortcut can target one pane.
Stay in control
Scripts run commands in your shell, so each source has its own controls. Open Settings → Security and find Scripting consent. AppleScript, Shortcuts and the other sources each have Enabled and Confirm every command, plus a rate limit. Multi-line commands with Return are always refused, and so is text that hides escape sequences or invisible characters.
Check yourself
trmnly identifyprints your pane's ids.- After
trmnly set-title, the sidebar row shows your title. trmnly raise-flagmarks the pane as flagged, and typing into it clears the flag.- An AppleScript
queue commandruns in the pane you targeted.
Go further
- Pane manifests &
trmnlyCLI: metadata keys, suppression, the event log and panes that message each other. - Scripting: the full AppleScript dictionary and every Shortcuts action.
- The command queue: what
queue commandfeeds into.