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/

The View Logs button on each tool card (or each nested row inside a group) opens every log file for that tool in Console.app at once.

Rotation and retention

Logs are rotated automatically. Each stream lives at {Name}.log, and older content gets archived as {Name}.log.1 (most recent), then {Name}.log.2.gz, {Name}.log.3.gz, etc. The first rotation stays uncompressed so you can grep or tail it without extracting; older rotations are gzipped.

Defaults: 5 MB per file, 3 rotations kept, 30-day age cap. Tune via Settings → Advanced → Logs, or by editing advanced.logMaxFileSizeMB / logKeepRotations / logMaxAgeDays in config.json. Rotations past the size or age cap are cleaned up at the next app launch.

To browse rotated files for one tool, right-click its card in the popover and choose Reveal Logs in Finder. The tool's live files are highlighted in the Finder window; archived siblings sit alongside them.

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

1. Open the popover and click View Logs on the tool's card. Scroll to the bottom of each Console.app window; most failures print a stack trace or error near the end.
2. If the tool errored during install, open {ToolName}-install.log.
3. 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 runs commands in a sanitized environment that does not load your shell's init files. See Shell environment and PATH below for the full explanation and fixes.
• 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.

Shell environment and PATH

Most "it works in my terminal, not in Runyard" issues trace back to one root cause: Runyard does not inherit your shell's environment. When you start a service or run an action, Runyard spawns the process with a minimal, sanitized environment built from your config.

What Runyard sets

• PATH is built from the paths array in your config (global plus tool-level, in priority order). Nothing else is inherited.
• A handful of safe variables: HOME, USER, LANG, SHELL, TMPDIR, SSH_AUTH_SOCK.
• Nothing else. Your .zshrc, .zprofile, .bash_profile, .bashrc are not sourced. Variables exported by nvm, fnm, direnv, mise, asdf, Homebrew shellenv, 1Password CLI, etc. are absent.

This is intentional: it makes Runyard predictable across machines and prevents subtle "works on my Mac" bugs.

Symptoms

• command not found: node (or npm, aws, docker, mise, etc.)
• The command runs, but with the wrong version (e.g., system Node 16 instead of project Node 22).
• The command runs, but with stale or missing env vars (no DATABASE_URL, no AWS profile, etc.).
• AppleScript actions that spawn shell sub-processes fail the same way.

Fix 1: extend paths

Add the directories that contain the missing binaries. This is the most direct fix and works for any service.

{
  "paths": [
    "/opt/homebrew/bin",
    "~/.nvm/versions/node/v22.0.0/bin",
    "/Applications/Docker.app/Contents/Resources/bin"
  ]
}

You can also set paths per-tool. By default tool-level paths merge with global; set pathsOverride: true on the tool to replace the global list entirely.

Use this when: the tools you need are static, you don't rely on shell init magic, and you want the lowest startup overhead.

Fix 2: wrap the command in a login shell

Run your command inside /bin/zsh -lc '…' (or /bin/bash -lc). The -l makes it a login shell, which sources your init files. nvm, fnm, direnv, Homebrew, and the rest initialize as if you'd opened a terminal.

"startCommands": [{
  "label": "Dev",
  "command": "/bin/zsh",
  "args": ["-lc", "npm run dev"]
}]

Use this when: you depend on shell-managed tool versions (nvm + .nvmrc), env loaders (direnv, mise), or anything that hooks into .zshrc. It is slower by a few hundred milliseconds per start but mirrors your terminal behaviour exactly.

When to use which

Quick test

To verify what env your command actually sees, run this once as a one-off action:

{
  "label": "Print env",
  "type": "command",
  "command": "/usr/bin/env"
}

Trigger it from the popover, then open the action's log file from ~/Library/Logs/Runyard/. Compare the listed PATH and variables against what env prints in a fresh terminal. The diff is your missing-pieces list.

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.

1. Open Runyard → Settings → General.
2. Under Files, click Change Location….
3. Pick a synced folder. Runyard copies config.json there and reloads from the new path.
4. 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:

1. Falls back to the default location (~/Library/Application Support/Runyard/config.json).
2. 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, so 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 field path (for example, tools[My App].startCommands[0].command). 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.

Importing a shared tool

Imported tools are intentionally set to not auto-start, so a freshly imported tool stays idle until you start it from the popover. If an AppleScript action does nothing, its script file may not have been bundled (the import sheet flags this in amber). For version-mismatch and "not a Runyard file" messages, and the full flow, see Exporting & Importing Tools.

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.