Usar Argorant desde la CLI y en pipelines de CI

La CLI es un envoltorio sin dependencias sobre la misma REST API que usan la app web y el conector MCP. Existe para cuando la creación de listas forma parte de un flujo recurrente y no es algo que una persona hace un martes: una actualización nocturna, un paso de CI que mantiene al día un CRM, un ciclo de agente que necesita una respuesta legible por máquinas. Esta guía recorre todo el camino, incluidas las partes que gastan dinero y la forma exacta de una ejecución que no puede gastar más de lo que pretendías.

La única regla que debes interiorizar primero

Antes de cualquier comando: reveal, export y verify --file piden confirmación solo cuando stdin es una terminal y no pasaste ni -y ni --json. En CI, dentro de una tubería o dentro de un ciclo de agente no hay ninguna confirmación y estos comandos gastan de inmediato.

La confirmación es una comodidad para personas, nunca una red de seguridad. Lo que de verdad controla el gasto es el número que pasas a -n, así que léelo antes de ejecutar, sobre todo en un script que nadie va a vigilar.

Instalación y primera ejecución

No hace falta instalar nada si no quieres:

npx argorant count "fintech CFOs in germany"

O instálala de forma global; el paquete se llama argorant:

npm install -g argorant

Gestión de la clave y qué credencial tiene prioridad

La CLI acepta una clave ag_live_, creada en Perfil, Claves de API. Hay tres formas de proporcionarla y un orden de prioridad estricto.

Interactiva, para tu propio equipo

npx argorant login

Te la pide con la entrada oculta, valida la clave contra el endpoint de la cuenta y la guarda. Una clave rechazada falla de inmediato con un mensaje claro en lugar de guardarse y fallar más tarde en un comando que cuesta dinero. También puedes pasarla directamente como argorant login <key>.

Variable de entorno, para CI y agentes

export ARGORANT_API_KEY=ag_live_...

Es la forma adecuada para scripts, pipelines y agentes. No se escribe nada en disco y la variable se lee en cada ejecución.

Prioridad

1. ARGORANT_API_KEY en el entorno tiene prioridad sobre todo lo demás.
2. Si no, se usa la clave guardada por argorant login, en ~/.argorant/config.json, escrita con el modo 0600.
3. Si no hay ninguna de las dos, los comandos terminan con el código 2 y te indican que inicies sesión.

argorant logout elimina el archivo de configuración. Si ARGORANT_API_KEY sigue definida, la CLI te avisa, porque esa variable tiene prioridad y te mantendría autenticado. Elimínala también.

Higiene de claves en pipelines

• Una clave por pipeline o agente. El uso sigue siendo atribuible y revocar una nunca rompe otra.
• Las claves van en el almacén de secretos del CI, nunca en un archivo confirmado en el repositorio ni pegadas en un chat compartido. Los historiales de chat se exportan y se capturan en pantalla; si ya pasó, rota la clave ahora.
• Rota sin tiempo de inactividad: crea la clave nueva, despliégala, confirma con npx argorant whoami y luego revoca la antigua. La revocación es inmediata y la siguiente solicitud que la use falla con 401.

Los comandos gratuitos, que deberías exprimir

count devuelve el tamaño de un segmento. search devuelve las personas que coinciden con la identidad anonimizada. company responde si se puede llegar a una cuenta concreta. Ninguno descuenta créditos de contacto; se aplican los permisos de la cuenta, los cupos y los límites de frecuencia.

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

Agrega --json a cualquier comando para obtener una salida legible por máquinas. Los scripts y los agentes siempre deberían usarlo: los nombres de los campos son estables, el formato para personas no, y analizar la salida bonita es la forma en que un pipeline se rompe en silencio con una actualización.

Los filtros son comunes a todos los comandos de búsqueda, así que lo que aprendes con count se aplica sin cambios a search, reveal, export y 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 es la puerta más amplia y fiable, con la coma como OR, y en general funciona mejor que --industry. --country y --geography son el mismo filtro y aceptan regiones como Europe, EMEA, DACH, Nordics, APAC, LATAM y GCC.

Dos opciones se comportan de forma distinta a lo que sugieren sus nombres, y la CLI te lo dice en lugar de disimular. --exclude-title se aplica por completo en export y list create, pero todavía no en count, search y reveal, donde se envía un aviso a stderr. --grade elige entre el conjunto entregable estricto y el más amplio que incluye catch-all, y está conectado de principio a fin en reveal y export, pero la plataforma todavía no filtra por ella, así que la CLI avisa en lugar de afirmar que lo hizo.

Hay dos salvaguardas de análisis siempre activas: un -n no numérico aborta en lugar de volver al límite por defecto, y una opción con valor seguida de otra opción aborta en lugar de tragársela. Ambas existen porque una opción tragada enviaría una solicitud que nunca pediste, con tu dinero.

Listas guardadas desde la terminal

Una lista guardada es un conjunto de filtros reutilizable, no una foto congelada. Crear una es gratis y no revela nada.

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

