All pages
Lesson 8.4 · Make it yours · 8 min
Troubleshooting and getting help
Fix the common problems and reach the team.
After this lesson, you can fix the problems people hit most often with TRMNLY. When you can't fix one, you can send the team a report with what they need to help.
Time: 8 minutes · Works on: all
Start with the version
Most answers depend on which version you're running.
On the Mac, choose TRMNLY → About TRMNLY.
Or, from any terminal, run:
trmnly --version
To check for a newer build, choose TRMNLY → Check for Updates.... Help → What's New in TRMNLY… lists what changed recently.
Find the answer in the app
Press ⌘?, or choose Help → TRMNLY Help. The Help tab opens in the right sidebar with the same pages as the docs on trmnly.dev. Help → Show First-Run Tour replays the introduction.
Common problems
TRMNLY only shows a sign-in window. Release builds open only for an approved trmnly.dev account. Choose Continue with GitHub or Sign in with trmnly.dev. A new account shows Waiting for approval. The window checks every 30 seconds and unlocks on its own once you're approved.
macOS asks for Accessibility or Screen Recording again. Grants are tied to TRMNLY's code signature. Install updates through TRMNLY's own updater or the downloaded DMG, not by copying the app by hand. Screen Recording only takes effect in a freshly launched app, so quit and reopen TRMNLY after you allow it. Settings → Permissions shows each grant's status, with Request and Open in System Settings… buttons.
The trmnly command can't reach the app. Run:
trmnly doctor
Read the app line. reachable means the command and the app agree. Otherwise it gives the reason. From inside a pane, the fix is almost always to relaunch TRMNLY.
Opening TRMNLY a second time just brings the first one forward. That's deliberate. One copy runs at a time, because a second copy would fight the first over the same files.
The Agent tab won't run. It needs a model provider. Add a key in Settings → API Keys, or connect a local model. Connect a model walks through it.
The agent says a key was rejected. Open Settings → Integrations and press Verify on that service. Rejected means the service refused the key, so replace it. Unreachable means TRMNLY got no answer, so check your network before replacing anything.
The cloud workspace won't start. A start is refused when your credit balance is empty. Check the balance on your trmnly.dev dashboard. Otherwise, a cold start takes about a minute.
The iPhone can't reach the Mac. Check the Mac is awake and TRMNLY is running. In Settings → AI Agent, under Remote Control (trmnly.dev), check Enabled is on and the Mac shows as paired.
TRMNLY crashed. Crash reports aren't in ~/Library/Logs. The terminal engine writes them to:
~/.local/state/ghostty/crash/
Attach the newest .ghosttycrash file when you report it. Help → Reveal Logs in Finder opens TRMNLY's other logs.
Report a bug or request a feature
Reports go straight to the people who build TRMNLY. You need to be signed in to trmnly.dev.
- Choose Help → Report a Bug or Request a Feature….
- Pick Bug report or Feature request.
- Write a title and the details. For a bug, say what happened, what you expected, and the steps that cause it.
- Leave Include diagnostics on. It adds the app version, build, macOS version and architecture. The window lists the exact values before you send. Paths, hostnames and file contents are never included.
- Send it. You get a reference like
FB-1A2B3C4D. Everything you've sent is listed at trmnly.dev under Feedback.
If you aren't signed in, the window says so, and Copy Report saves your text to the clipboard so nothing is lost.
You can also report from a terminal on any platform:
trmnly feedback bug "Files sidebar goes blank" --body "Steps: open a project, switch to another…"
Or ask the agent: "file a TRMNLY bug: the Files sidebar goes blank after switching projects". On the Mac it shows you the report for approval before anything is sent.
Tip: You can send up to 20 reports an hour from one account.
Contact support
For anything a report doesn't cover, such as account approval, billing or a refund, email will.schulz@aw3.tech. Put "TRMNLY support" and your trmnly.dev account email in the subject. Include your platform, the version, what happened, any error text, and the FB- reference if you filed a report.
Never send passwords, API keys or tokens. Nobody from TRMNLY will ask for them.
Check yourself
- You can find your TRMNLY version in two ways.
trmnly doctorprints anappline, and you know whatreachablemeans.- You know where to find a crash report, and which address to email.
Go further
- Troubleshooting: known issues from programs running in a pane, such as
gh auth login. - Reporting bugs and requesting features: every way to send a report, and the limits.
- Getting started: sign-in and approval in detail.