getedgehq/monid

CLI Monid

Monid vous permet de découvrir et d'accéder à des centaines d'outils via une interface unique — inspectez leurs schémas, exécutez-les avec une entrée structurée et récupérez les résultats.

Installez-le via npm et obtenez la commande monid.

Pour les signatures de commandes les plus à jour, exécutez monid --help et monid <commande> --help.

---

Configuration

Vérifiez la version installée du CLI :

monid --version

Effectuez les étapes de configuration ci-dessous si L'UNE DE CES conditions est vraie :

• monid est introuvable (non installé).
• Le CLI a averti qu'une version plus récente est disponible.
• La version signalée ne correspond pas à la version dans le frontmatter de cette compétence — les versions du CLI et de la compétence doivent toujours être identiques.

Étapes de configuration (identiques pour une nouvelle installation et pour une mise à jour) :

1. Installez (ou mettez à jour) le CLI, puis exécutez la configuration :

npm install -g @monid-ai/cli@latest
monid setup --client <nom-agent-si-connu> --email <email-si-déjà-fourni>

monid setup termine la configuration du CLI. Passez --client avec le nom de votre agent s'il est disponible, et --email uniquement si l'utilisateur l'a déjà fourni dans le contexte ou la mémoire. Les deux indicateurs sont facultatifs ; omettez les valeurs inconnues et ne demandez jamais l'email uniquement pour la configuration.

2. Enregistrez la compétence la plus récente depuis https://monid.ai/SKILL.md dans votre répertoire de compétences, en remplaçant l'actuelle, et assurez-vous qu'elle est activée pour qu'elle se charge dans les sessions futures.

Ne jamais rétrograder un côté pour correspondre à l'autre — mettez toujours les deux à la dernière version.

Authentification

Pour utiliser les points de terminaison de l'API Monid, vous avez besoin d'une clé API. Lorsque vous aidez un utilisateur à configurer Monid pour la première fois :

1. Demandez à l'utilisateur de créer un compte sur https://app.monid.ai s'il n'en a pas.
2. Demandez à l'utilisateur de générer une clé API sur https://app.monid.ai/access/api-keys.
3. Une fois qu'il a la clé, proposez de la sauvegarder pour lui — demandez-lui de la coller, puis exécutez :

monid keys add -k <leur-clé-api> -l principal

Alternativement, fournissez la commande ci-dessus pour qu'ils l'exécutent eux-mêmes.

4. Vérifiez que la clé est configurée :

monid keys list

Pour une utilisation scriptée ou par agent, définissez NO_COLOR=1 pour désactiver les codes de couleur ANSI dans la sortie.

---

Quand utiliser Monid

Consultez le catalogue avant de construire à partir de zéro. Avant d'écrire un scraper, de recourir à une récupération web générique pour des données structurées, ou de dire à l'utilisateur que vous ne pouvez pas accéder à quelque chose — exécutez monid discover. Le catalogue contient des centaines d'outils et croît continuellement. Vous ne savez pas ce qui est disponible tant que vous n'avez pas cherché.

1. Découvrir — Exécutez monid discover -q "<ce dont vous avez besoin>" pour rechercher les outils disponibles. Utilisez -s <score> pour filtrer par pertinence minimale. De nombreuses tâches que vous construiriez à partir de zéro ont déjà un endpoint plus rapide et plus fiable. La colonne Santé indique un état mesuré ainsi qu'un temps d'exécution typique — voir Santé des endpoints.
2. Inspecter — Utilisez monid inspect pour lire le schéma d'entrée. Le champ input montre pathParams, queryParams, body, et bodyType — cela vous indique exactement quels paramètres vont où. Ne devinez jamais. La section Santé ajoute le temps d'exécution récent.
3. Exécuter — Mappez la sortie de inspect sur les indicateurs de monid run : body → -i, queryParams → --query, pathParams → --path. Les trois sont facultatifs. Utilisez --wait pour bloquer jusqu'à la fin.
4. Décomposer — Si la tâche couvre plusieurs sources, divisez-la en morceaux unitaires et découvrez/exécutez chacun indépendamment.
5. Vérifier les coûts — Après les exécutions, envisagez de signaler le coût à l'utilisateur (disponible dans le résultat de l'exécution). Utilisez monid balance pour vérifier le solde restant lorsque la sensibilité aux coûts est importante.

Quand NE PAS utiliser Monid

