CLI d'agent de code

Utilisez la CLI BernOps pour connecter cet ordinateur à l'application et exécuter des sessions de codage appartenant au créateur avec l'agent Pi intégré. Un hôte personnel d'agent de code est distinct d'un worker d'exécution d'espace de travail.

Démarrage rapide

La distribution reste privée : aucune URL de téléchargement publique, commande curl | sh ou installation npm n'est prise en charge. Obtenez l'archive complète du bootstrap approuvé auprès de votre opérateur et authentifiez sa somme de contrôle et sa provenance par un canal de confiance avant extraction ou exécution. Une somme de contrôle fournie avec un téléchargement non fiable ne suffit pas.

Après obtention et extraction approuvées, lancez l'installateur inclus avec votre utilisateur habituel, sans sudo. Remplacez le chemin d'exemple par celui de l'extraction vérifiée :

/absolute/verified/bootstrap-linux-x64/install.sh
export PATH="$HOME/.local/bin:$PATH"
bernops --version

Le bootstrap inclut Node 22.19.0 épinglé ; les utilisateurs finaux n'installent ni Node ni NVM et ne compilent pas la CLI. Le périmètre visé est Ubuntu/Debian x86-64 ; la qualification sur OS neuf avec ou sans bureau et en production cloud reste incomplète. L'opérateur doit configurer des versions de composants signées et approuvées. L'authentification seule ne nécessite ni Pi, ni Docker, ni moteur worker.

Depuis le repository Git à autoriser, lancez :

bernops setup

1. Choisissez 2 (agent de code) ou 4 (les deux), pas l'authentification seule proposée par défaut. Sélectionnez la racine Git courante affichée ou saisissez une autre racine Git absolue. Le nom du repository est généré automatiquement, sans invite de nommage. La détection seule n'accorde aucun accès.
2. Effectuez la connexion plateforme, puis approuvez séparément l'hôte personnel lié. Si les deux composants sont sélectionnés, l'approbation du worker pour son espace est encore une autorisation indépendante.
3. L'assistant installe le composant agent privé signé, gère la connexion OpenAI Codex si les identifiants locaux sont absents, puis configure l'accès au repository et le service utilisateur. Les identifiants fournisseur compatibles sont réutilisés. Aucune commande préalable auth login, de connexion fournisseur ou de mise à niveau n'est nécessaire.
4. Attendez que les composants sélectionnés indiquent ready. L'agent doit disposer d'un repository accessible, d'identifiants fournisseur, d'un service utilisateur actif et d'une connexion hôte authentifiée observée, pas seulement d'un processus actif. Aucune requête modèle facturable ne valide le fournisseur.

Pour le développement depuis le checkout BernOps approuvé avec la pile locale :

./dev.sh install-cli
bernops setup

./dev.sh install-cli prépare les versions locales signées et active le bootstrap privé à cible locale sans redémarrer la pile. Il peut utiliser un Node 22.19.0 déjà installé via NVM, mais n'installe jamais NVM ni Node. La préparation des versions exige des prérequis de build développeur ; ce n'est pas le parcours d'installation utilisateur. Le backend local doit fonctionner avec son catalogue de versions configuré.

L'assistant utilise la cible explicite si fournie ; sinon il consulte l'identité utilisateur enregistrée, puis son journal, puis la cible compilée du bootstrap. Les bootstraps locaux choisissent local par défaut ; les builds généraux choisissent cloud, sans annoncer de version publique. bernops setup --target local permet un choix local explicite. Un conflit de cible échoue au lieu de migrer les identités ; consulter ces docs localement ne choisit pas la cible de la CLI.

Pour choisir explicitement plutôt que via le menu interactif :

bernops setup --components agent --repo /home/user/code/project

--repo <directory> sélectionne une racine Git absolue sans option de nommage. Sans TTY, y compris en mode JSON, --components est obligatoire : auth, agent, worker ou agent,worker. Ne combinez pas auth avec les autres noms ; l'authentification est déjà partagée. Les options explicites ne suppriment ni les approbations ni les interactions fournisseur.

Pi est le moteur intégré. Ne fournissez pas --runtime, --backend ou --app : ce ne sont pas des options publiques d'onboarding.

Sortie lisible et JSON

Un terminal interactif affiche des résultats lisibles et concis. Les commandes redirigées conservent le format JSON compact et stable pour les scripts. Utilisez l'option globale --json avant la commande pour forcer ce format, ou --debug pour ajouter des détails techniques expurgés à la sortie interactive :

