Como rodar o Argorant na CLI e em pipelines de CI

A CLI é um wrapper sem dependências sobre a mesma API REST que o app web e o conector MCP usam. Ela existe para o caso em que montar listas faz parte de um workflow recorrente, e não de algo que uma pessoa faz numa terça-feira: uma atualização noturna, uma etapa de CI que mantém um CRM atualizado, um loop de agente que precisa de uma resposta legível por máquina. Este guia percorre o caminho inteiro, incluindo as partes que gastam dinheiro e o formato exato de uma execução que não consegue gastar mais do que você pretendia.

A regra para gravar antes de tudo

Antes de qualquer comando: reveal, export e verify --file só pedem confirmação quando o stdin é um terminal e você não passou nem -y nem --json. Em CI, dentro de um pipe ou dentro de um loop de agente, não aparece nenhuma confirmação, e esses comandos gastam na hora.

A confirmação é uma conveniência para pessoas, nunca uma rede de segurança. O que realmente controla o gasto é o número que você passa para -n, então leia-o antes de rodar, principalmente num script em que ninguém vai estar olhando.

Instalação e primeira execução

Não precisa instalar nada se você não quiser:

npx argorant count "fintech CFOs in germany"

Ou instale globalmente; o pacote se chama argorant:

npm install -g argorant

Manejo da chave, e qual credencial vale

A CLI usa uma chave ag_live_, criada em Perfil, Chaves de API. Há três formas de fornecê-la e uma ordem de precedência rígida.

Interativo, para a sua própria máquina

npx argorant login

Ele pede a chave com a digitação mascarada, valida a chave no endpoint da conta e a guarda. Uma chave rejeitada falha na hora com uma mensagem clara, em vez de ser salva e falhar depois num comando que custa dinheiro. Você também pode passá-la direto como argorant login <key>.

Variável de ambiente, para CI e agentes

export ARGORANT_API_KEY=ag_live_...

Este é o formato certo para scripts, pipelines e agentes. Nada é gravado em disco, e a variável é lida a cada execução.

Precedência

1. ARGORANT_API_KEY no ambiente vence tudo.
2. Caso contrário, é usada a chave salva por argorant login, em ~/.argorant/config.json, gravado com permissão 0600.
3. Sem nenhuma das duas, os comandos saem com o código 2 e pedem que você faça login.

argorant logout remove o arquivo de configuração. Se ARGORANT_API_KEY ainda estiver definida, a CLI avisa, porque essa variável tem precedência e manteria você autenticado. Remova-a também.

Higiene de chaves em pipelines

• Uma chave por pipeline ou agente. O uso continua atribuível, e revogar uma nunca quebra outra.
• As chaves vão para o cofre de segredos do CI, nunca para um arquivo versionado e nunca coladas num chat compartilhado. Históricos de chat são exportados e viram capturas de tela; se isso aconteceu, troque a chave agora.
• Troque sem interrupção: crie a nova chave, publique, confirme com npx argorant whoami e só então revogue a antiga. A revogação é imediata, e a próxima requisição com ela falha com 401.

Os comandos grátis, que você deve usar até gastar

count retorna o tamanho de um segmento. search retorna as pessoas correspondentes com a identidade mascarada. company responde se uma conta específica é alcançável. Nenhum deles desconta créditos de contato; valem as permissões da conta, as cotas e os limites de requisições.

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

Acrescente --json a qualquer comando para ter saída legível por máquina. Scripts e agentes devem sempre usar: os nomes dos campos são estáveis, a formatação para humanos não é, e interpretar a saída bonita é como um pipeline quebra em silêncio numa atualização.

Os filtros são compartilhados por todos os comandos de busca, então o que você aprende no count vale igual para 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 é a porta mais ampla e mais confiável, com vírgula significando OU, e geralmente rende mais do que --industry. --country e --geography são o mesmo filtro e aceitam regiões como Europe, EMEA, DACH, Nordics, APAC, LATAM e GCC.

Duas flags se comportam de forma diferente do que os nomes sugerem, e a CLI avisa em vez de fingir. --exclude-title é aplicada por completo em export e list create, mas ainda não em count, search e reveal, onde uma nota vai para o stderr. --grade escolhe entre o conjunto estritamente entregável e o mais amplo, que inclui catch-all, e funciona de ponta a ponta em reveal e export, mas a plataforma ainda não filtra por ela, então a CLI avisa em vez de afirmar que filtrou.

Duas proteções de interpretação estão sempre ativas: um -n não numérico aborta em vez de cair no limite padrão, e uma flag de valor seguida de outra flag aborta em vez de engoli-la. As duas existem porque uma flag engolida enviaria uma requisição que você nunca pediu, com o seu dinheiro.

Listas salvas pelo terminal

Uma lista salva é um conjunto de filtros reutilizável, e não uma foto congelada. Criar uma é grátis e não revela nada.

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

As listas são compartilhadas entre as interfaces. Uma lista criada pelo seu pipeline aparece no app web, e uma que um colega monta no app fica visível para o seu pipeline. Como list status é grátis, um job agendado pode acompanhar diariamente a movimentação de um mercado sem gastar nada, o monitoramento mais barato que você vai construir.