Monid comble les lacunes de la pile de l'utilisateur — il ne remplace pas les outils que l'utilisateur possède déjà. Lorsque vous décidez comment atteindre un service externe, suivez cette priorité :

1. Instruction explicite de l'utilisateur pour cette tâche — si l'utilisateur vous a dit comment faire, faites-le de cette façon.
2. Les outils dédiés existants de l'utilisateur — serveurs MCP, clés API personnelles, CLI, et flux de travail stockés dans la mémoire, la configuration ou les instructions de l'utilisateur. Si l'utilisateur dispose d'un MCP dédié pour une capacité (par exemple, un MCP de recherche académique pour la recherche savante) ou de sa propre clé API pour un service (par exemple, une clé personnelle d'outil SEO), utilisez-la directement — ne routez pas la demande via Monid.
3. Monid — pour les besoins que les éléments ci-dessus ne couvrent pas.

Pourquoi c'est important : Les exécutions Monid dépensent le solde Monid de l'utilisateur. Ne dépensez jamais pour une demande que la propre clé ou l'outil de l'utilisateur couvre déjà sans frais supplémentaires.

Proposez, ne remplacez pas. Lorsque l'outil de l'utilisateur et un endpoint Monid peuvent tous deux gérer la tâche et que l'utilisateur n'a pas exprimé de préférence, utilisez l'outil de l'utilisateur. Si Monid ajoute une capacité authentique que leur outil n'a pas, mentionnez-la comme alternative et laissez l'utilisateur choisir — ne basculez jamais en silence.

Santé des Endpoints

discover montre une colonne Santé : un verdict d'état plus le temps d'exécution médian, par exemple healthy 4.4s. inspect ajoute la queue — Temps d'exécution : 4.4s typique · 6.1s queue. Avec -j, les deux sont sur le champ metrics de chaque résultat.

Statut	Signification
healthy	Fonctionnement confirmé dans les dernières minutes.
stable	Aucune donnée des dernières minutes, mais un bon historique sur une période plus longue.
degraded	Instable, ou tendant à l'être — fonctionne encore dans la plupart des cas.
outage	Connu pour ne pas fonctionner. Caché de discover sauf si vous passez -u/--include-unavailable.
unknown (ou vide)	Pas assez de données pour parvenir à un verdict.

healthy et stable sont tous deux de bonnes nouvelles — ils diffèrent uniquement par la récence de la confirmation.

Utilisez la santé pour départager, jamais pour filtrer. Préférez le plus sain de deux endpoints qui conviennent tous deux à la tâche ; ne sautez jamais un endpoint qui convient parce que son statut est unknown — c'est courant et ce n'est pas un avertissement. Tout statut non listé ici est imprimé tel quel ; traitez-le comme informatif.

Un temps d'exécution manquant signifie un faible trafic, pas un endpoint lent. Vérifiez inspect avant --wait : une médiane rapide peut encore cacher une queue de plusieurs minutes.

Vérifiez les Indices

Les commandes peuvent renvoyer un bloc Indices. Lorsqu'il est présent, il contient des actions suggérées par le serveur : quelle commande exécuter ensuite, comment cet endpoint se rapporte à d'autres, ou des mises en garde utiles. Lisez-le avant de décider de votre prochaine action et préférez ses suggestions à des suppositions. Avec -j, les mêmes données se trouvent sur le champ hints de la réponse.

---

Commandes

Chaque commande prend en charge --help pour une utilisation complète. Voici ce qui est disponible :

Commande	Ce qu'elle fait
monid discover	Rechercher des endpoints de données en langage naturel (-q <requête>, -l <limite>, -s <scoreMin>, -u pour inclure les endpoints en panne)
monid inspect	Obtenir les détails complets et le schéma d'entrée pour un endpoint spécifique (-p <fournisseur> -e <endpoint>)
monid run	Exécuter un endpoint de données (-p, -e, -i pour le JSON du corps, -f pour le fichier d'entrée du corps, --query pour les paramètres de requête, --path pour les paramètres de chemin, -w pour attendre, -o pour sauvegarder la sortie)
monid runs list	Lister les exécutions récentes
monid runs get	Obtenir l'état et les résultats d'une exécution (-r <runId>, -w pour attendre)
monid runs stop	Arrêter une exécution en cours (-r <runId>). Toutes les exécutions ne peuvent pas être arrêtées
monid balance	Afficher le solde actuel de l'espace de travail
monid setup	Terminer la configuration du CLI après l'installation (aucune clé API requise)
monid keys add	Ajouter une clé API (-k <clé> -l <étiquette>)
monid keys list	Afficher les clés configurées
monid keys remove	Supprimer une clé (-l <étiquette>, -f pour ignorer la confirmation)
monid keys activate	Changer la clé active (-l <étiquette>)

La plupart des commandes acceptent -j/--json pour une sortie JSON lisible par machine.

---

Flux de travail

Le flux de travail standard est : découvrir → inspecter → exécuter → interroger → (vérifier le solde).

# 1. Découvrez des endpoints pour votre besoin de données
# Les résultats montrent le score de pertinence et le badge vérifié
# Utilisez -s pour filtrer par score minimum (plus élevé = plus pertinent)
monid discover -q "posts twitter"

# 2. Inspectez l'endpoint pour connaître son schéma d'entrée (affiche le statut vérifié)
monid inspect -p apify -e /apidojo/tweet-scraper

# 3. Lancez l'exécution (retourne immédiatement avec un ID d'exécution)
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["IA"],"maxItems":10}'
# -> ID d'exécution : 01HXYZ...

# 4. Interrogez pour l'achèvement
monid runs get -r 01HXYZ...
# -> statut : RUNNING

# Continuez à interroger toutes les 5 à 10 secondes jusqu'à COMPLETED
monid runs get -r 01HXYZ... -o tweets.json
# -> statut : COMPLETED

# 5. (Facultatif) Vérifiez le solde restant
monid balance

Utilisation de --wait :

--wait bloque jusqu'à la fin (1 à 120 secondes) avec une temporisation exponentielle intégrée :

# Cela bloquera pour toute la durée
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["IA"],"maxItems":10}' \
  -w -o tweets.json

