Utiliser Argorant depuis la CLI et dans les pipelines CI

La CLI est une surcouche sans dépendance de la même API REST qu'utilisent l'app web et le connecteur MCP. Elle existe pour le cas où la construction de listes fait partie d'un workflow récurrent plutôt que d'une tâche qu'une personne effectue un mardi : une actualisation nocturne, une étape CI qui tient un CRM à jour, une boucle d'agent qui a besoin d'une réponse lisible par machine. Ce guide parcourt tout ce chemin, y compris les parties qui dépensent de l'argent et la forme exacte d'une exécution qui ne peut pas dépenser plus que prévu.

La règle à intégrer avant tout

Avant toute commande : reveal, export et verify --file ne demandent une confirmation que si stdin est un terminal et que vous n'avez passé ni -y ni --json. En CI, dans un pipe ou dans une boucle d'agent, il n'y a aucune invite et ces commandes dépensent immédiatement.

L'invite de confirmation est une commodité pour les humains, jamais un filet de sécurité. Ce qui contrôle réellement la dépense, c'est le nombre que vous passez à -n : relisez-le avant d'exécuter, surtout dans un script que personne ne surveillera.

Installation et première exécution

Rien à installer si vous ne le souhaitez pas :

npx argorant count "fintech CFOs in germany"

Ou installez-la globalement, sous le nom de paquet argorant :

npm install -g argorant

Gestion de la clé, et quel identifiant l'emporte

La CLI prend une clé ag_live_, créée sous Profil, Clés API. Il y a trois façons de la fournir et un ordre de priorité strict.

En interactif, pour votre propre machine

npx argorant login

Elle demande la clé en masquant la saisie, la valide auprès de l'endpoint du compte et l'enregistre. Une clé refusée échoue immédiatement avec un message clair au lieu d'être enregistrée puis d'échouer plus tard sur une commande payante. Vous pouvez aussi la passer directement : argorant login <key>.

Variable d'environnement, pour la CI et les agents

export ARGORANT_API_KEY=ag_live_...

C'est la bonne approche pour les scripts, pipelines et agents. Rien n'est écrit sur le disque, et la variable est lue à chaque appel.

Ordre de priorité

1. ARGORANT_API_KEY dans l'environnement l'emporte sur tout.
2. Sinon, c'est la clé enregistrée par argorant login qui est utilisée, depuis ~/.argorant/config.json, écrit en mode 0600.
3. Sans l'une ni l'autre, les commandes s'arrêtent avec le code 2 et vous demandent de vous connecter.

argorant logout supprime le fichier de configuration. Si ARGORANT_API_KEY est toujours définie, la CLI vous avertit, car cette variable est prioritaire et vous maintiendrait authentifié. Supprimez-la aussi.

Hygiène des clés pour les pipelines

• Une clé par pipeline ou par agent. L'usage reste attribuable et révoquer une clé n'en casse jamais une autre.
• Les clés vont dans le coffre de secrets de la CI, jamais dans un fichier versionné ni collées dans un chat partagé. Les historiques de chat sont exportés et capturés en image ; si c'est arrivé, renouvelez la clé maintenant.
• Renouvelez sans interruption : créez la nouvelle clé, déployez-la, confirmez avec npx argorant whoami, puis révoquez l'ancienne. La révocation est immédiate et la requête suivante qui l'utilise échoue avec une erreur 401.

Les commandes gratuites, à utiliser sans retenue

count renvoie la taille d'un segment. search renvoie les personnes correspondantes avec l'identité masquée. company indique si un compte précis est joignable. Aucune ne déduit de crédits contacts ; les autorisations, quotas et limites de débit du compte s'appliquent.

npx argorant count "fintech CFOs in germany"
npx argorant count --keywords logistics --country "United States" --seniority vp
npx argorant search "heads of procurement" --country Germany -n 10

Ajoutez --json à n'importe quelle commande pour une sortie lisible par machine. Scripts et agents devraient toujours l'utiliser : les noms de champs sont stables, la mise en forme humaine ne l'est pas, et analyser la sortie formatée est la façon dont un pipeline casse en silence lors d'une mise à jour.

Les filtres sont communs à toutes les commandes de type recherche : ce que vous apprenez sur count s'applique tel quel à search, reveal, export et list create :

--keywords --title --exclude-title --seniority --department --industry
--country --geography --state --city --company --domain
--has-phone --has-linkedin --has-email --verified-only
-n/--limit  -o/--output  --json  -y/--yes  --base  --grade