bernops --json workspace list
bernops --debug status

Les options globales de sortie doivent précéder la commande. La combinaison de --json et --debug produit uniquement l'enveloppe JSON normale, sans flux supplémentaire susceptible de casser l'analyse. Le mode debug n'ajoute jamais de jetons OAuth, de clés API de projet, de secrets de jumelage, de corps de requête ou d'erreurs brutes inconnues. Les vues humaine et debug masquent les jetons de bail renvoyés ; les automatisations de réclamation qui en ont besoin doivent utiliser --json. bernops service logs reste un flux de journaux non formaté.

Connexion utilisateur et stockage des identifiants

bernops auth login
bernops auth login --target local
bernops auth status

Ce sont des alternatives d'authentification seule, pas des prérequis de configuration. bernops auth login crée ou réutilise uniquement la session utilisateur plateforme : cette commande n'inscrit pas d'hôte, ne connecte pas Codex, n'enregistre pas de repository et ne démarre ni service ni worker. bernops setup --components auth offre le même choix léger via l'assistant ; fournissez --target local ou --target cloud pour choisir explicitement une cible d'authentification.

Linux Secret Service est le stockage par défaut des identifiants plateforme en local comme dans le cloud. Il exige secret-tool, gdbus et un Secret Service déverrouillé dans la session D-Bus de l'utilisateur réel. Les jetons d'accès restent en mémoire. Aucun repli automatique en clair n'existe. Pour une nouvelle identité, --credential-store file ou le choix explicite BERNOPS_AUTH_STORE=file accepte un fichier d'identifiants de renouvellement réservé au propriétaire mais non chiffré. Les identités enregistrées gardent leur stockage ; cette option ne le migre pas. Réparez un stockage natif verrouillé, refusé ou indisponible plutôt que de le dégrader.

Les commandes d'espace de travail, projet, job, file, exécution et découverte utilisent cette session OAuth. bernops app reste explicitement authentifié par une clé API de projet ; aucun principal ne se rabat silencieusement sur l'autre.

Connexion au fournisseur

Le choix agent dans bernops setup gère déjà la connexion OpenAI Codex si nécessaire via l'infrastructure fournisseur Pi épinglée. L'onboarding unifié ne prend actuellement en charge que openai-codex ; l'authentification seule et le worker seul ne configurent aucun fournisseur. Pour inspecter ou renouveler délibérément la connexion fournisseur d'un agent installé :

bernops provider login openai-codex
bernops provider status

Suivez les instructions de connexion affichées par le fournisseur. --no-browser ne garantit pas une connexion fournisseur non interactive ; sans TTY, le résultat peut être provider_login_interactive_required. Les identifiants restent dans ~/.pi/agent/auth.json et ne sont jamais envoyés au backend BernOps.

bernops provider logout openai-codex

Enregistrer les repositories

L'assistant peut enregistrer un repository avec votre accord. Seuls les checkouts explicitement enregistrés peuvent être sélectionnés dans BernOps. Pour ajouter une autre racine Git ensuite, lancez depuis cette racine :

bernops repo add "$PWD"
bernops repo list

Les deux commandes d'enregistrement nomment automatiquement les repositories à partir du dernier segment du chemin du repository Git origin. Les origines HTTPS (https://github.com/owner/project.git), URL SSH (ssh://[email protected]/owner/project.git) et de type scp ([email protected]:owner/project.git) donnent toutes project, après suppression du suffixe .git. Si aucun nom d'origine exploitable n'est disponible, le nom du dossier canonique du checkout est utilisé. Aucune invite de nommage ni option de personnalisation d'alias ou de libellé n'est proposée.

L'option facultative bernops repo add <directory> --remote owner/name fournit uniquement les métadonnées distantes sûres existantes ; elle ne remplace pas le nom généré. Les champs du protocole et du stockage alias et display_name restent inchangés. L'application reçoit les métadonnées sûres du repository et sa disponibilité, pas le chemin canonique de l'hôte. Conserver l'accès existant n'ajoute aucun accès au dossier courant ni au dossier personnel. Sans repository enregistré disponible, l'agent signale qu'une intervention est nécessaire, pas un état prêt. L'enregistrement n'est pas un bac à sable système : l'agent personnel hérite des permissions de votre utilisateur.