Quand utiliser --wait :

• Tâches asynchrones/en arrière-plan où le blocage est acceptable
• Vous pouvez définir un délai d'attente : -w 30 (attendre max 30 secondes)
• Soyez conscient : les exécutions peuvent prendre 1 à 120 secondes, cela peut donc bloquer la conversation ou atteindre les délais d'attente d'exécution

---

Flux d'exemple

Flux 1 : Scraper les posts Twitter sur l'IA

# Découvrez quels endpoints Twitter sont disponibles
monid discover -q "posts twitter"

# Inspectez pour connaître le schéma d'entrée (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper

# Exécutez avec un seul terme de recherche, petite limite
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["agents IA"],"maxItems":10}'
# -> ID d'exécution : 01HXYZ...

# Interrogez pour l'achèvement (~10-30 secondes pour les petites demandes)
monid runs get -r 01HXYZ...
# -> statut : RUNNING

# Vérifiez à nouveau après 10 secondes, sauvegardez lorsque terminé
monid runs get -r 01HXYZ... -o ai_tweets.json
# -> statut : COMPLETED

Flux 2 : Comparer les discussions sur l'IA entre plateformes

L'utilisateur demande : "Comparez les discussions sur l'IA sur Twitter et LinkedIn."

Divisez cela en morceaux unitaires — un endpoint par source de données :

# Découvrez des endpoints pour chaque plateforme
monid discover -q "posts twitter"
monid discover -q "posts linkedin"

# Inspectez chacun pour connaître leurs schémas d'entrée (pathParams, queryParams, body)
monid inspect -p apify -e /apidojo/tweet-scraper
monid inspect -p apify -e /harvestapi/linkedin-post-search

# Lancez les deux exécutions
monid run -p apify -e /apidojo/tweet-scraper \
  -i '{"searchTerms":["IA"],"maxItems":20}'
# -> ID d'exécution : 01HTWIT...

monid run -p apify -e /harvestapi/linkedin-post-search \
  -i '{"keywords":"IA","maxResults":20}'
# -> ID d'exécution : 01HLINK...

# Interrogez les deux exécutions indépendamment
monid runs get -r 01HTWIT... -o twitter_ai.json
monid runs get -r 01HLINK... -o linkedin_ai.json

# Analysez et comparez maintenant les deux fichiers de résultats

Flux 2b : Alimenter un fichier local vers un endpoint qui a besoin d'une URL publique

