Sections

Guide utilisateur

Dépannage

Journaux, récupération de configuration, forçage de langue et résolution des problèmes courants.

Journaux

Runyard écrit un journal distinct pour chaque processus, action et commande d'installation sous ~/Library/Logs/Runyard/. Vous pouvez ouvrir directement ce dossier :

~/Library/Logs/Runyard/
Fichier Contenu
{NomOutil}-{Label}.log stdout + stderr de la commande de démarrage.
{NomOutil}-stop-{Label}.log Sortie d'une stopCommand personnalisée.
{NomOutil}-action-{Label}.log Sortie d'une action (commande shell ou AppleScript). Les espaces et les / dans l'étiquette deviennent des -, donc « Clear Cache » écrit MyApp-action-Clear-Cache.log.
{NomOutil}-install.log Sortie de installCommand.
{NomVerification}.log Historique des sondages par vérification d'état (horodatages, résultats, codes de réponse / erreurs).

Le bouton View Logs sur chaque carte d'outil (ou sur chaque rangée imbriquée dans un groupe) ouvre tous les fichiers journaux de l'outil dans Console.app en une seule fois.

Rotation et rétention

Les journaux font l'objet d'une rotation automatique. Chaque flux vit dans {Nom}.log, et le contenu plus ancien est archivé sous {Nom}.log.1 (plus récent), puis {Nom}.log.2.gz, {Nom}.log.3.gz, etc. La première archive reste non compressée pour permettre grep ou tail sans extraction ; les plus anciennes sont en gzip.

Valeurs par défaut : 5 Mo par fichier, 3 rotations conservées, plafond d'âge de 30 jours. Ajustables dans Préférences → Avancé → Journaux, ou en modifiant advanced.logMaxFileSizeMB / logKeepRotations / logMaxAgeDays dans config.json. Les archives qui dépassent les seuils de taille ou d'âge sont nettoyées au prochain démarrage de l'application.

Pour parcourir les archives d'un outil en particulier, faites un clic droit sur sa carte dans la fenêtre de la barre des menus et choisissez Révéler les journaux dans le Finder. Les fichiers en cours de l'outil sont mis en évidence dans la fenêtre Finder, et les archives apparaissent à côté.

Un outil refuse de démarrer : où regarder ?

  1. Ouvrez le popover et cliquez sur View Logs sur la carte de l'outil. Faites défiler jusqu'en bas de chaque fenêtre Console.app ; la plupart des échecs affichent une trace ou un message d'erreur à la fin.
  2. Si l'outil a échoué pendant l'installation, ouvrez {NomOutil}-install.log.
  3. Si le processus démarre mais n'atteint jamais l'état « running », la vérification d'état échoue probablement. Consultez le journal pour connaître l'URL interrogée, puis essayez cette URL dans un navigateur ou avec curl pour voir ce qu'elle retourne.

Causes courantes

Environnement shell et PATH

La plupart des problèmes du type « ça fonctionne dans mon terminal mais pas dans Runyard » remontent à une seule cause : Runyard n'hérite pas de l'environnement de votre shell. Quand vous démarrez un service ou lancez une action, Runyard lance le processus avec un environnement minimal et nettoyé, construit à partir de votre configuration.

Ce que Runyard définit

C'est intentionnel : Runyard devient prévisible d'un Mac à l'autre, et les bogues du type « ça marche chez moi » sont évités.

Symptômes

Correctif 1 : étendre paths

Ajoutez les répertoires qui contiennent les binaires manquants. C'est le correctif le plus direct, et il fonctionne pour n'importe quel service.

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

Vous pouvez aussi définir paths par outil. Par défaut, les chemins au niveau outil fusionnent avec ceux du niveau global ; mettez pathsOverride: true sur l'outil pour remplacer entièrement la liste globale.

À utiliser quand : les outils dont vous avez besoin sont stables, vous ne dépendez pas de la magie des fichiers d'init du shell, et vous voulez un démarrage le plus rapide possible.

Correctif 2 : encapsuler la commande dans un shell de connexion

