Chaque clic dans l'interface Sharkly correspond à une décision prise par une personne : créer cette tâche, assigner cet agent, vérifier une exécution. C'est l'interface idéale pour les décisions qui demandent du jugement. C'est la mauvaise interface pour la millième répétition de la même décision. Dès que votre équipe décide que chaque build nocturne échoué doit devenir une tâche, le fait de cliquer dans des écrans cesse d'être un workflow pour devenir une corvée.
C'est là qu'intervient la surface programmatique. Le CLI Sharkly permet aux personnes, aux agents et aux scripts de travailler avec Sharkly depuis un terminal : gérer les ressources de l'organisation, enregistrer un ordinateur pour l'exécution par les agents, inspecter le service local et automatiser les workflows répétitifs. Derrière, une API REST accessible à api.sharkly.ai accepte les mêmes jetons d'accès personnels que ceux utilisés par le CLI.
Cela compte davantage pour Sharkly que pour un outil de gestion de projet classique, car Sharkly n'est pas seulement l'endroit où l'on décrit le travail. C'est l'endroit où il s'exécute. Sharkly ajoute une couche partagée de tâches, d'ordinateurs, de contexte, de contrôle et de revue autour d'outils de codage comme Claude Code et Codex. Un sharkly task create scripté ne se contente donc pas de créer un ticket. Si la tâche est assignée à un agent et se trouve dans un statut prêt, elle peut lancer une véritable exécution sur une véritable machine. Scripter cette surface, c'est scripter votre main-d'œuvre.
TL;DR
Le CLI Sharkly (commande sharkly) permet aux personnes, aux agents et aux scripts de travailler avec Sharkly depuis un terminal. C'est aussi par ce biais que le service local s'installe sur les hôtes distants et les machines Linux, afin qu'ils rejoignent votre parc en tant qu'ordinateurs. L'authentification est volontairement scindée : un jeton d'accès personnel (préfixe shk_) connecte une personne ou un script, un jeton d'installation à usage unique (préfixe sit_) enregistre un ordinateur, et les exécutions d'agents utilisent un identifiant d'exécution à portée limitée fourni par Sharkly. Une fois le jeton en place, les scripts peuvent créer et modifier des tâches, y ajouter des commentaires, inspecter les exécutions et les journaux, et gérer les ordinateurs, le tout avec --output json pour un parsing propre. Le même jeton shk_ fonctionne comme bearer token sur l'API REST, et les déclencheurs webhook des automatisations permettent à la CI et à d'autres systèmes externes de lancer des exécutions d'agents avec une requête POST.
Une plateforme, deux surfaces
L'interface de Sharkly et sa surface programmatique sont deux portes d'entrée vers le même système. La tâche créée par votre script est celle que voit votre collègue sur le tableau, avec le même statut, le même workflow, les mêmes commentaires et le même historique d'exécution. L'automatisation ne contourne jamais l'enregistrement partagé : elle l'alimente.
Une bonne façon de distinguer les deux est de se demander qui décide. Utilisez l'interface lorsqu'une personne porte un jugement : formuler un besoin, relire un diff, valider un résultat. Utilisez le CLI ou l'API lorsque la décision est déjà prise et que seuls les gestes se répètent : créer des tâches depuis un système de supervision, remonter les journaux d'exécution dans un tableau de bord, vérifier l'état des ordinateurs depuis une tâche cron. Un script peut créer la tâche et même déclencher l'exécution, mais la validation reste humaine.
Installer le CLI, et ce qu'il installe
Sous macOS ou Linux, l'installateur officiel tient en une seule commande :
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Windows dispose d'un installateur PowerShell officiel, actuellement limité à AMD64. Quelle que soit la plateforme, vérifiez et maintenez l'installation avec :
sharkly version
sharkly update
Le CLI joue un second rôle, au-delà de celui de client. La documentation décrit deux façons de connecter un ordinateur : installer Sharkly Desktop sur un ordinateur personnel pris en charge, ou installer le CLI Sharkly et le service local sur un hôte distant ou une machine Linux. Cette seconde voie permet à un serveur de build, à une machine Linux inutilisée ou à un conteneur de devenir de la capacité d'exécution pour vos agents. Le service local ainsi installé enregistre l'ordinateur, détecte les runtimes installés, envoie des heartbeats, reçoit les exécutions mises en file d'attente, prépare les répertoires de tâches et renvoie la progression en continu, en initiant lui-même la connexion : aucun port entrant n'est nécessaire.
Si vous en êtes encore à connecter votre première machine via l'interface, le guide de démarrage couvre ce parcours.
Trois identifiants, trois rôles
Sharkly utilise des identifiants distincts pour des usages distincts, et cette séparation mérite d'être bien assimilée avant d'automatiser quoi que ce soit.
Un jeton d'accès personnel commence par shk_ et permet au CLI, à un script ou à un autre client de confiance d'agir en tant que votre compte utilisateur. Vous en créez un dans les Paramètres, choisissez une expiration de 30 jours, 90 jours, 1 an ou aucune expiration, et copiez la valeur complète au moment de la création. Connectez-vous avec le flux interactif pour que le jeton n'atterrisse jamais dans l'historique du shell :
sharkly login --token
sharkly auth status
Un jeton d'installation d'ordinateur commence par sit_, expire au bout de 30 minutes et ne peut être utilisé qu'une seule fois. Sa seule fonction est d'enregistrer un ordinateur :
sharkly computer register --install-token sit_...
Le troisième identifiant, vous ne le manipulez jamais : une exécution d'agent active reçoit un identifiant d'exécution à portée limitée fourni par Sharkly, restreint aux familles de commandes autorisées par son contexte d'exécution.
La documentation trace clairement la frontière : un jeton d'accès personnel n'enregistre pas d'ordinateur, et un jeton d'installation ne crée pas de connexion humaine au CLI. L'enregistrement crée une session indépendante pour le service local ; c'est pourquoi révoquer plus tard votre jeton personnel ne met pas hors ligne les ordinateurs que vous avez enregistrés. De même, sharkly auth logout ne fait que supprimer le jeton de votre profil local ; le jeton reste valide côté serveur jusqu'à ce que vous le révoquiez dans les Paramètres.
En CI, passez complètement le flux de connexion. Le CLI lit le jeton dans la variable d'environnement SHARKLY_TOKEN, qui a la priorité sur tout profil enregistré. Alimentez-la depuis un coffre de secrets protégé, comme les secrets GitHub Actions, plutôt que d'écrire le jeton dans le fichier de workflow, et précisez explicitement l'organisation avec --organization-id.
Gérer un parc d'ordinateurs depuis le terminal
Une fois les hôtes enregistrés, le groupe de commandes sharkly computer couvre l'inspection et la maintenance sans passer par un navigateur :
sharkly computer list --output json
sharkly computer show <computer-id> --output json
sharkly computer usage <computer-id> <runtime-id> --days 30 --output json
sharkly computer ping <computer-id> <runtime-id> --wait --output json
sharkly computer update <computer-id> <runtime-id>
list affiche les ordinateurs enregistrés pour l'organisation courante, show renvoie un ordinateur avec ses runtimes, usage inspecte un runtime précis, ping vérifie si ce runtime peut effectuer un aller-retour, et update demande une mise à jour du CLI pour un runtime. La nuance que ping permet de saisir : un ordinateur en ligne signifie seulement que son service local envoie des heartbeats, pas qu'un runtime donné est capable de lancer une exécution à cet instant précis.
Sur l'hôte lui-même, le diagnostic courant passe par les commandes destinées aux utilisateurs :
sharkly computer status --output json
sharkly computer logs --lines 100
L'espace de noms daemon expose le cycle de vie des processus et le contrôle du disque, avec notamment sharkly daemon disk-usage et sharkly daemon cleanup, qui s'exécute en simulation (dry run) sauf si vous ajoutez --confirm. La règle de décision de la documentation : privilégiez computer status et computer logs pour le diagnostic courant, et ne recourez à daemon que si vous avez besoin du cycle de vie des processus, d'un état du disque ou d'un nettoyage. L'article sur les ordinateurs de cette série approfondit les politiques de propriété, de visibilité et de nettoyage.
Scripter les tâches : du travail qui arrive sans réunion
Les tâches sont ce qui légitime le CLI dans un pipeline. Cette famille de commandes ressemble à une version scriptable du tableau :
sharkly task list --output json
sharkly task search "authentication error" --output json
sharkly task create --title "Investigate authentication error" --output json
sharkly task edit <task-id> --status <status> --output json
sharkly task comment <task-id> --body "Investigation started." --output json
Le cas d'usage CI évident, c'est la création automatique de travail. Une tâche nocturne qui détecte une release échouée n'a pas besoin qu'une personne remplisse un formulaire :
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
Utilisez --body-file ou --body-stdin dès que le contenu exact compte, car la forme courte --body décode les séquences d'échappement. Et comme une tâche assignée à un agent lance une exécution lorsqu'elle se trouve dans un statut prêt, cette seule commande peut amorcer une boucle entièrement automatisée : le script crée la tâche, l'agent assigné la prend en charge, puis l'exécution, les blocages et le résultat reviennent dans la tâche, où une personne les examine le lendemain matin.
Les scripts de reporting disposent de vrais filtres plutôt que d'un tri côté client. Vous pouvez filtrer selon l'ancienneté du statut avec --status-changed-within 7d, et selon les champs personnalisés :
sharkly task list --space HF --field "Customer Tier=VIP" --output json
Les options --field répétées sont combinées par un ET logique, la correspondance tient compte du type et est exacte, et le filtrage s'effectue côté serveur avant la pagination. Adoptez sans réserve les conventions de scripting de la documentation : demandez explicitement --output json, ajoutez --color never et --quiet, laissez --organization-id visible et utilisez set -euo pipefail. Les codes de sortie sont contractuels : 0 pour un succès, 1 pour une erreur de commande, de validation, d'authentification ou d'API distante, et 2 pour une condition transitoire du service local ou du réseau, ce qui simplifie la logique de nouvelle tentative.
Le CLI est aussi auto-descriptif. sharkly schema task create --format json expose le registre des commandes dans un format lisible par une machine, et sharkly tldr task met en avant des scénarios sélectionnés — ce qui compte lorsque ce qui écrit le script est lui-même un agent.
Suivre les exécutions sans ouvrir de tableau de bord
Les exécutions sont observables via la même surface :
sharkly run list --task <task-id> --output json
sharkly run view <run-id> --output json
sharkly run log <run-id> --since <sequence> --output json
sharkly run cancel <run-id> --output json
L'option --since rend le polling raisonnable : un script de supervision mémorise le dernier numéro de séquence traité et ne récupère que les messages plus récents à chaque passage. Combinez-la avec sharkly agent list, sharkly automation view et sharkly automation runs pour construire une page de statut de votre flotte d'agents à partir d'un script shell et de jq.
L'API REST et les webhooks
Tout ce que fait le CLI repose sur l'API REST, et la documentation montre la voie directe : envoyer son jeton d'accès personnel comme bearer token via HTTPS.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
L'accès via l'API est limité par les permissions de l'utilisateur associé au jeton ; le modèle de jeton actuel ne permet pas de choisir des portées par jeton, ce qui incite à créer un jeton distinct pour chaque service, avec une expiration définie. La référence des endpoints se trouve sur docs.sharkly.ai, et les réponses --output json du CLI donnent un aperçu fidèle des structures que vous manipulerez.
Le trafic circule aussi dans l'autre sens. Une automatisation peut porter un déclencheur webhook : Sharkly génère une URL secrète qui accepte une requête POST, et une requête valide lance l'exécution de l'agent ou de la Crew associée à l'automatisation. L'URL complète n'est affichée qu'une seule fois et fait office de secret bearer par défaut, avec une vérification de signature en option. C'est la moitié entrante de l'histoire CI : votre pipeline annonce à Sharkly « il s'est passé quelque chose, lance l'agent de triage ».
Il vaut la peine de préciser ce que cette surface n'est pas. Le CLI Sharkly n'est pas un agent de codage de plus, et l'API n'est pas un endpoint de modèle. Des runtimes comme Claude Code et Codex assurent l'exécution ; la surface programmatique de Sharkly gère la couche qui les entoure. Cette neutralité la distingue d'options liées à un écosystème comme GitHub Agent HQ, où la surface d'automatisation et l'exécution vivent à l'intérieur des murs d'un même fournisseur.
Par où commencer
Commencez plus petit que vous ne l'imaginez. Créez un jeton d'accès personnel avec une expiration de 90 jours, lancez sharkly login --token et scriptez la lecture la plus ennuyeuse de votre quotidien, par exemple une liste de tâches passée dans jq pour produire un résumé matinal. Les lectures sont sans risque et vous apprennent les structures JSON. Automatisez ensuite une seule écriture avec un déclencheur évident, comme la création d'une tâche à partir d'un job CI échoué. Ne branchez un déclencheur webhook qu'une fois les deux devenus routiniers.
Le schéma à préserver est celui sur lequel repose toute la plateforme : les scripts et les agents génèrent et exécutent le travail, tandis que le contexte, la progression, les blocages, les résultats et la revue humaine restent visibles de la demande à la livraison. Automatisez les entrées. Gardez la revue.
FAQ
Faut-il le CLI pour utiliser Sharkly ?
Non. Sharkly Desktop couvre la connexion d'un ordinateur personnel, et l'application web couvre le travail quotidien sur les tâches. Le CLI devient nécessaire lorsque vous connectez un hôte distant ou une machine Linux, car l'installation du CLI Sharkly et du service local est la procédure documentée dans ce cas. Il devient précieux dès qu'un workflow se répète assez souvent pour que le parcours manuel dans l'interface représente un coût.
Quelle est la différence entre un jeton d'accès personnel et un jeton d'installation ?
Un jeton d'accès personnel (préfixe shk_) authentifie une personne ou un script en tant que votre compte utilisateur, pour les connexions au CLI, les jobs CI et les requêtes directes à l'API. Un jeton d'installation d'ordinateur (préfixe sit_) est à usage unique et de courte durée, expirant au bout de 30 minutes, et sert uniquement à enregistrer un ordinateur. Ni l'un ni l'autre ne remplace l'autre.
Puis-je appeler directement l'API REST de Sharkly au lieu d'utiliser le CLI ?
Oui. Envoyez un jeton d'accès personnel comme bearer token via HTTPS à api.sharkly.ai ; la documentation donne comme modèle curl -fsS https://api.sharkly.ai/rest/v1/users/current avec un en-tête Authorization: Bearer. Le jeton hérite des permissions de votre compte utilisateur.
Comment créer une tâche depuis un pipeline CI ?
Stockez un jeton shk_ comme secret CI protégé et exposez-le via la variable d'environnement SHARKLY_TOKEN, que le CLI lit automatiquement. Lancez ensuite sharkly task create avec --title, --body-file pour un contenu multiligne exact, un --organization-id explicite et --output json, afin que le job puisse récupérer l'ID de la tâche créée.
La révocation de mon jeton d'accès personnel arrête-t-elle mes ordinateurs enregistrés ?
Non. L'enregistrement d'un ordinateur crée une session de service local indépendante via le jeton d'installation ; révoquer un jeton d'accès personnel n'arrête donc pas ces ordinateurs. La révocation invalide en revanche le jeton partout où il sert aux requêtes CLI, API et d'automatisation ; c'est pourquoi une rotation doit mettre à jour les scripts dépendants avant que l'ancien jeton ne soit révoqué.
