[Feature Request] CLI de pilotage et interface d'automatisation pour OpenFox

[theshwal]

English summary

OpenFox today exposes a CLI meant mostly for serving and configuring the local instance. This request asks for a stable, public CLI surface to drive projects, sessions, commands, workflows, criteria, questions, confirmations, workspaces, branches, Plan, Build and Verify. The CLI must be a thin client of the same OpenFox server used by the web UI, share the same source of truth, and remain safely separable from the GUI flow. This is a discussion request, not a roadmap proposal, and we are open to maintainers' feedback on scope, architecture and the smallest useful MVP.

Problème observé

La CLI d’OpenFox telle qu’elle est documentée et utilisée aujourd’hui sert principalement à :

• démarrer/arrêter le serveur local ;
• configurer l’instance (providers, plugins, paramètres).

Il n’existe pas, à notre connaissance, d’interface CLI publique stable pour piloter une session de travail en cours : créer une session, lui envoyer un prompt, suivre son état, répondre à une question, confirmer une action, valider un plan, ou consulter de manière scriptable l’historique d’un projet. Cela limite fortement plusieurs cas d’usage :

• pilotage humain en SSH sur une machine distante ;
• automatisation via scripts, cron, GitHub Actions ou CI ;
• intégration avec des agents comme Hermes ou Orca qui ont besoin d’une API stable, structurée et testable ;
• future intégration avec Open Design (cf. discussion open design integration #198), où un autre agent doit pouvoir orchestrer OpenFox en arrière-plan.

L’interface web reste la source de vérité fonctionnelle, mais elle n’est pas un point d’entrée approprié pour l’automatisation ni pour des agents qui ne doivent pas dépendre d’un navigateur.

Cas d’usage visés

1. Humain en SSH sur un poste où OpenFox tourne mais sans interface graphique disponible.
2. Scripts shell / pipelines CI qui veulent créer des sessions, soumettre un brief et récupérer un résultat.
3. Agents tiers (Hermes, Orca, futurs intégrateurs) qui pilotent OpenFox sans dépendre d’un navigateur.
4. Intégration future avec Open Design : un agent de design doit pouvoir déclencher et suivre un Plan OpenFox sans manipuler l’UI.

Dans tous les cas, l’exigence est la même : passer par le même moteur et la même source de vérité que l’interface web, pas par un chemin différent.

Principes proposés (à discuter)

• Client mince du serveur OpenFox. La CLI est un consommateur de l’API serveur existante ; elle ne réimplémente pas la logique métier.
• Jamais d’accès direct à SQLite. Toute lecture/écriture passe par le serveur, comme pour la GUI.
• Entrées depuis stdin ou fichiers. Les prompts, critères et configurations peuvent être passés en argument, via stdin ou depuis un fichier, pour faciliter les scripts.
• Sortie JSON versionnée + JSONL pour les événements. La CLI expose un état structuré consommable par des programmes, et un flux d’événements ligne par ligne pour le suivi.
• Codes de sortie documentés. Au minimum : succès, erreur d’utilisation, erreur serveur, action refusée (validation/sécurité), action nécessitant confirmation explicite.
• Lecture et mutation séparées. Les commandes de lecture ne mutent jamais l’état ; les commandes de mutation sont explicites (verbe clair, --dry-run quand c’est pertinent).
• Sécurité et confirmations conservées. Les confirmations de l’UI (critères sensibles, actions destructives, approbations de plan) doivent exister côté CLI sous une forme structurée, jamais contournée par défaut.

Exemples de commandes (indicatifs, non contractuels)

Les noms ci-dessous sont des pistes pour ouvrir la discussion, pas une spec :

• openfox project list
• openfox project show <project-id>
• openfox session list --project <project-id>
• openfox session create --project <project-id> --prompt @brief.md
• openfox session send <session-id> --prompt @message.md
• openfox session status <session-id> --format json
• openfox session follow <session-id> --events jsonl
• openfox session answer <session-id> --question <id> --choice <id>
• openfox session confirm <session-id> --action <id> --yes
• openfox session approve-plan <session-id> --plan <plan-id>
• openfox session stop <session-id>

Ces commandes couvrent les grandes familles : projets, sessions, prompts, état, événements, questions structurées, confirmations, approbation de plan, arrêt.

MVP proposé (à arbitrer avec les mainteneurs)

Un premier palier utile pourrait se limiter à :

1. Découverte du serveur et authentification.
2. Lecture des projets et des sessions.
3. Création d’une session et envoi d’un prompt.
4. Lecture d’un état JSON (status, phase, dernière activité, dernier progrès).
5. Suivi d’événements structuré (au moins JSONL).
6. Réponse structurée aux questions / confirmations émises par le serveur.
7. Tests de cohérence GUI/CLI : mêmes opérations, mêmes résultats observables, mêmes garde-fous.

Si ce MVP est jugé trop large, une option encore plus réduite pourrait être : discovery + auth + lecture sessions + suivi d’événements, sans mutation à ce stade.

Hors périmètre initial (à confirmer)

• Un second moteur terminal ou une ré-implémentation de la boucle agent.
• Reproduction de l’ensemble de l’UI dans le terminal.
• Tout contournement des validations de sécurité de la GUI.
• Une orchestration externe qui deviendrait à son tour source de vérité.

Questions ouvertes aux mainteneurs

• Quelle est la frontière publique que vous envisagez : REST + WebSocket, ou une bibliothèque interne ré-utilisable par la CLI ?
• Quel est, selon vous, le plus petit MVP acceptable pour que la CLI soit utile sans devenir un projet en soi ?
• Conventions CLI préférées : sous-commandes à la git, à la gh, autre ?
• Comment exposer proprement les questions, confirmations et approbations de plan sans les transformer en simple « yes --force destructeur » ?

Références

• Discussion code-review-graph save 93x tokens per session #179 : retours d’expérience sur la réduction de tokens en revue de code, qui motive une interface plus scriptable.
• Discussion open design integration #198 : idée d’intégration Open Design comme checkpoint du mode Plan, qui suppose un pilotage non-UI d’OpenFox.

Issue associée Watchdog

Issue associée Watchdog : #200.

[bravo-delta]

I like to extend this feature request with simple cli commands to let OpenFox work on a prompt without user interaction, for example as part of a github action.

The cli should allow the user to specify:

• global instructions
• prompt (as a parameter and as a second option via an input stream for lengthy messages)
• the agent and model to use
• the acceptance criteria to fulfill the request
• enable dangerous mode (no questions)

Finally it should respond with a message.

This would allow OpenFox to handle these requests:

• Review the latest push to a repository
• Research background information for a bug report
• Implement the requested changes from a ticket and send a new pull request

OpenCode allows this with its run command, these Options are available in OpenCode:
https://opencode.ai/docs/cli/