Las listas se comparten entre superficies. Una que crea tu pipeline aparece en la app web, y una que un compañero crea en la app es visible para tu pipeline. Como list status es gratis, una tarea programada puede seguir cada día cómo se mueve un mercado sin gastar nada, que es la monitorización más barata que vas a construir nunca.

Exportaciones y la vía de recuperación

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

Lo que ocurre, en orden:

1. Se comprueba que la ruta de salida tenga permisos de escritura antes de crear la tarea, así que una ruta incorrecta nunca puede cobrarte por un archivo que no puedes guardar.
2. Se te pide confirmación, salvo que hayas pasado -y o --json o que stdin no sea una terminal.
3. Se crea la tarea y se consulta su estado. La verificación se hace en ese momento y solo se cobran las filas entregables.
4. El CSV llega a tu ruta -o y se imprime el número de filas.

Dos valores por defecto que conviene conocer: has_email es true por defecto, así que las filas exportadas llevan una dirección, y los contactos que ya exportaste se omiten salvo que pases --include-exported. Lo segundo es lo que hace que una actualización programada devuelva personas nuevas en lugar de volver a inscribir a todo el mundo.

Bifurcación: el proceso se cayó a mitad de la exportación

Una exportación de pago nunca es irrecuperable. Si la CLI se cae después de crear la tarea, imprime los comandos de recuperación exactos, y los dos son gratis:

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

Bifurcación: la exportación supera las 50,000 filas

Por encima de 50,000 filas, la tarea se convierte en un lote de varias partes. La CLI consulta el lote y escribe un archivo por parte, leads-part1.csv, leads-part2.csv, etc., e imprime el ID del lote para que puedas recuperarlo más tarde:

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

Verificar tus propias direcciones

verify comprueba las direcciones que traes tú y cuesta medio crédito por comprobación de tu saldo normal.

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 archivo, extrae las direcciones y elimina los duplicados, las envía en bloques de 500 y escribe un CSV con email,status,deliverable, por defecto argorant-verified.csv. El resumen indica cuántas eran entregables, cuántas comprobaciones se cobraron y cuántas fueron gratis porque ya había un resultado reciente. Si no encuentra ninguna dirección, aborta y sugiere --column en lugar de no hacer nada en silencio.

Los contactos exportados desde Argorant ya se verificaron al exportar, así que este comando es para listas que vienen de otro sitio.

Códigos de salida: el contrato con tu pipeline

Bifurca según los códigos de salida, nunca según los textos de error.

• 0 éxito.
• 1 error genérico: uso incorrecto, fallo de red o una tarea que falló en el servidor. Algo está realmente roto.
• 2 sin autenticar. No hay clave o la clave se rechazó. Corrige la credencial y vuelve a intentarlo.
• 3 prohibido. La clave es válida pero no tiene el alcance necesario. Ampliar una clave es una decisión humana, no un reintento.
• 4 límite de frecuencia o cupo diario. Espera y continúa más tarde.
• 5 se requiere un pago o mejorar el plan. El mensaje incluye el enlace.

El código 5 es distinto de 1 a propósito, justo por eso. Un pipeline que reintenta en bucle un problema de pago es un pipeline que te despierta a las cuatro de la mañana por algo que solo puede arreglar una persona con una tarjeta de crédito.

Un patrón de shell que aguanta:

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

Los códigos corresponden directamente a los códigos de estado HTTP de la REST API: 401 se convierte en 2, 403 en 3, 429 en 4 y 402 en 5. Un agente que usa ambas superficies puede compartir una única ruta de gestión de errores.

Una tarea cron que actualiza un segmento

La forma que funciona en producción pone todos los pasos gratuitos antes de los de pago, así que una mala noche no cuesta nada.

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

Cuatro propiedades hacen que ese script sea seguro y no solo funcional. El límite de filas es una variable con nombre al principio, no un valor por defecto enterrado en un comando. La comprobación de estado gratuita se ejecuta antes de cobrar nada. Un problema de pago avisa a una persona en lugar de reintentar. Y un límite de frecuencia termina con cero, porque la ejecución de mañana lo recogerá, y un build en rojo por un límite pasajero enseña a la gente a ignorar los builds en rojo.

Errores que te pasarán exactamente una vez

• Dar por hecho que la confirmación te salvará. En CI no hay confirmación. El valor de -n es el presupuesto.
• Analizar la salida pensada para personas. Usa --json en toda la automatización desde el primer commit.
• Dejar ARGORANT_API_KEY definida después de cerrar sesión. El entorno tiene prioridad, así que sigues autenticado.
• Reintentar un 5. Ningún número de reintentos produce créditos.
• Volver a lanzar desde cero una exportación fallida. Si la tarea se creó, se cobró, y export download la recupera gratis. Compruébalo antes de volver a lanzarla.
• Compartir una clave entre tres pipelines. Revócala una vez y rompes los tres, y nunca sabrás cuál la filtró.

Una última nota sobre el alcance: argorant campaigns existe, pero es una superficie interna para operadores, y una clave normal de cliente recibe un 401 o un 403 ahí. Es el sistema funcionando bien, no un error que reportar. Para los clientes, los comandos que importan son count, list, export y verify, más la integración que lleve el archivo terminado a tu propio secuenciador.