Exécutez votre commande dans /bin/zsh -lc '…' (ou /bin/bash -lc). Le -l en fait un shell de connexion, qui charge vos fichiers d'init. nvm, fnm, direnv, Homebrew et le reste s'initialisent comme si vous aviez ouvert un terminal.

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

À utiliser quand : vous dépendez de versions d'outils gérées par le shell (nvm + .nvmrc), de chargeurs d'env (direnv, mise), ou de tout ce qui s'accroche à .zshrc. C'est plus lent de quelques centaines de millisecondes par démarrage, mais cela reproduit exactement le comportement de votre terminal.

Lequel utiliser

Situation Correctif recommandé
Besoin de /opt/homebrew/bin disponible Correctif 1 (paths)
Version Node fixe qui change rarement Correctif 1 (paths)
Bascule auto de Node via .nvmrc / .node-version Correctif 2 (shell de connexion)
Projet qui utilise direnv ou mise Encapsulez avec direnv exec / mise exec (voir Exemples de configuration)
Projet qui utilise asdf Correctif 2 (shell de connexion)

Test rapide

Pour vérifier l'environnement vu par votre commande, déclenchez cette action une fois :

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

Lancez-la depuis le popover, puis ouvrez le fichier journal de l'action dans ~/Library/Logs/Runyard/. Comparez le PATH et les variables affichées avec ce qu'env retourne dans un terminal vierge. La différence, c'est votre liste de pièces manquantes.

Synchroniser entre plusieurs Mac

Vous pouvez déplacer config.json vers iCloud Drive, Dropbox ou tout autre dossier synchronisé afin que tous vos Mac partagent la même configuration. L'interface complète est documentée dans Fenêtre Réglages → Fichiers.

  1. Ouvrez Runyard → Settings → General.
  2. Sous Files, cliquez sur Change Location….
  3. Choisissez un dossier synchronisé. Runyard y copie config.json et recharge depuis ce nouveau chemin.
  4. Sur chacun de vos autres Mac, répétez l'opération et choisissez le même dossier.

Le chemin retenu est stocké localement par Mac dans les UserDefaults ; chaque machine doit donc être réglée une fois. Seul le fichier de configuration lui-même est synchronisé par votre service de synchronisation.

Repli lorsque l'emplacement synchronisé est indisponible

Si le dossier choisi est introuvable au lancement de Runyard (service de synchronisation hors ligne, volume démonté, etc.), Runyard :

  1. Se replie sur l'emplacement par défaut (~/Library/Application Support/Runyard/config.json).
  2. Affiche une notification vous informant du repli.

Une fois le dossier synchronisé de nouveau disponible, Runyard s'y reconnecte au prochain relancement.

Réinitialiser par défaut

Réglages → General → Reset to Default recopie config.json vers l'emplacement par défaut. La copie synchronisée n'est pas supprimée, vous pouvez donc revenir en arrière par la suite.

Récupérer une configuration cassée

Si config.json contient une erreur de syntaxe, Runyard affiche une alerte au lancement (et au rechargement) pointant vers le chemin du champ fautif (par exemple, tools[Mon App].startCommands[0].command). Vous pouvez :

Importer un outil partagé

Les outils importés sont volontairement réglés pour ne pas démarrer automatiquement ; un outil fraîchement importé reste inactif jusqu'à ce que vous le démarriez depuis le popover. Si une action AppleScript ne fait rien, son fichier de script n'a peut-être pas été inclus (la fenêtre d'importation le signale en ambre). Pour les messages d'incompatibilité de version et « Ce n'est pas un fichier Runyard », ainsi que le flux complet, voir Exporter et importer des outils.

Forçage de langue

Runyard suit la langue système de macOS (Réglages Système → Général → Langue et région). Pour tester une langue précise sans modifier les réglages système, lancez depuis le Terminal.

Anglais :

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

Français :

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

Cela n'affecte que le lancement en cours. Quittez Runyard puis rouvrez-le normalement pour revenir à l'état précédent.

Toujours bloqué ?