--keywords est la porte la plus large et la plus fiable, la virgule signifiant OU, et elle fait généralement mieux que --industry. --country et --geography sont le même filtre et acceptent des régions comme Europe, EMEA, DACH, Nordics, APAC, LATAM et GCC.

Deux options se comportent autrement que leur nom ne le laisse penser, et la CLI vous le dit au lieu de faire semblant. --exclude-title est pleinement appliquée par export et list create, mais pas encore par count, search et reveal, où une note s'affiche sur stderr. --grade choisit entre l'ensemble délivrable strict et l'ensemble élargi qui inclut les catch-all ; elle est câblée de bout en bout sur reveal et export, mais la plateforme ne filtre pas encore dessus, donc la CLI avertit au lieu de prétendre l'avoir fait.

Deux garde-fous d'analyse sont toujours actifs : un -n non numérique interrompt l'exécution au lieu de revenir à la limite par défaut, et une option à valeur suivie d'une autre option interrompt l'exécution au lieu de l'absorber. Les deux existent parce qu'une option absorbée enverrait une requête que vous n'avez jamais demandée, avec votre argent.

Listes enregistrées depuis le terminal

Une liste enregistrée est un jeu de filtres réutilisable plutôt qu'un instantané figé. En créer une est gratuit et ne débloque rien.

npx argorant list create --name "DACH CFOs 200+" --title CFO --country DACH
npx argorant list status 42

Les listes sont partagées entre les interfaces. Une liste créée par votre pipeline apparaît dans l'app web, et une liste construite dans l'app par un collègue est visible par votre pipeline. Comme list status est gratuit, une tâche programmée peut suivre chaque jour l'évolution d'un marché sans rien dépenser : c'est la surveillance la moins chère que vous construirez jamais.

Les exports, et la voie de reprise

npx argorant export "fintech CFOs" --country Germany -n 1000 -o leads.csv

Ce qui se passe, dans l'ordre :

1. Le chemin de sortie est vérifié comme accessible en écriture avant la création de la tâche : un mauvais chemin ne peut jamais vous faire payer un fichier que vous ne pouvez pas enregistrer.
2. Une confirmation vous est demandée, sauf si vous avez passé -y ou --json ou si stdin n'est pas un terminal.
3. La tâche est créée et interrogée régulièrement. La vérification a lieu à ce moment-là et seules les lignes délivrables sont facturées.
4. Le CSV arrive à votre chemin -o et le nombre de lignes s'affiche.

Deux valeurs par défaut à connaître : has_email vaut true par défaut pour que les lignes exportées comportent une adresse, et les contacts déjà exportés sont ignorés sauf si vous passez --include-exported. C'est ce second réglage qui permet à une actualisation programmée de renvoyer de nouvelles personnes au lieu de réinscrire tout le monde.

Embranchement : le processus s'est arrêté en plein export

Un export payé n'est jamais irrécupérable. Si la CLI s'arrête après la création de la tâche, elle affiche les commandes de reprise exactes, et les deux sont gratuites :

npx argorant export status 12345
npx argorant export download 12345 -o leads.csv

Embranchement : l'export dépasse 50,000 lignes

Au-delà de 50,000 lignes, la tâche devient un lot en plusieurs morceaux. La CLI interroge le lot et écrit un fichier par morceau, leads-part1.csv, leads-part2.csv et ainsi de suite, en affichant l'identifiant du lot pour que vous puissiez le récupérer plus tard :

npx argorant export status 987 --batch
npx argorant export download 987 --batch -o leads.csv

Vérifier vos propres adresses

verify vérifie les adresses que vous apportez vous-même et coûte un demi-crédit par vérification sur votre solde habituel.

npx argorant verify someone@company.com
npx argorant verify --file emails.csv -o out.csv
npx argorant verify --file contacts.csv --column work_email -o out.csv

Avec un fichier, elle extrait et dédoublonne les adresses, les envoie par lots de 500 et écrit un CSV avec email,status,deliverable, par défaut argorant-verified.csv. Le récapitulatif indique combien étaient délivrables, combien de vérifications ont été facturées et combien étaient gratuites parce qu'un résultat récent existait déjà. Si aucune adresse n'est trouvée, elle s'interrompt et suggère --column au lieu de ne rien faire en silence.

Les contacts exportés depuis Argorant sont déjà vérifiés au moment de l'export : cette commande sert aux listes venues d'ailleurs.

Codes de sortie : le contrat avec votre pipeline

