Usare Argorant dalla CLI e nelle pipeline CI

La CLI è un wrapper senza dipendenze sulla stessa REST API usata dall'app web e dal connettore MCP. Esiste per i casi in cui costruire liste fa parte di un workflow ricorrente invece di essere qualcosa che una persona fa il martedì: un aggiornamento notturno, un passaggio di CI che mantiene aggiornato un CRM, un ciclo di un agente che ha bisogno di una risposta leggibile da una macchina. Questa guida percorre tutto il cammino, comprese le parti che costano denaro e la forma esatta di un'esecuzione che non può spendere più di quanto volevi.

L'unica regola da interiorizzare subito

Prima di qualsiasi comando: reveal, export e verify --file chiedono conferma solo quando stdin è un terminale e non hai passato né -y né --json. In CI, dentro una pipe o dentro il ciclo di un agente non c'è alcuna richiesta di conferma e questi comandi spendono subito.

La richiesta di conferma è una comodità per le persone, mai una rete di sicurezza. Ciò che controlla davvero la spesa è il numero che passi a -n, quindi leggilo prima di eseguire, soprattutto in uno script che nessuno starà guardando.

Installazione e primo avvio

Se non vuoi, non devi installare nulla:

npx argorant count "fintech CFOs in germany"

Oppure installala globalmente, dove il pacchetto si chiama argorant:

npm install -g argorant

Gestione delle chiavi: quali credenziali hanno la precedenza

La CLI accetta una chiave ag_live_, creata in Profilo, Chiavi API. Ci sono tre modi per fornirla e un ordine di precedenza rigoroso.

In modo interattivo, sul tuo computer

npx argorant login

Ti chiede la chiave con l'input nascosto, la convalida con l'endpoint dell'account e la salva. Una chiave rifiutata fallisce subito con un messaggio chiaro, invece di essere salvata e fallire più tardi su un comando che costa denaro. Puoi anche passarla direttamente come argorant login <key>.

Variabile d'ambiente, per CI e agenti

export ARGORANT_API_KEY=ag_live_...

È la soluzione giusta per script, pipeline e agenti. Non viene scritto nulla su disco e la variabile viene letta a ogni esecuzione.

Ordine di precedenza

1. ARGORANT_API_KEY nell'ambiente ha la precedenza su tutto.
2. Altrimenti viene usata la chiave salvata da argorant login, in ~/.argorant/config.json, scritta con permessi 0600.
3. Se non c'è nessuna delle due, i comandi terminano con codice 2 e ti dicono di effettuare il login.

argorant logout rimuove il file di configurazione. Se ARGORANT_API_KEY è ancora impostata, la CLI ti avvisa, perché quella variabile ha la precedenza e ti manterrebbe autenticato. Rimuovi anche quella.

Igiene delle chiavi nelle pipeline

• Una chiave per ogni pipeline o agente. L'utilizzo resta attribuibile e revocarne una non blocca mai le altre.
• Le chiavi vanno nel gestore dei secret della CI, mai in un file sotto versione e mai incollate in una chat condivisa. Le cronologie delle chat vengono esportate e fotografate; se è successo, ruota la chiave adesso.
• Ruota senza interruzioni: crea la nuova chiave, distribuiscila, verifica con npx argorant whoami, poi revoca quella vecchia. La revoca è immediata e la richiesta successiva che la usa fallisce con 401.

I comandi gratuiti, da usare senza risparmio

count restituisce la dimensione di un segmento. search restituisce le persone corrispondenti con l'identità oscurata. company ti dice se un account specifico è raggiungibile. Nessuno di questi scala crediti contatto; valgono permessi dell'account, quote e limiti di frequenza.

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

Aggiungi --json a qualsiasi comando per avere un output leggibile da una macchina. Script e agenti dovrebbero usarlo sempre: i nomi dei campi sono stabili, la formattazione per le persone no, e analizzare l'output formattato è il modo in cui una pipeline si rompe in silenzio a un aggiornamento.

I filtri sono condivisi da tutti i comandi di tipo ricerca, quindi ciò che impari con count vale identico per search, reveal, export e 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 è la porta più ampia e affidabile, con la virgola che significa OR, e in genere funziona meglio di --industry. --country e --geography sono lo stesso filtro e accettano regioni come Europe, EMEA, DACH, Nordics, APAC, LATAM e GCC.

Due opzioni si comportano diversamente da quanto suggerisce il nome, e la CLI te lo dice invece di fingere. --exclude-title viene applicata completamente da export e list create, ma non ancora da count, search e reveal, dove viene scritta una nota su stderr. --grade sceglie tra l'insieme rigoroso degli indirizzi recapitabili e quello più ampio che include i catch-all, ed è collegata da un capo all'altro su reveal ed export, ma la piattaforma non filtra ancora in base a essa, quindi la CLI ti avvisa invece di dichiarare di averlo fatto.

Due protezioni sull'analisi dei parametri sono sempre attive: un -n non numerico interrompe il comando invece di ripiegare sul limite predefinito, e un'opzione con valore seguita da un'altra opzione interrompe il comando invece di inglobarla. Esistono entrambe perché un'opzione inglobata invierebbe una richiesta che non hai mai chiesto, con i tuoi soldi.

Liste salvate dal terminale

Una lista salvata è un insieme di filtri riutilizzabile, non un'istantanea congelata. Crearla è gratis e non mostra nessun contatto.

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

