De CLI is een wrapper zonder afhankelijkheden rond dezelfde REST API die de webapp en de MCP-connector gebruiken. Hij is er voor de situatie waarin lijsten bouwen deel is van een terugkerende workflow in plaats van iets wat iemand op een dinsdag doet: een nachtelijke verversing, een CI-stap die een CRM actueel houdt, een agentlus die een machineleesbaar antwoord nodig heeft. Deze handleiding loopt dat hele traject door, inclusief de delen die geld kosten en de precieze vorm van een run die niet meer kan uitgeven dan je bedoelde.
De ene regel die je eerst moet verinnerlijken
Vóór elk commando: reveal, export en verify --file vragen alleen om bevestiging als stdin een terminal is en je -y noch --json hebt meegegeven. In CI, in een pipe of in een agentlus is er helemaal geen prompt en geven deze commando's meteen uit.
De prompt is een gemak voor mensen, nooit een vangnet. Wat de uitgaven echt bepaalt, is het getal dat je aan -n meegeeft. Lees het dus voordat je iets draait, zeker in een script waar niemand meekijkt.
Installeren en eerste run
Niets te installeren als je dat niet wilt:
npx argorant count "fintech CFOs in germany"Of installeer hem globaal; het pakket heet argorant:
npm install -g argorant
Omgaan met sleutels, en welke inloggegevens voorgaan
De CLI gebruikt een ag_live_-sleutel, aangemaakt onder Profiel, API-sleutels. Je kunt hem op drie manieren meegeven, met een strikte volgorde van voorrang.
Interactief, voor je eigen computer
npx argorant loginHij vraagt de sleutel met verborgen invoer, controleert hem tegen het accountendpoint en slaat hem op. Een geweigerde sleutel faalt meteen met een duidelijke melding, in plaats van te worden opgeslagen en later te falen bij een commando dat geld kost. Je kunt hem ook direct meegeven als argorant login <key>.
Omgevingsvariabele, voor CI en agents
export ARGORANT_API_KEY=ag_live_...Dit is de juiste vorm voor scripts, pipelines en agents. Er wordt niets naar schijf geschreven, en de variabele wordt bij elke aanroep gelezen.
Voorrang
ARGORANT_API_KEYin de omgeving gaat voor alles.- Anders wordt de sleutel gebruikt die
argorant loginheeft opgeslagen, uit~/.argorant/config.json, geschreven met modus0600. - Zonder een van beide stoppen commando's met code
2en vragen ze je in te loggen.
argorant logout verwijdert het configuratiebestand. Staat ARGORANT_API_KEY nog ingesteld, dan waarschuwt de CLI je, omdat die variabele voorgaat en je ingelogd zou houden. Verwijder hem dus ook.
Sleutelhygiëne voor pipelines
- Eén sleutel per pipeline of agent. Het gebruik blijft toe te wijzen, en als je er een intrekt, breekt er nooit een andere.
- Sleutels horen in de geheimenopslag van je CI, nooit in een gecommit bestand en nooit geplakt in een gedeelde chat. Chatgeschiedenissen worden geëxporteerd en gescreenshot; is het gebeurd, vervang de sleutel dan nu.
- Vervangen zonder downtime: maak de nieuwe sleutel aan, rol hem uit, bevestig met
npx argorant whoamien trek daarna de oude in. Intrekken werkt meteen, en het volgende verzoek met de oude sleutel faalt met 401.
De gratis commando's, die je flink mag gebruiken
count geeft de omvang van een segment. search geeft passende personen met gemaskeerde identiteit. company beantwoordt of een specifiek account überhaupt bereikbaar is. Geen van drieën schrijft contactcredits af; rechten van het account, daglimieten en snelheidslimieten blijven gelden.
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
Voeg --json toe aan elk commando voor machineleesbare uitvoer. Scripts en agents moeten dat altijd doen: veldnamen zijn stabiel, de opmaak voor mensen niet, en het parsen van de mooie uitvoer is precies hoe een pipeline bij een upgrade stilletjes breekt.
Filters zijn gedeeld over alle commando's die zoeken, dus wat je leert bij count werkt ongewijzigd bij search, reveal, export en 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 is de breedste en betrouwbaarste ingang, waarbij een komma OF betekent, en het werkt meestal beter dan --industry. --country en --geography zijn hetzelfde filter en accepteren regio's zoals Europe, EMEA, DACH, Nordics, APAC, LATAM en GCC.
Twee flags gedragen zich anders dan hun naam doet vermoeden, en de CLI zegt dat eerlijk in plaats van te doen alsof. --exclude-title wordt volledig toegepast door export en list create, maar nog niet bij count, search en reveal; daar gaat een melding naar stderr. --grade kiest tussen de strikte bezorgbare set en de bredere set met catch-all, en is van begin tot eind aangesloten bij reveal en export, maar het platform filtert er nog niet op, dus de CLI waarschuwt in plaats van te beweren dat het gebeurd is.
Twee beveiligingen bij het parsen staan altijd aan: een niet-numerieke -n breekt af in plaats van terug te vallen op de standaardlimiet, en een flag met een waarde die door een andere flag wordt gevolgd, breekt af in plaats van die in te slikken. Beide bestaan omdat een ingeslikte flag een verzoek zou versturen waar je nooit om vroeg, met jouw geld.
Opgeslagen lijsten vanuit de terminal
Een opgeslagen lijst is een herbruikbare set filters, geen bevroren momentopname. Er een maken is gratis en geeft niets vrij.
npx argorant list create --name "DACH CFOs 200+" --title CFO --country DACH
npx argorant list status 42
Lijsten worden gedeeld tussen alle omgevingen. Een lijst die je pipeline maakt, verschijnt in de webapp, en een lijst die een collega in de app bouwt, is zichtbaar voor je pipeline. Omdat list status gratis is, kan een ingeplande taak dagelijks volgen hoe een markt beweegt zonder iets uit te geven. Goedkoper wordt monitoring niet.
Exports, en de weg terug bij problemen
npx argorant export "fintech CFOs" --country Germany -n 1000 -o leads.csvWat er gebeurt, op volgorde:
- Het uitvoerpad wordt voordat de taak wordt aangemaakt gecontroleerd op schrijfrechten, zodat een fout pad je nooit kan laten betalen voor een bestand dat je niet kunt opslaan.
- Je wordt om bevestiging gevraagd, tenzij je
-yof--jsonhebt meegegeven of stdin geen terminal is. - De taak wordt aangemaakt en gevolgd. Op dit moment draait de controle, en alleen bezorgbare rijen worden afgerekend.
- De CSV komt op je
-o-pad terecht en het aantal rijen wordt getoond.
Twee standaarden die je moet kennen: has_email staat standaard op true, zodat geëxporteerde rijen een adres hebben, en contacten die je al hebt geëxporteerd, worden overgeslagen tenzij je --include-exported meegeeft. Door die tweede levert een ingeplande verversing nieuwe mensen op in plaats van iedereen opnieuw in te schrijven.
Afslag: het proces stopte halverwege de export
Een betaalde export is nooit onherstelbaar. Stopt de CLI nadat de taak is aangemaakt, dan toont hij de precieze herstelcommando's, en beide zijn gratis:
npx argorant export status 12345
npx argorant export download 12345 -o leads.csvAfslag: de export is groter dan 50,000 rijen
Boven 50,000 rijen wordt de taak een batch in meerdere delen. De CLI volgt de batch en schrijft één bestand per deel, leads-part1.csv, leads-part2.csv enzovoort, en toont de batch-ID zodat je hem later opnieuw kunt ophalen:
npx argorant export status 987 --batch
npx argorant export download 987 --batch -o leads.csvJe eigen adressen controleren
verify controleert adressen die je zelf meebrengt en kost een halve credit per controle van je normale saldo.
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.csvMet een bestand haalt hij de adressen eruit, ontdubbelt ze, verstuurt ze in delen van 500 en schrijft een CSV met email,status,deliverable, standaard argorant-verified.csv. De samenvatting meldt hoeveel er bezorgbaar waren, hoeveel controles zijn afgerekend en hoeveel gratis waren omdat er al een recent resultaat was. Wordt er geen adres gevonden, dan breekt hij af en stelt --column voor, in plaats van stilletjes niets te doen.
Contacten die uit Argorant zijn geëxporteerd, zijn bij de export al gecontroleerd, dus dit commando is voor lijsten die ergens anders vandaan komen.
Exitcodes: het contract met je pipeline
Vertak op exitcodes, nooit op foutteksten.
0gelukt.1algemene fout: verkeerd gebruik, een netwerkfout of een taak die aan de serverkant mislukte. Er is echt iets kapot.2niet ingelogd. Geen sleutel, of de sleutel werd geweigerd. Herstel de inloggegevens en probeer het opnieuw.3verboden. De sleutel is geldig maar mist de rechten. Een sleutel ruimer maken is een beslissing voor een mens, geen nieuwe poging.4snelheidslimiet of daglimiet. Wacht even en ga later verder.5betaling of upgrade van het plan nodig. De melding bevat de link.
Code 5 verschilt om precies die reden bewust van 1. Een pipeline die een betalingsprobleem in een lus opnieuw probeert, is een pipeline die je om vier uur 's nachts oppiept over iets wat alleen een mens met een creditcard kan oplossen.
Een shellpatroon dat standhoudt:
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 ;;
esacDe codes komen direct overeen met HTTP-statuscodes in de REST API: 401 wordt 2, 403 wordt 3, 429 wordt 4, 402 wordt 5. Een agent die beide gebruikt, kan één pad voor foutafhandeling delen.
Een cronjob die een segment ververst
De opzet die in productie werkt, zet elke gratis stap vóór elke betaalde, zodat een slechte nacht niets kost.
#!/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 ;;
esac0 6 * * 1 /opt/jobs/argorant-refresh.sh >> /var/log/argorant.log 2>&1Vier eigenschappen maken dat script veilig in plaats van alleen werkend. De rijlimiet is een benoemde variabele bovenaan in plaats van een standaardwaarde die in een commando verstopt zit. De gratis statuscontrole draait voordat er iets wordt afgerekend. Een betalingsprobleem waarschuwt een mens in plaats van het opnieuw te proberen. En een snelheidslimiet eindigt met nul, omdat de run van morgen het oppakt en een rode build voor een tijdelijke limiet mensen leert rode builds te negeren.
Dingen die je precies één keer bijten
- Ervan uitgaan dat de prompt je redt. In CI is er geen prompt. De waarde van
-nis het budget. - Uitvoer voor mensen parsen. Gebruik
--jsonoveral in automatisering, vanaf de eerste commit. ARGORANT_API_KEYingesteld laten na een logout. De omgeving gaat voor, dus je bent nog steeds ingelogd.- Een 5 opnieuw proberen. Hoeveel pogingen je ook doet, er komen geen credits uit.
- Een mislukte export helemaal opnieuw draaien. Is de taak aangemaakt, dan is hij afgerekend, en
export downloadhaalt hem gratis op. Controleer dat voordat je opnieuw draait. - Eén sleutel delen over drie pipelines. Trek hem één keer in en je breekt ze alle drie, en je komt nooit te weten welke hem heeft gelekt.
Nog een laatste opmerking over de reikwijdte: argorant campaigns bestaat, maar is een interne omgeving voor beheerders, en een normale klantsleutel krijgt daar een 401 of 403. Dat is het systeem dat correct werkt, geen bug om te melden. Voor klanten zijn de commando's die ertoe doen count, list, export en verify, plus de integratie die het klare bestand naar je eigen e-mailtool doorzet.
