Troubleshooting

Logs, config recovery, language override, and how to fix common issues.

Logs

Runyard writes a separate log for every process, action, and install command under ~/Library/Logs/Runyard/. You can open the folder directly with:

~/Library/Logs/Runyard/

File	What it contains
`{ToolName}-{Label}.log`	stdout + stderr of the start command.
`{ToolName}-stop-{Label}.log`	Output of a custom `stopCommand`.
`{ToolName}-action-{Label}.log`	Output of an action that runs a shell command.
`{ToolName}-install.log`	Output of `installCommand`.
`{ProbeName}.log`	Per-probe poll history (timestamps, outcomes, response codes / errors).

The menu's View Logs submenu opens these directly in Console.app.

A tool won't start — where do I look?

Open the tool's menu and click View Logs → {Label}. Scroll to the bottom; most failures print a stack trace or error near the end.
If the tool errored during install, open {ToolName}-install.log.
If the process starts but never reaches "running," the health check is probably failing. Check the log for the URL being polled, then try that URL in a browser or curl to see what it returns.

Common causes

Command not found. Runyard's PATH is built from the paths array in your config — it does not inherit your shell's PATH. If npm or node isn't found, add your Node install directory (e.g., ~/.nvm/versions/node/v22.0.0/bin) or Homebrew (/opt/homebrew/bin) to paths.
Startup check times out. The default is 30 s. Raise advanced.startupTimeout globally, or set a process-specific startupRequestTimeout on the start command for slow endpoints.
Port not detected. Some processes fork in ways lsof can't trace. Set startupFallbackPort on the start command as a hint.
Install loops. If installCommand runs every time, the markerPath (default node_modules) probably doesn't match what your installer creates. Set markerPath explicitly to a file or folder you know exists after install.

Syncing across Macs

You can move config.json to iCloud Drive, Dropbox, or any other synced folder so all your Macs share the same configuration. The full UI is documented in Settings Window → Files.

Open Runyard → Settings → General.
Under Files, click Change Location….
Pick a synced folder. Runyard copies config.json there and reloads from the new path.
On each other Mac, repeat the steps and pick the same folder.

The chosen path is stored per-Mac in UserDefaults, so each machine needs to be told once. Only the config file itself is synced by your sync service.

Fallback when the synced location is unavailable

If the chosen folder is missing when Runyard launches (sync service offline, volume unmounted, etc.), Runyard:

Falls back to the default location (~/Library/Application Support/Runyard/config.json).
Shows a notification telling you it did so.

Once the synced folder is available again, Runyard reattaches to it on the next relaunch.

Reset to default

Settings → General → Reset to Default copies config.json back to the default location. The synced copy is not deleted — you can switch back later.

Recovering from a broken config

If config.json has a syntax error, Runyard shows an alert on launch (and on reload) pointing at the line. You can:

Fix it in place. Open Settings → General → Open in Editor, or run Reload Configuration after editing to verify.
Restore the starter config. Delete ~/Library/Application Support/Runyard/config.json. On next launch Runyard writes a fresh sample based on the bundled template.
Keep a known-good backup. If your config lives in a synced folder with version history (iCloud Drive, Dropbox), revert to the last working revision.

Language override

Runyard follows your macOS system language (System Settings → General → Language & Region). To test a specific language without changing system settings, launch from Terminal:

# English
open /Applications/Runyard.app --args -AppleLanguages "(en)"

# French
open /Applications/Runyard.app --args -AppleLanguages "(fr)"

This affects only the current launch. Quit Runyard and open it normally to revert.

Still stuck?

Check the Menu Bar Guide for how each feature is supposed to behave.
Re-read the config.json Reference — most "weird" behaviour traces back to a default (e.g., showWhen: "running" hiding an action you added).
If you think something is a bug, reach out with your sanitized config.json and the relevant log excerpt:
- Use Send Feedback in Settings → About — it pre-fills the email with your version info and (optionally) attaches your config.json automatically.
- Or email support@bonevil.ca directly.

User Guide