Conditionnez sur les codes de sortie, jamais sur les messages d'erreur.

• 0 succès.
• 1 erreur générique : mauvaise utilisation, panne réseau ou tâche en échec côté serveur. Quelque chose est vraiment cassé.
• 2 non authentifié. Pas de clé, ou clé refusée. Corrigez l'identifiant, puis réessayez.
• 3 interdit. La clé est valide mais n'a pas la portée nécessaire. Élargir une clé est une décision humaine, pas une nouvelle tentative.
• 4 limite de débit ou quota quotidien. Ralentissez et reprenez plus tard.
• 5 paiement ou passage à un forfait supérieur requis. Le message contient le lien.

Le code 5 est volontairement distinct du code 1 précisément pour cette raison. Un pipeline qui réessaie en boucle un problème de paiement est un pipeline qui vous réveille à quatre heures du matin pour un problème que seul un humain muni d'une carte bancaire peut régler.

Un modèle de shell qui tient la route :

npx argorant export --keywords fintech --country Germany -n 500 -o leads.csv --yes
case $? in
  0) echo "done" ;;
  2|3) echo "credential problem, stopping"; exit 1 ;;
  4) echo "rate limited, retry later" ;;
  5) echo "needs credits, notify a human" ;;
  *) echo "failed"; exit 1 ;;
esac

Les codes correspondent directement aux codes de statut HTTP de l'API REST : 401 devient 2, 403 devient 3, 429 devient 4, 402 devient 5. Un agent qui utilise les deux interfaces peut partager une seule logique de gestion des erreurs.

Une tâche cron qui actualise un segment

La forme qui fonctionne en production place chaque étape gratuite avant chaque étape payante : une mauvaise nuit ne coûte rien.

#!/usr/bin/env bash
set -euo pipefail
export ARGORANT_API_KEY="$ARGORANT_KEY_FROM_SECRET_STORE"
LIMIT=500
OUT="/var/data/leads-$(date +%F).csv"
FILTERS="--keywords fintech --title CFO --country Germany"

# 1. Free: how big is the segment right now?
SIZE=$(npx argorant count $FILTERS --json | jq -r '.count')
if [ "$SIZE" -lt 200 ]; then
  echo "segment too small to bother, skipping"; exit 0
fi

# 2. Paid: export, with an explicit ceiling and no prompt.
npx argorant export $FILTERS -n "$LIMIT" -o "$OUT" --yes --json
case $? in
  0) ./push-to-sequencer.sh "$OUT" ;;
  4) echo "rate limited, will run tomorrow" ; exit 0 ;;
  5) ./notify-human.sh "Argorant needs credits" ; exit 0 ;;
  *) exit 1 ;;
esac

0 6 * * 1 /opt/jobs/argorant-refresh.sh >> /var/log/argorant.log 2>&1

Quatre propriétés rendent ce script sûr, et pas seulement fonctionnel. La limite de lignes est une variable nommée en haut du script plutôt qu'une valeur par défaut enfouie dans une commande. La vérification de statut gratuite s'exécute avant toute facturation. Un problème de paiement prévient une personne au lieu de réessayer. Et une limite de débit renvoie zéro, car l'exécution du lendemain prendra le relais, et un build rouge pour une limite passagère apprend aux équipes à ignorer les builds rouges.

Les erreurs que vous ne ferez qu'une fois

• Compter sur l'invite de confirmation. En CI, il n'y a pas d'invite. La valeur de -n, c'est le budget.
• Analyser la sortie destinée aux humains. Utilisez --json partout dans l'automatisation, dès le premier commit.
• Laisser ARGORANT_API_KEY définie après une déconnexion. L'environnement l'emporte : vous êtes toujours authentifié.
• Réessayer un code 5. Aucun nombre de tentatives ne produit de crédits.
• Relancer de zéro un export en échec. Si la tâche a été créée, elle a été facturée, et export download la récupère gratuitement. Vérifiez avant de relancer.
• Partager une seule clé entre trois pipelines. Révoquez-la une fois et vous cassez les trois, sans jamais savoir lequel l'a laissée fuiter.

Une dernière remarque sur le périmètre : argorant campaigns existe mais c'est une interface interne d'opérateur, et une clé client normale reçoit une erreur 401 ou 403. C'est le système qui fonctionne correctement, pas un bug à signaler. Pour les clients, les commandes qui comptent sont count, list, export et verify, plus l'intégration qui envoie le fichier final dans votre propre outil de séquences.