CLI는 웹 앱과 MCP 커넥터가 쓰는 것과 같은 REST API를 감싼, 의존성 없는 도구예요. 리스트 구축이 누군가 화요일에 한 번 하는 일이 아니라 반복 워크플로의 일부일 때를 위해 존재해요. 매일 밤 갱신, CRM을 최신으로 유지하는 CI 단계, 기계가 읽을 수 있는 답이 필요한 에이전트 루프 같은 경우요. 이 가이드는 돈이 드는 부분과 의도보다 더 쓸 수 없는 실행의 정확한 형태까지 포함해 그 전체 경로를 안내해요.
먼저 새겨 둘 규칙 하나
어떤 명령을 쓰든 먼저: reveal, export, verify --file은 stdin이 터미널이고 동시에 -y와 --json을 둘 다 넘기지 않았을 때만 확인을 요청해요. CI, 파이프, 에이전트 루프 안에서는 확인 요청이 전혀 없고, 이 명령들은 바로 크레딧을 써요.
확인 요청은 사람을 위한 편의 기능일 뿐, 절대 안전망이 아니에요. 실제로 지출을 통제하는 건 -n에 넘기는 숫자예요. 그러니 실행하기 전에 그 숫자를 읽으세요. 아무도 지켜보지 않는 스크립트라면 더더욱요.
설치와 첫 실행
원하지 않으면 설치할 필요가 없어요.
npx argorant count "fintech CFOs in germany"또는 전역으로 설치하세요. 패키지 이름은 argorant예요.
npm install -g argorant
키 관리, 그리고 어떤 자격 증명이 우선하는지
CLI는 프로필, API 키에서 만든 ag_live_ 키를 받아요. 키를 넘기는 방법은 세 가지이고, 엄격한 우선순위가 있어요.
대화형: 내 컴퓨터에서
npx argorant login입력을 가린 채 키를 묻고, 계정 엔드포인트로 키를 검증한 뒤 저장해요. 거부된 키는 저장됐다가 나중에 돈이 드는 명령에서 실패하는 대신, 즉시 명확한 메시지와 함께 실패해요. argorant login <key>처럼 한 줄로 넘길 수도 있어요.
환경 변수: CI와 에이전트용
export ARGORANT_API_KEY=ag_live_...스크립트, 파이프라인, 에이전트에 맞는 방식이에요. 디스크에 아무것도 쓰지 않고, 실행할 때마다 변수를 읽어요.
우선순위
- 환경 변수
ARGORANT_API_KEY가 모든 것보다 우선해요. - 그렇지 않으면
argorant login이 저장한 키를 써요. 키는~/.argorant/config.json에0600권한으로 저장돼요. - 둘 다 없으면 명령은 종료 코드
2로 끝나고 로그인하라고 알려 줘요.
argorant logout은 설정 파일을 지워요. ARGORANT_API_KEY가 아직 설정돼 있으면 CLI가 경고해요. 그 변수가 우선해서 계속 인증된 상태로 남기 때문이에요. 그 변수도 해제하세요.
파이프라인을 위한 키 관리 습관
- 파이프라인이나 에이전트마다 키 하나. 사용 내역을 추적할 수 있고, 하나를 폐기해도 다른 것이 깨지지 않아요.
- 키는 CI 비밀 저장소에 두세요. 커밋된 파일에도, 공유 채팅에도 절대 넣지 마세요. 채팅 기록은 내보내지고 스크린샷으로 찍혀요. 이미 그랬다면 지금 바로 교체하세요.
- 중단 없이 교체하기: 새 키를 만들어 배포하고,
npx argorant whoami로 확인한 뒤, 이전 키를 폐기하세요. 폐기는 즉시 적용되고, 그 키로 보낸 다음 요청은 401로 실패해요.
닳도록 써야 할 무료 명령
count는 세그먼트의 크기를 돌려줘요. search는 신원을 가린 채 일치하는 사람을 돌려줘요. company는 특정 계정에 닿을 수 있는지를 알려 줘요. 어느 것도 연락처 크레딧을 차감하지 않아요. 계정 권한, 할당량, 속도 제한은 적용돼요.
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
어떤 명령이든 --json을 붙이면 기계가 읽을 수 있는 출력이 나와요. 스크립트와 에이전트는 항상 이걸 써야 해요. 필드 이름은 안정적이지만 사람용 형식은 그렇지 않고, 보기 좋은 출력을 파싱하는 순간 업그레이드 때 파이프라인이 조용히 깨져요.
필터는 검색 형태의 모든 명령에서 공통이라, count에서 익힌 내용은 search, reveal, export, 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는 가장 넓고 믿을 만한 입구예요. 쉼표는 OR을 뜻하고, 대체로 --industry보다 나아요. --country와 --geography는 같은 필터이고 Europe, EMEA, DACH, Nordics, APAC, LATAM, GCC 같은 지역도 받아요.
플래그 두 개는 이름과 다르게 동작하는데, CLI는 그런 척하지 않고 알려 줘요. --exclude-title은 export와 list create에서는 완전히 적용되지만, count, search, reveal에서는 아직 적용되지 않고 stderr에 안내가 나가요. --grade는 엄격한 도달 가능 세트와 캐치올을 포함한 더 넓은 세트 중에서 고르고, reveal과 export까지 처음부터 끝까지 연결돼 있지만, 플랫폼이 아직 그 값으로 좁히지 않아서 CLI가 적용했다고 주장하지 않고 경고해요.
파싱 안전장치 두 개는 항상 켜져 있어요. 숫자가 아닌 -n은 기본 한도로 돌아가지 않고 중단돼요. 값을 받는 플래그 뒤에 다른 플래그가 오면 그걸 삼키지 않고 중단돼요. 둘 다 존재하는 이유는, 삼켜진 플래그가 내 돈으로 요청하지도 않은 요청을 보내게 되기 때문이에요.
터미널에서 저장된 리스트 쓰기
저장된 리스트는 고정된 스냅샷이 아니라 다시 쓸 수 있는 필터 세트예요. 만드는 데 비용이 들지 않고 아무것도 공개하지 않아요.
npx argorant list create --name "DACH CFOs 200+" --title CFO --country DACH
npx argorant list status 42
리스트는 모든 화면에서 공유돼요. 파이프라인이 만든 리스트는 웹 앱에 나타나고, 동료가 앱에서 만든 리스트는 파이프라인에서도 보여요. list status는 무료라서, 예약 작업이 한 푼도 쓰지 않고 매일 시장 변화를 지켜볼 수 있어요. 이보다 싼 모니터링은 없을 거예요.
내보내기, 그리고 복구 경로
npx argorant export "fintech CFOs" --country Germany -n 1000 -o leads.csv순서대로 일어나는 일이에요.
- 작업을 만들기 전에 출력 경로에 쓸 수 있는지 확인해서, 잘못된 경로 때문에 저장할 수 없는 파일 값을 청구받는 일이 없어요.
-y나--json을 넘겼거나 stdin이 터미널이 아니면 확인을 묻지 않고, 그 외에는 확인을 요청해요.- 작업이 만들어지고 진행 상태를 확인해요. 검증은 이 순간 실행되고, 도달 가능한 행에만 과금돼요.
- CSV가
-o경로에 저장되고 행 수가 출력돼요.
알아 둘 기본값이 두 가지 있어요. has_email은 기본값이 true라서 내보낸 행에 주소가 들어 있고, 이미 내보낸 연락처는 --include-exported를 넘기지 않으면 건너뛰어요. 이 두 번째 기본값 덕분에 예약 갱신이 모든 사람을 다시 등록하지 않고 새 사람만 돌려줘요.
갈림길: 내보내기 도중 프로세스가 죽었을 때
유료 내보내기는 절대 복구 불가능하지 않아요. 작업이 만들어진 뒤 CLI가 죽으면 정확한 복구 명령을 출력하고, 둘 다 무료예요.
npx argorant export status 12345
npx argorant export download 12345 -o leads.csv갈림길: 내보내기가 50,000행을 넘을 때
50,000행을 넘으면 작업이 여러 조각으로 된 배치가 돼요. CLI는 배치를 확인하며 조각마다 파일을 하나씩 쓰고(leads-part1.csv, leads-part2.csv 등), 나중에 다시 받을 수 있도록 배치 ID를 출력해요.
npx argorant export status 987 --batch
npx argorant export download 987 --batch -o leads.csv내 주소 검증하기
verify는 직접 가져온 주소를 확인하고, 일반 잔액에서 검증 1건당 0.5크레딧이 들어요.
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파일을 넣으면 주소를 추출해 중복을 제거하고, 500개씩 나눠 보내고, email,status,deliverable 열이 있는 CSV를 써요. 기본 파일명은 argorant-verified.csv예요. 요약에는 도달 가능한 주소 수, 과금된 검증 수, 최근 결과가 이미 있어서 무료였던 수가 나와요. 주소를 하나도 찾지 못하면 조용히 아무것도 하지 않는 대신 중단하고 --column을 쓰라고 제안해요.
Argorant에서 내보낸 연락처는 이미 내보낼 때 검증됐으니, 이 명령은 다른 곳에서 가져온 리스트를 위한 거예요.
종료 코드: 파이프라인과의 약속
오류 문자열이 아니라 종료 코드로 분기하세요.
0성공.1일반 오류: 잘못된 사용법, 네트워크 실패, 서버에서 실패한 작업. 무언가 실제로 고장 난 거예요.2인증되지 않음. 키가 없거나 거부됐어요. 자격 증명을 고친 뒤 다시 시도하세요.3금지됨. 키는 유효하지만 범위가 부족해요. 키의 범위를 넓히는 건 재시도가 아니라 사람이 내릴 결정이에요.4속도 제한 또는 일일 할당량. 물러났다가 나중에 다시 시작하세요.5결제 또는 플랜 업그레이드 필요. 메시지에 링크가 담겨 있어요.
코드 5를 1과 일부러 구분한 이유가 바로 그거예요. 결제 문제를 루프에서 재시도하는 파이프라인은, 신용카드를 가진 사람만 고칠 수 있는 문제로 새벽 4시에 당신을 깨우는 파이프라인이에요.
안정적으로 버티는 셸 패턴이에요.
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이 코드는 REST API의 HTTP 상태 코드와 바로 대응해요. 401은 2, 403은 3, 429는 4, 402는 5가 돼요. 두 방식을 모두 쓰는 에이전트는 오류 처리 경로 하나를 공유할 수 있어요.
세그먼트를 갱신하는 cron 작업
운영 환경에서 잘 작동하는 구조는 모든 무료 단계를 모든 유료 단계 앞에 둬서, 운 나쁜 밤에도 비용이 들지 않게 해요.
#!/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>&1이 스크립트를 단지 작동하는 수준이 아니라 안전하게 만드는 특성이 네 가지 있어요. 행 한도는 명령 속에 묻힌 기본값이 아니라 맨 위에 이름 붙인 변수로 둬요. 무료 상태 확인이 과금 전에 실행돼요. 결제 문제는 재시도하지 않고 사람에게 알려요. 그리고 속도 제한은 0으로 종료해요. 내일 실행이 이어받을 거고, 일시적인 제한으로 빌드가 빨갛게 뜨면 사람들이 빨간 빌드를 무시하는 버릇이 들기 때문이에요.
딱 한 번은 꼭 당하게 되는 실수들
- 확인 요청이 지켜 줄 거라고 믿기. CI에는 확인 요청이 없어요.
-n값이 곧 예산이에요. - 사람용 출력 파싱하기. 자동화에서는 첫 커밋부터 어디서나
--json을 쓰세요. - 로그아웃 후에도
ARGORANT_API_KEY를 남겨 두기. 환경 변수가 우선하니 여전히 인증된 상태예요. - 코드 5를 재시도하기. 아무리 재시도해도 크레딧은 생기지 않아요.
- 실패한 내보내기를 처음부터 다시 돌리기. 작업이 만들어졌다면 이미 과금됐고,
export download로 무료로 받을 수 있어요. 다시 돌리기 전에 확인하세요. - 파이프라인 세 개에 키 하나를 같이 쓰기. 한 번 폐기하면 셋이 모두 깨지고, 어디서 유출됐는지 끝내 알 수 없어요.
범위에 관해 마지막으로 하나. argorant campaigns는 존재하지만 내부 운영자용 기능이라, 일반 고객 키로는 401이나 403이 나와요. 버그가 아니라 시스템이 제대로 작동하는 거예요. 고객에게 중요한 명령은 count, list, export, verify, 그리고 완성된 파일을 내 시퀀서로 보내는 연동이에요.