Exportações, e o caminho de recuperação

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

O que acontece, em ordem:

1. O caminho de saída é testado quanto à permissão de gravação antes de o job ser criado, então um caminho errado nunca vai cobrar você por um arquivo que você não consegue salvar.
2. Você precisa confirmar, a menos que tenha passado -y ou --json ou que o stdin não seja um terminal.
3. O job é criado e consultado. A verificação roda neste momento, e só as linhas entregáveis são cobradas.
4. O CSV é gravado no seu caminho -o e o número de linhas é impresso.

Dois padrões que vale conhecer: has_email vem como true por padrão, para que as linhas exportadas tenham um endereço, e contatos que você já exportou são pulados, a menos que você passe --include-exported. Esse segundo padrão é o que faz uma atualização agendada trazer pessoas novas em vez de reinscrever todo mundo.

Desvio: o processo morreu no meio da exportação

Uma exportação paga nunca é irrecuperável. Se a CLI morrer depois de o job ser criado, ela imprime os comandos exatos de recuperação, e os dois são grátis:

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

Desvio: a exportação tem mais de 50,000 linhas

Acima de 50,000 linhas, o job vira um lote com várias partes. A CLI consulta o lote e grava um arquivo por parte, leads-part1.csv, leads-part2.csv e assim por diante, e imprime o id do lote para você buscá-lo de novo depois:

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

Verificando os seus próprios endereços

verify verifica endereços que você mesmo traz e custa meio crédito por verificação, do seu 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

Com um arquivo, ele extrai os endereços e remove os duplicados, envia em partes de 500 e grava um CSV com email,status,deliverable, por padrão argorant-verified.csv. O resumo informa quantos eram entregáveis, quantas verificações foram cobradas e quantas saíram de graça porque já existia um resultado recente. Se nenhum endereço for encontrado, ele aborta e sugere --column, em vez de não fazer nada em silêncio.

Contatos exportados do Argorant já são verificados no momento da exportação, então este comando é para listas que vieram de outro lugar.

Códigos de saída: o contrato com o seu pipeline

Tome decisões pelos códigos de saída, nunca pelos textos de erro.

• 0 sucesso.
• 1 erro genérico: uso incorreto, falha de rede ou um job que falhou no servidor. Algo realmente quebrou.
• 2 não autenticado. Nenhuma chave, ou a chave foi rejeitada. Corrija a credencial e tente de novo.
• 3 proibido. A chave é válida, mas não tem o escopo. Ampliar uma chave é uma decisão humana, não uma nova tentativa.
• 4 limite de requisições ou cota diária. Espere e retome depois.
• 5 é preciso pagamento ou upgrade de plano. A mensagem traz o link.

O código 5 é propositalmente diferente do 1 exatamente por isso. Um pipeline que tenta de novo um problema de pagamento em loop é um pipeline que acorda você às quatro da manhã por algo que só uma pessoa com cartão de crédito consegue resolver.

Um padrão de shell que se sustenta:

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

Os códigos correspondem diretamente aos códigos de status HTTP da API REST: 401 vira 2, 403 vira 3, 429 vira 4, 402 vira 5. Um agente que usa as duas interfaces pode compartilhar um único caminho de tratamento de erros.

Um cron job que atualiza um segmento

O formato que funciona em produção coloca todas as etapas grátis antes de todas as pagas, para que uma noite ruim não custe 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

Quatro propriedades tornam esse script seguro, e não só funcional. O limite de linhas é uma variável com nome no topo, e não um padrão escondido num comando. A verificação de status grátis roda antes de qualquer cobrança. Um problema de pagamento avisa uma pessoa em vez de tentar de novo. E um limite de requisições sai com zero, porque a execução de amanhã vai pegar o que faltou, e um build vermelho por um limite passageiro ensina as pessoas a ignorar builds vermelhos.

Coisas que vão morder você exatamente uma vez

• Achar que a confirmação vai salvar você. No CI não existe confirmação. O valor de -n é o orçamento.
• Interpretar a saída para humanos. Use --json em toda automação, desde o primeiro commit.
• Deixar ARGORANT_API_KEY definida depois de um logout. O ambiente vence, então você continua autenticado.
• Tentar de novo um código 5. Nenhuma quantidade de tentativas gera créditos.
• Rodar do zero uma exportação que falhou. Se o job foi criado, ele foi cobrado, e export download o busca de graça. Confira antes de rodar de novo.
• Compartilhar uma chave entre três pipelines. Revogue-a uma vez e você quebra os três, e nunca vai saber qual deles a vazou.

Uma última observação sobre o escopo: argorant campaigns existe, mas é uma interface interna de operação, e uma chave normal de cliente recebe 401 ou 403 ali. É o sistema funcionando corretamente, e não um bug para reportar. Para clientes, os comandos que importam são count, list, export e verify, além da integração que leva o arquivo pronto para o seu próprio sequenciador.