Service en arrière-plan et usage sans bureau

La configuration unifiée de l'agent exige un utilisateur habituel non root et un gestionnaire systemd utilisateur fonctionnel. Elle installe le service s'il est absent, le démarre s'il est arrêté et préserve un service actif vérifié. L'absence de gestionnaire ou du linger requis nécessite une intervention, pas un repli au premier plan. Demandez à l'administrateur de vérifier la configuration D-Bus/session ; l'assistant n'installe jamais de paquets système et ne modifie aucun paramètre privilégié.

La préparation du service agent exécute encore npm ci avec npm inclus et exige l'accès au registre de dépendances. La livraison d'une archive signée ne permet pas d'installer le service hors ligne.

bernops service status
bernops service logs --lines 200

Pour des approbations distantes et un agent qui doit rester disponible après fermeture de session :

bernops setup --components agent --repo /home/user/code/project \
  --no-browser --headless

--no-browser supprime l'ouverture du navigateur, pas le consentement. Laissez la CLI interroger le backend, ouvrez chaque URL affichée sur un autre appareil, comparez le code humain et le compte connecté, puis vérifiez l'empreinte de l'hôte avant d'approuver. L'approbation plateforme utilise un relais Authorization Code + PKCE, pas un flux OAuth de code d'appareil. Gardez les URL et codes d'approbation privés.

--headless est réservé à l'agent et exige que loginctl show-user "$UID" --property=Linger --value indique yes. Un administrateur peut examiner l'activation du linger pour cet utilisateur ; l'assistant ne l'active jamais. Headless n'implique pas le stockage fichier : utilisez le stockage natif disponible, ou ajoutez délibérément --credential-store file pour une nouvelle identité si vous acceptez un stockage non chiffré.

La commande avancée bernops --foreground reste disponible pour exécuter délibérément un agent installé au premier plan. Ce n'est pas le parcours de configuration unifiée et elle ne satisfait pas ses contrôles de disponibilité du service en arrière-plan.

Mettre à niveau

Relancez bernops setup avec la même cible et les mêmes choix pour reprendre ou vérifier la disponibilité. Désélectionner un composant ne le désinstalle jamais. L'assistant interactif demande confirmation avant de sélectionner une nouvelle version signée de l'agent ou d'actualiser un service éligible sans travail en cours qui ne prend pas en charge le statut de connexion. En cas de refus, de travail en cours ou d'échec de vérification, l'état est préservé et une intervention est signalée comme nécessaire ; aucune mise à niveau manuelle n'est requise dans le parcours interactif normal.

Pour des opérations délibérées sur le cycle de vie du service d'un agent installé :

bernops service upgrade
bernops service rollback

Ces opérations redémarrent délibérément le service avec des versions vérifiées et un état de retour arrière conservé. Elles ne mettent pas à jour le bootstrap et ne migrent ni comptes, ni cibles, ni origines. Ne supprimez et ne modifiez pas les reçus de version ni installation.json pour forcer une mise à niveau.

Pour supprimer délibérément seulement le service, puis laisser la configuration agent le réinstaller :

bernops service uninstall
bernops setup --components agent

La désinstallation du service conserve l'identité hôte, les repositories, les identifiants Pi, les versions et les données de session. L'installateur privé du bootstrap ne se met pas à jour lui-même et refuse une commande existante ; demandez à l'opérateur de vérifier tout remplacement. Depuis un checkout de développement, ./dev.sh install-cli peut activer un bootstrap local vérifié en conservant les éléments de récupération.

Raccourcis de commandes

Choisissez la commande adaptée à votre intention ; cette liste n'est pas une séquence à exécuter. Logout et disconnect sont des nettoyages délibérés, pas des prérequis de configuration.

bernops setup
bernops setup --target local
bernops setup --local
bernops setup --components auth
bernops setup --components agent,worker
bernops auth login
bernops auth login --target local
bernops auth login --credential-store file
bernops auth status
bernops auth logout
bernops auth logout --local-only
bernops logout
bernops disconnect --everything
bernops status
bernops doctor
bernops provider login openai-codex
bernops provider status
bernops repo add <directory>
bernops repo list
bernops service status
bernops service restart
bernops credential rotate

Recherchez la documentation publique actuelle sans connexion, configuration de fournisseur ni installation du composant d'agent de code :