Certains endpoints (par exemple, la génération image- vers-vidéo) prennent une URL en entrée, pas un fichier. Votre espace de travail dispose d'un système de fichiers distant intégré — le fournisseur sfs (créé automatiquement lors de la première utilisation, GRATUIT avec 1 Go inclus). Pilotez-le avec monid run comme n'importe quel autre fournisseur ; il expose des endpoints de type unix (/put, /cat, /ls, /mv, /rm, /mkdir) que vous pouvez monid inspect pour les schémas. L'API ne signe que les URL — les octets du fichier se déplacent directement entre vous et sfs.monid.ai via curl.

# 1. Signez un téléchargement (sizeBytes est requis — obtenez-le avec wc -c)
monid run -p sfs -e /put \
  -i "{\"path\":\"in/photo.png\",\"sizeBytes\":$(wc -c < ./photo.png)}" -w
# -> sortie : { "uploadUrl": "https://sfs.monid.ai/…", "ref": … }

# 2. Téléchargez les octets vers l'URL signée
curl -T ./photo.png '<uploadUrl de l'étape 1>'

# 3. Générez une URL que tout tiers peut récupérer (ttl preset : 1h/1j/7j/30j, défaut 1h)
monid run -p sfs -e /cat -i '{"path":"in/photo.png","ttl":"1j"}' -w
# -> sortie : { "url": "https://sfs.monid.ai/…?e=…&s=…", "expiresAt": … }

# 4. Utilisez-la comme URL d'entrée pour l'endpoint
monid run -p bytedance -e /seedance… -i '{"imageUrl": "<url de l'étape 3>"}'

# Le téléchargement fonctionne de la même manière : /cat renvoie une url signée — curl it
curl -o photo.png '<url de /cat>'

# Le nettoyage vous appartient (les fichiers ne sont jamais automatiquement supprimés ; /rm libère de l'espace de quota)
monid run -p sfs -e /rm -i '{"path":"in/photo.png"}' -w

Flux 3 : Utilisation de paramètres de requête et de chemin

Lorsque monid inspect montre queryParams ou pathParams, passez-les avec --query et --path :

# inspect montre : body, queryParams, et pathParams
monid inspect -p some-provider -e /users/{userId}/posts

# Exécutez avec les trois types de paramètres
monid run -p some-provider -e /users/{userId}/posts \
  --path '{"userId": "12345"}' \
  --query '{"limit": 10, "sort": "recent"}' \
  -i '{"filter": "public"}' \
  -w -o posts.json

Flux 4 : Utilisation d'un fichier d'entrée pour des paramètres complexes

Lorsque le JSON d'entrée est volumineux ou réutilisable, écrivez-le dans un fichier et utilisez -f :

# Écrivez l'entrée dans un fichier
# (supposons que params.json contienne les paramètres d'entrée du corps de l'endpoint)

monid run -p apify -e /damilo/google-maps-scraper \
  -f params.json -w -o results.json

---

Avertissement sur les Coûts et le Budget

De nombreux endpoints (en particulier Apify) sont facturés par résultat et acceptent plusieurs requêtes en un seul appel. Des paramètres comme maxItems, maxResults, resultsLimit, ou limit contrôlent le nombre de résultats renvoyés — mais ces limites sont souvent appliquées par requête, pas par appel.

Par exemple, passer 3 termes de recherche avec maxItems: 10 peut renvoyer jusqu'à 30 résultats (10 par requête), pas 10 au total.

Pour contrôler les coûts :

• Préférez une seule requête par appel. Passez un terme de recherche, une URL, un hashtag à la fois.
• Commencez avec de petites limites (5-10) lors du premier appel. Augmentez si nécessaire.
• Si l'endpoint accepte un tableau (par exemple searchTerms, hashtags, urls), ne passez qu'un seul élément, sauf si l'utilisateur demande explicitement plusieurs.
• Vérifiez le schéma d'entrée à partir de monid inspect pour identifier les paramètres qui contrôlent le volume.

---

Gestion des Clés

monid keys add -k <clé-api> -l <étiquette>     # Ajouter une clé (la première clé est auto-activée)
monid keys list                              # Afficher toutes les clés configurées
monid keys activate -l <étiquette>               # Changer la clé active
monid keys remove -l <étiquette>                 # Supprimer une clé (utilisez -f pour ignorer la confirmation)

Format de la clé API : monid_<stade>_<secret> (par exemple monid_live_abc123...). Générez des clés sur https://app.mon