CLIは、WebアプリとMCPコネクタが使っているのと同じREST APIを、依存関係なしで包んだラッパーです。リスト作成が、誰かが火曜日に手作業で行うものではなく、繰り返しのワークフローの一部である場合のためにあります。たとえば毎晩の更新、CRMを最新に保つCIのステップ、機械が読める答えを必要とするエージェントのループです。このガイドでは、費用がかかる部分や、意図した以上に費用を使えない実行の正確な形も含め、その全体の流れを説明します。
最初に身につけるべき1つのルール
どのコマンドよりも先に知っておくべきことがあります。reveal、export、verify --fileが確認を求めるのは、stdinがターミナルで、かつ-yも--jsonも指定していない場合だけです。CIやパイプの中、エージェントのループの中では確認は一切表示されず、これらのコマンドは即座に費用を使います。
確認のプロンプトは人のための便利機能であって、安全装置ではありません。実際に支出を決めるのは -n に渡す数値です。特に、誰も見ていないスクリプトで実行する場合は、実行前に必ずこの値を確認してください。
インストールと初回の実行
インストールしたくなければ、何もインストールする必要はありません：
npx argorant count "fintech CFOs in germany"グローバルにインストールすることもできます。パッケージ名は argorant です：
npm install -g argorant
キーの管理と、どの認証情報が優先されるか
CLIでは ag_live_ で始まるキーを使います。キーはプロフィールの「APIキー」で作成します。キーを渡す方法は3つあり、厳密な優先順位があります。
自分のマシンでは対話形式で
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は警告を表示します。この変数が優先されるため、認証された状態が続いてしまうからです。変数も削除してください。
パイプラインでのキーの安全な管理
- パイプラインやエージェントごとにキーを1つ。利用状況を追跡でき、1つを取り消してもほかに影響しません。
- キーは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などの地域も指定できます。
名前から想像するのとは動きが異なるフラグが2つあり、CLIはそれをごまかさずに伝えます。--exclude-title は export と list create では完全に適用されますが、count、search、reveal ではまだ適用されず、stderrに注記が出力されます。--grade は、厳格な到達可能のみの集合と、キャッチオールを含む広い集合のどちらにするかを選ぶもので、reveal と export では最後までつながっていますが、プラットフォーム側ではまだこの値で絞り込まないため、CLIは絞り込んだふりをせずに警告を表示します。
解析時の安全策が2つ、常に有効です。数値でない -n は既定の上限に戻さずに処理を中止し、値を取るフラグの後に別のフラグが続いた場合も、それを値として飲み込まずに中止します。どちらも、飲み込まれたフラグのせいで、頼んでもいないリクエストが自分のお金で送られるのを防ぐためにあります。
ターミナルから保存したリスト
保存したリストは、固定したスナップショットではなく、再利用できるフィルターの組み合わせです。作成は無料で、連絡先が表示されることもありません。
npx argorant list create --name "DACH CFOs 200+" --title CFO --country DACH
npx argorant list status 42
リストは画面をまたいで共有されます。パイプラインで作ったリストはWebアプリに表示され、同僚がアプリで作ったリストはパイプラインからも見えます。list status は無料なので、スケジュール実行のジョブで市場の動きを毎日、費用をかけずに見守れます。これほど安い監視の仕組みはほかにありません。
エクスポートと復旧の手順
npx argorant export "fintech CFOs" --country Germany -n 1000 -o leads.csv処理は次の順に進みます：
- ジョブを作成する前に、出力先のパスに書き込めるかを確認します。そのため、保存できないファイルに課金されることはありません。
-yや--jsonを指定した場合、または標準入力がターミナルでない場合を除き、確認を求められます。- ジョブが作成され、完了まで状態を確認します。メールチェックはこの時点で行われ、課金されるのは到達可能な行だけです。
- CSVが
-oで指定したパスに保存され、行数が表示されます。
知っておきたい既定値が2つあります。has_email は既定でtrueのため、エクスポートした行にはアドレスが入っています。また、すでにエクスポートしたコンタクトは、--include-exported を指定しない限りスキップされます。2つ目のおかげで、定期的な更新では全員を登録し直すのではなく、新しい人だけが返ってきます。
ケース：エクスポートの途中でプロセスが止まった
有料のエクスポートが復旧できなくなることはありません。ジョブの作成後に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 のようにチャンクごとに1つのファイルを書き出します。後でもう一度取得できるよう、バッチ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 です。サマリーには、到達可能だった件数、課金されたチェックの件数、最近の結果がすでにあったため無料になった件数が表示されます。アドレスが1件も見つからない場合は、黙って何もしないのではなく処理を中止し、--column の指定を提案します。
Argorantからエクスポートしたコンタクトはエクスポート時にすでにチェック済みなので、このコマンドはほかから入手したリストに使います。
終了コード：パイプラインとの約束
分岐はエラーの文言ではなく、必ず終了コードで行います。
0成功。1一般的なエラー。使い方の誤り、ネットワークの障害、サーバー側でのジョブの失敗です。実際に何かが壊れています。2未認証。キーがないか、キーが拒否されました。認証情報を直してから再試行してください。3権限なし。キーは有効ですが、必要な権限範囲がありません。キーの権限を広げるのは人が判断することで、再試行で解決するものではありません。4レート制限、または1日の利用上限。間隔を空けて、後で再開してください。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 です。両方を使うエージェントでも、エラー処理を1つにまとめられます。
セグメントを更新する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このスクリプトが単に動くだけでなく安全なのは、4つの特徴があるからです。行数の上限が、コマンドの奥に埋もれた既定値ではなく、冒頭の名前付きの変数になっていること。課金の前に無料のステータス確認を行うこと。支払いの問題は再試行せずに人に知らせること。そして、レート制限では終了コード0で終わること。翌日の実行が引き継ぐからであり、一時的な制限でビルドを赤くすると、人は赤いビルドを無視するようになるからです。
一度は必ずやってしまう失敗
- 確認のプロンプトが守ってくれると思い込む。CIにはプロンプトがありません。
-nの値が予算そのものです。 - 人向けの出力を解析する。自動化では、最初のコミットからどこでも
--jsonを使ってください。 - ログアウト後も
ARGORANT_API_KEYを設定したままにする。環境変数が優先されるので、認証された状態が続きます。 - 終了コード5を再試行する。何度再試行してもクレジットは増えません。
- 失敗したエクスポートを最初からやり直す。ジョブが作成されていれば課金済みで、
export downloadで無料で取得できます。やり直す前に確認してください。 - 3つのパイプラインで1つのキーを共有する。一度取り消せば3つとも止まり、どこから漏れたのかもわかりません。
最後に範囲について一言。argorant campaigns というコマンドもありますが、これは社内の運用担当者向けで、通常の顧客のキーでは401や403が返ります。これはシステムが正しく動いている結果であり、報告すべき不具合ではありません。顧客にとって重要なコマンドは、count、list、export、verify、そして完成したファイルを自社のシーケンサーに送る連携です。