bernops docs search "worker setup"
bernops --json docs search "work item claims" --limit 10
bernops docs search "variables" --locale fr
bernops docs get coding-agent-cli#command-reference

La CLI récupère un index compact depuis https://bernops.com en HTTPS et renvoie les liens des sections pertinentes avec de courts extraits. Elle ne télécharge pas toutes les pages et ne transmet pas votre recherche à un fournisseur de recherche. Les docs publiques décrivent leur révision actuelle ; consultez l'aide --help installée pour les commandes prises en charge par une ancienne CLI.

Pour la découverte d'opérations, les lectures compactes gérées, les ETags sûrs et la planification roadmap atomique sur les versions compatibles, consultez Utilisation efficace des outils agent. Les références publiques ne garantissent pas que ces opérations sont disponibles dans votre backend déployé ou hôte installé.

Choisir la bonne déconnexion

• bernops auth logout révoque la session CLI distante de cette installation, puis efface l'état OAuth local.
• bernops auth logout --local-only efface uniquement l'identifiant OAuth local.
• bernops logout supprime de façon destructive l'identité hôte locale, sa file d'envoi et son service, pas l'autorisation hôte distante. Ce n'est pas une réparation de verrou ou de réinitialisation.
• bernops provider logout supprime uniquement l'identifiant du fournisseur sélectionné.
• bernops disconnect --everything nettoie localement l'authentification, l'hôte et le service, ainsi que les identifiants du seul fournisseur par défaut OpenAI Codex, pas ceux de tous les fournisseurs enregistrés. Il ne supprime ni ne désinstalle les workers et n'effectue aucune révocation distante ; le résultat indique remote_revoked:false.

La déconnexion plateforme ne supprime pas les accès hôte, fournisseur ou worker. La déconnexion du navigateur, la révocation globale du client, la révocation serveur de l'hôte, la révocation d'une clé API de projet et la suppression d'une session restent distinctes. Les commandes de lecture/nettoyage comme status, doctor, service stop|logs|status|uninstall, repo list et provider status|logout peuvent utiliser le moteur installé signé et vérifié sans connexion plateforme ni accès aux versions en ligne. Ce n'est pas un contournement pour installer ou exécuter hors ligne.

Dépannage

• backend_unreachable : depuis le même espace réseau, vérifiez http://127.0.0.1:3410/health avec --target local.
• Aucun navigateur : ajoutez --no-browser et utilisez l'URL de vérification affichée pendant que la CLI continue d'interroger le backend.
• Coffre natif indisponible ou verrouillé : restaurez le trousseau ou la session. Le stockage fichier exige un accord explicite pour une nouvelle identité et ne migre pas une session native enregistrée.
• Compte incompatible : terminez avec le compte propriétaire de l'hôte proposé, ou annulez et créez une nouvelle transaction. BernOps ne transfère jamais l'hôte.
• Aucun modèle : lancez bernops provider status, puis connectez le fournisseur requis.
• Aucun gestionnaire systemd utilisateur ou linger headless absent : demandez à l'administrateur de fournir les prérequis, puis relancez l'assistant. Aucun repli automatique au premier plan n'existe.
• Base réinitialisée ou ancien hôte local confirmé : relancez bernops setup avec la même cible et les mêmes choix. Examinez Reconnect this PC? si proposé. Un accord explicite peut archiver les anciennes sessions locales et obtenir une nouvelle approbation hôte tout en conservant la connexion fournisseur et l'accès aux repositories. Ne supprimez pas l'état et n'utilisez pas logout comme réparation universelle.
• component_release_trust_unconfigured ou component_releases_not_configured : demandez à l'opérateur un bootstrap approuvé et un catalogue signé. Ne contournez pas les signatures et n'installez pas de substituts publics.
• Configuration interrompue : arrêtez les opérations concurrentes, confirmez la fin du processus initial, puis reprenez les mêmes choix. Les verrous sécurisés peuvent récupérer un propriétaire obsolète vérifié ; un verrou actif ou dangereux exige une investigation, pas une suppression aveugle.

Le résumé indique ready, needs_attention, failed ou not_selected par composant. Le code de sortie 0 signifie que tous les composants sélectionnés sont prêts, 2 indique qu'une intervention est nécessaire et 1 un échec. Les composants terminés restent intacts si un autre échoue.

Consultez docs/unified-onboarding.md et cli/README.md dans le repository pour le contrat complet, les conditions de publication et les procédures de récupération opérateur.