Dépannage

Commencer par isoler la couche en cause

Un problème CLI peut venir de plusieurs endroits : installation, PATH, connexion, réseau, projet courant, Git, permissions locales, configuration ou service distant. Avant de changer quoi que ce soit, identifiez la couche la plus probable.

Évitez de réinstaller, supprimer des fichiers ou modifier Git immédiatement. Commencez par des commandes de lecture qui décrivent l’état actuel. Cette approche réduit le risque d’effacer un indice utile ou de créer un second problème pendant le diagnostic.

Vérifier l’installation

La commande d’installation publique confirmée est :

$ npm install -g @orbitwake/cli

Si l’installation échoue, l’erreur npm est le premier élément à lire. Elle peut indiquer un problème de réseau, de permissions npm, de registre, d’environnement Node.js ou de paquet.

Cette documentation ne publie pas encore de version minimale officielle de Node.js ni de procédure spécifique par système d’exploitation. N’inventez pas un prérequis local : conservez le message d’erreur exact et vérifiez l’environnement avant de réinstaller plusieurs fois.

La commande orbitwake est introuvable

Si le shell indique que orbitwake n’existe pas, le problème se situe généralement entre l’installation globale et le PATH utilisé par le terminal.

Commencez par vérifier l’emplacement courant et la disponibilité de npm, puis comparez avec le terminal dans lequel l’installation a été effectuée.

$ pwd
$ npm --version

npm --version est une commande npm standard. La documentation OrbitWake ne publie pas encore de commande officielle de version du CLI, donc elle n’utilise pas ici orbitwake --version comme si cette interface était garantie.

Problème de connexion

Le flux confirmé démarre avec :

$ orbitwake login

Si la connexion ne se termine pas, vérifiez d’abord que la machine a accès au réseau et que le compte OrbitWake utilisé est valide. Si le CLI affiche une étape supplémentaire, suivez le flux présenté par le produit plutôt que d’essayer des flags non documentés.

La manière exacte de stocker, renouveler ou révoquer une session d’authentification n’est pas encore publiée comme contrat stable. Évitez donc de supprimer manuellement des fichiers supposés contenir un token si leur rôle n’est pas confirmé.

Mauvais projet ou mauvais contexte

Si OrbitWake semble analyser le mauvais projet, commencez par vérifier le répertoire courant avant de relancer la session.

$ pwd
$ git status
$ git branch --show-current
$ orbitwake

Le répertoire courant sert de point de départ au contexte. Dans un monorepo ou un dossier contenant plusieurs projets, lancez OrbitWake au niveau qui correspond réellement à la tâche.

Si le contexte paraît trop large ou trop pauvre, reformulez la tâche et indiquez les fichiers concernés plutôt que de supposer que tout le dépôt doit être chargé.

Problèmes liés à Git

Avant d’attribuer un comportement étrange à OrbitWake, vérifiez l’état Git. Des changements locaux existants, une branche inattendue ou un dépôt non propre peuvent expliquer une différence entre ce que vous attendez et ce que vous observez.

$ git status
$ git branch --show-current
$ git diff

N’utilisez pas reset, clean, rebase ou une autre opération destructive simplement pour « repartir propre ». Les changements présents peuvent appartenir à votre travail en cours et doivent être préservés tant que leur origine n’est pas comprise.

Commande refusée ou action bloquée

Une action peut être bloquée parce qu’elle dépasse la portée autorisée, touche un fichier protégé, demande une écriture, exécute une commande locale ou implique une opération externe sensible.

Dans ce cas, ne contournez pas automatiquement la restriction avec des droits plus élevés. Vérifiez d’abord l’action demandée, son impact et si elle correspond vraiment à votre intention.

La syntaxe exacte des approbations OrbitWake n’est pas encore publiée. Cette page ne recommande donc ni flag de contournement ni commande de type --force.

Réseau, latence et service distant

OrbitWake CLI dépend de services distants pour certaines opérations. Une connexion instable, un proxy, un filtrage réseau ou une indisponibilité temporaire peut interrompre le flux.

Si une requête reste bloquée ou échoue, vérifiez d’abord votre accès réseau général et l’état public du service OrbitWake. Évitez de modifier le projet local si le symptôme ressemble à une interruption distante.

Lorsque le problème est intermittent, conservez l’heure approximative, le message d’erreur exact et l’action qui était en cours. Ces informations sont plus utiles qu’une description générale comme « le CLI ne marche pas ».

Configuration inattendue

Si le comportement diffère entre deux machines, utilisateurs ou projets, comparez d’abord l’environnement et le contexte plutôt que de supposer un bug du modèle.

Les variables d’environnement, outils installés, branche Git, répertoire courant et futures sources de configuration OrbitWake peuvent influencer l’expérience.

Comme les fichiers et clés de configuration OrbitWake ne sont pas encore publiés comme interface stable, cette documentation n’indique pas de fichier à supprimer ou régénérer. Préservez l’état existant jusqu’à ce que la source du réglage soit identifiée.

Réponse lente, contexte trop large ou session longue

Une tâche très large peut nécessiter plus de temps qu’une demande ciblée. Un dépôt volumineux, un grand nombre de fichiers ou une session longue peut également augmenter la quantité de contexte à organiser.

Pour diagnostiquer ce type de problème, réduisez temporairement la portée : travaillez depuis le bon sous-répertoire, indiquez les fichiers importants et formulez une tâche précise. Si le comportement s’améliore, la taille du contexte faisait probablement partie du problème.

Une nouvelle session peut aussi être utile si l’interaction précédente a accumulé beaucoup de contexte sans rapport avec la tâche actuelle.

Préparer un rapport de problème utile

Quand un problème persiste, rassemblez les informations nécessaires pour le reproduire sans inclure de secrets. Un bon rapport réduit fortement le temps de diagnostic.

Retirez ou masquez les tokens, mots de passe, clés API, données clients et autres informations sensibles avant de partager une capture ou un log.

Ce qui reste à documenter

Les commandes officielles de diagnostic, la version du CLI, les logs locaux, les emplacements de cache, les mécanismes de réinitialisation, les codes d’erreur et les procédures de support ne sont pas encore publiés comme contrat stable.

Lorsqu’ils seront confirmés, ils seront ajoutés ici avec des commandes copiables et des procédures spécifiques. Jusqu’à ce moment, cette page privilégie des vérifications standard non destructives.

Étapes suivantes

Cette page clôt la série de base OrbitWake CLI. Vous pouvez revenir à Vue d’ensemble pour naviguer vers les autres sections Developers, notamment Code, Agents, Connectors, Cloud, VS Code et API.