Le liste sono condivise tra tutte le interfacce. Una lista creata dalla tua pipeline compare nell'app web, e una che un collega costruisce nell'app è visibile alla tua pipeline. Dato che list status è gratuito, un job programmato può seguire ogni giorno l'evoluzione di un mercato senza spendere nulla: è il monitoraggio più economico che costruirai mai.

Esportazioni e percorso di recupero

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

Cosa succede, nell'ordine:

1. Il percorso di output viene verificato come scrivibile prima che il job venga creato, così un percorso sbagliato non può mai farti pagare un file che non riesci a salvare.
2. Ti viene chiesta conferma, a meno che tu non abbia passato -y o --json o che stdin non sia un terminale.
3. Il job viene creato e monitorato. La verifica avviene in questo momento e vengono addebitate solo le righe recapitabili.
4. Il CSV finisce nel percorso indicato con -o e viene stampato il numero di righe.

Due impostazioni predefinite da conoscere: has_email è true per default, così le righe esportate hanno un indirizzo, e i contatti che hai già esportato vengono saltati a meno che tu non passi --include-exported. Questa seconda è ciò che fa sì che un aggiornamento programmato restituisca persone nuove invece di reinserire tutti.

Bivio: il processo si è interrotto a metà esportazione

Un'esportazione a pagamento non è mai irrecuperabile. Se la CLI si interrompe dopo la creazione del job, stampa i comandi esatti per il recupero, ed entrambi sono gratuiti:

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

Bivio: l'esportazione supera le 50,000 righe

Oltre le 50,000 righe il job diventa un lotto in più parti. La CLI monitora il lotto e scrive un file per ogni parte, leads-part1.csv, leads-part2.csv e così via, stampando l'id del lotto così puoi recuperarlo di nuovo più tardi:

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

Verificare i tuoi indirizzi

verify controlla gli indirizzi che porti tu e costa mezzo credito per controllo, scalato dal tuo saldo normale.

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

Con un file estrae e deduplica gli indirizzi, li invia in blocchi da 500 e scrive un CSV con email,status,deliverable, per default argorant-verified.csv. Il riepilogo indica quanti erano recapitabili, quanti controlli sono stati addebitati e quanti erano gratuiti perché esisteva già un risultato recente. Se non trova alcun indirizzo, si interrompe e suggerisce --column invece di non fare nulla in silenzio.

I contatti esportati da Argorant sono già verificati al momento dell'esportazione, quindi questo comando serve per le liste che arrivano da altre fonti.

Codici di uscita: il contratto con la tua pipeline

Fai le diramazioni in base ai codici di uscita, mai ai messaggi di errore.

• 0 successo.
• 1 errore generico: uso sbagliato, problema di rete o un job fallito lato server. Qualcosa è davvero rotto.
• 2 non autenticato. Nessuna chiave, o la chiave è stata rifiutata. Sistema la credenziale, poi riprova.
• 3 accesso negato. La chiave è valida ma non ha i permessi necessari. Ampliare una chiave è una decisione umana, non un nuovo tentativo.
• 4 limite di frequenza o quota giornaliera. Fermati e riprendi più tardi.
• 5 serve un pagamento o un piano superiore. Il messaggio contiene il link.

Il codice 5 è volutamente distinto da 1 proprio per questo motivo. Una pipeline che ritenta in loop un problema di pagamento è una pipeline che ti sveglia alle quattro del mattino per qualcosa che può risolvere solo una persona con una carta di credito.

Uno schema shell che regge:

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

I codici corrispondono direttamente agli status HTTP della REST API: 401 diventa 2, 403 diventa 3, 429 diventa 4, 402 diventa 5. Un agente che usa entrambe le interfacce può condividere un'unica gestione degli errori.

Un cron job che aggiorna un segmento

La struttura che funziona in produzione mette ogni passaggio gratuito prima di ogni passaggio a pagamento, così una notte andata male non costa nulla.

#!/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

Quattro caratteristiche rendono questo script sicuro e non solo funzionante. Il limite di righe è una variabile con un nome in cima, non un valore predefinito nascosto in un comando. Il controllo gratuito dello stato avviene prima di qualsiasi addebito. Un problema di pagamento avvisa una persona invece di ritentare. E un limite di frequenza esce con zero, perché ci penserà l'esecuzione di domani, e una build rossa per un limite temporaneo abitua le persone a ignorare le build rosse.

Errori che commetti una volta sola

• Contare sulla richiesta di conferma per salvarti. In CI la richiesta non c'è. Il valore di -n è il budget.
• Analizzare l'output pensato per le persone. Nelle automazioni usa --json ovunque, dal primo commit.
• Lasciare ARGORANT_API_KEY impostata dopo un logout. L'ambiente ha la precedenza, quindi sei ancora autenticato.
• Ritentare un codice 5. Nessun numero di tentativi genera crediti.
• Rieseguire da zero un'esportazione non riuscita. Se il job è stato creato è stato anche addebitato, e export download lo recupera gratis. Controlla prima di rieseguire.
• Condividere una chiave tra tre pipeline. La revochi una volta e le blocchi tutte e tre, e non saprai mai quale l'ha fatta trapelare.

Un'ultima nota sull'ambito: argorant campaigns esiste ma è un'interfaccia interna per gli operatori, e una normale chiave cliente riceve lì un 401 o un 403. È il sistema che funziona correttamente, non un bug da segnalare. Per i clienti i comandi che contano sono count, list, export e verify, più l'integrazione che invia il file finito al tuo strumento di sequenze.