camoufox-cli

camoufox-cli を使用したアンチ検出ブラウザー自動化

基本的なワークフロー

すべてのブラウザー自動化は、次のパターンに従います。

1. 移動：camoufox-cli open <url>
2. スナップショット：camoufox-cli snapshot -i（@e1、@e2 などの要素参照を取得します）
3. 操作：参照を使ってクリック、入力、選択を行います
4. 再スナップショット：移動または DOM の変更後に、新しい参照を取得します
5. 閉じる：タスク全体が完了したら、他のコマンドと同じ --tab／--session フラグを付けて camoufox-cli close を実行します。ユーザーから追加の指示がある可能性がある場合は、開いたままにします。

camoufox-cli open https://example.com/form
camoufox-cli snapshot -i
# Output: - textbox "Email" [ref=e1]
#         - textbox "Password" [ref=e2]
#         - button "Submit" [ref=e3]

camoufox-cli fill @e1 "[email protected]"
camoufox-cli fill @e2 "password123"
camoufox-cli click @e3
camoufox-cli snapshot -i  # Check result

コマンドの連結

1 回のシェル呼び出しで、&& を使ってコマンドを連結できます。バックグラウンドデーモンを介してブラウザーの状態がコマンド間で維持されるため、連結しても安全で、個別に呼び出すより効率的です。

# Chain open + snapshot in one call
camoufox-cli open https://example.com && camoufox-cli snapshot -i

# Chain multiple interactions
camoufox-cli fill @e1 "[email protected]" && camoufox-cli fill @e2 "password123" && camoufox-cli click @e3

# Navigate and capture
camoufox-cli open https://example.com && camoufox-cli screenshot page.png

連結するタイミング： 中間コマンドの出力を確認せずに次へ進める場合（例：ページを開いてスクリーンショットを撮る場合）は、&& を使います。出力を解析する必要がある場合（例：スナップショットで参照を確認してから、その参照を使って操作する場合）は、コマンドを個別に実行します。

重要なコマンド

# Navigation
camoufox-cli open <url>              # Navigate to URL (starts daemon if needed)
camoufox-cli back                    # Go back
camoufox-cli forward                 # Go forward
camoufox-cli reload                  # Reload page
camoufox-cli url                     # Print current URL
camoufox-cli title                   # Print page title
camoufox-cli close                   # Close your tab (browser exits when the last tab closes)
camoufox-cli close --all             # Force-close all sessions

# Snapshot
camoufox-cli snapshot                # Full aria tree of page
camoufox-cli snapshot -i             # Interactive elements only (recommended)
camoufox-cli snapshot -s "#selector" # Scope to CSS selector

# Interaction (use @refs from snapshot)
camoufox-cli click @e1               # Click element
camoufox-cli fill @e1 "text"         # Clear + type into input
camoufox-cli type @e1 "text"         # Type without clearing (append)
camoufox-cli select @e1 "option"     # Select dropdown option
camoufox-cli check @e1               # Toggle checkbox
camoufox-cli hover @e1               # Hover over element
camoufox-cli mouse click 660 380     # Click at viewport coordinates (no ref needed)
camoufox-cli press Enter             # Press keyboard key
camoufox-cli press "Control+a"       # Key combination

# Data Extraction
camoufox-cli text @e1                # Get text content of element
camoufox-cli text body               # Get all page text (CSS selector)
camoufox-cli eval "document.title"   # Execute JavaScript

# Capture
camoufox-cli screenshot              # Screenshot as JSON {"base64": "..."}
camoufox-cli screenshot page.png     # Screenshot to file
camoufox-cli screenshot --full p.png # Full page screenshot
camoufox-cli pdf output.pdf          # Save page as PDF

# Scroll & Wait
camoufox-cli scroll down             # Scroll down 500px
camoufox-cli scroll up               # Scroll up 500px
camoufox-cli scroll down 1000        # Scroll down 1000px
camoufox-cli wait @e1                # Wait for element to appear
camoufox-cli wait 2000               # Wait milliseconds
camoufox-cli wait --url "*/dashboard" # Wait for URL pattern

# Tabs
camoufox-cli tabs                    # List open tabs (with owner names)
camoufox-cli switch 2                # Switch to tab by index
camoufox-cli --tab <unique-name> open <url> # Named tab: shared browser + login, own page/refs

# Cookies & State
camoufox-cli cookies                 # Dump cookies as JSON
camoufox-cli cookies import file.json # Import cookies
camoufox-cli cookies export file.json # Export cookies

# Sessions
camoufox-cli sessions                # List active sessions
camoufox-cli --session work open <url> # Use named session
camoufox-cli close --all             # Force-close all sessions

# Setup
camoufox-cli install                 # Download Camoufox browser
camoufox-cli install --with-deps     # Download browser + system libs (Linux)

よく使うパターン

フォームの送信

camoufox-cli open https://example.com/signup
camoufox-cli snapshot -i
camoufox-cli fill @e1 "Jane Doe"
camoufox-cli fill @e2 "[email protected]"
camoufox-cli select @e3 "California"
camoufox-cli check @e4
camoufox-cli click @e5
camoufox-cli snapshot -i  # Verify submission result

データの抽出

camoufox-cli open https://example.com/products
camoufox-cli snapshot -i
camoufox-cli text @e5                # Get specific element text
camoufox-cli eval "document.title"   # Get page title via JS
camoufox-cli screenshot results.png  # Visual capture

Cookie の管理（ログイン状態の維持）

# Login and export cookies
camoufox-cli open https://app.example.com/login
camoufox-cli snapshot -i
camoufox-cli fill @e1 "user"
camoufox-cli fill @e2 "pass"
camoufox-cli click @e3
camoufox-cli cookies export auth.json

# Restore in future session
camoufox-cli open https://app.example.com
camoufox-cli cookies import auth.json
camoufox-cli reload

Cookie だけでなくデバイスの安定性もサイトが確認する長期利用アカウントの場合は、これに --persistent を組み合わせて、Cookie とともにフィンガープリントも固定します。詳しくは、下記の「永続的な ID」セクションを参照してください。

複数のタブ

camoufox-cli open https://site-a.com
camoufox-cli eval "window.open('https://site-b.com')"
camoufox-cli tabs                    # List tabs
camoufox-cli switch 1                # Switch to second tab
camoufox-cli snapshot -i

並列タブ（ID を共有する単一ブラウザー）

名前付きタブは、セッション内で同じブラウザーを共有します。つまり、フィンガープリントと Cookie／ログイン状態は共通ですが、各タブはそれぞれ独自のページ、要素参照、移動履歴を保持するため、並行して動作するエージェント同士が互いの状態を上書きすることはありません。これは並列化する低コストな方法です。Firefox は 1 つだけ起動し、タブを追加するごとに必要なメモリはおよそ 50～150MB です。

camoufox-cli --tab inbox-scan-x4q open https://app.example.com/inbox
camoufox-cli --tab report-pull-9kf open https://app.example.com/reports
camoufox-cli --tab inbox-scan-x4q snapshot -i   # refs are per tab
camoufox-cli tabs                               # Lists every tab with its owner name
camoufox-cli --tab inbox-scan-x4q close         # Frees only this tab; browser stays for the others

タブ名の決め方。 一意性は強制されません。同じ名前を使う 2 つのエージェントは同じページポインターを共有するため、互いの状態を上書きします。タスクの開始時に、タブ名を 1 回生成してください。具体的なタスク名を短いスラッグにし、シェルで生成したランダムなサフィックスを付けます。サフィックスを自分で考えてはいけません。LLM が「ランダム」に生成した文字列には偏りがあり、並行して動作するエージェント同士で同じ名前になる可能性があります。その後のすべてのコマンドでは、出力された名前をそのまま再利用してください。（指示でタブ名が明示的に割り当てられている場合は、そちらを使ってください。）

TAB="price-scan-$(openssl rand -hex 2)" && echo "$TAB" && camoufox-cli --tab "$TAB" open https://example.com
# prints e.g. price-scan-9f3c — use that exact name in every later command:
camoufox-cli --tab price-scan-9f3c snapshot -i

サブエージェントに同じ ID として動作させる場合（例：すべてのエージェントが同じログイン済みアカウントを操作する場合）は、タブを使います。クリーンアップの調整は不要です。各エージェントは、自分のタブを指定して close を実行します（camoufox-cli --tab <name> close）。これにより、そのタブだけが解放され、最後のタブが閉じるとブラウザーは自動的に終了します。

タブは同じブラウザープロセスを共有するため、別々のタブからのコマンドは、時間のかかる移動や wait の完了を待つ場合があります。別々のセッションは独立したプロセスとして動作し、完全に並列実行されます。コマンドを非常に多く実行するエージェントが複数いる場合は、それらには独自のセッションを割り当て、残りにはタブを使うことを検討してください。

並列セッション（分離された ID）

名前付きセッションごとに別のブラウザープロセスが起動し、それぞれが独自のランダム生成フィンガープリントと Cookie を持ちます。エージェント間で ID を共有してはならない場合（複数アカウントの作業など）に使います。セッションごとに Firefox 1 つ分（約 300～500MB）のコストがかかります。

camoufox-cli --session s1 open https://site-a.com
camoufox-cli --session s2 open https://site-b.com
camoufox-cli sessions                # List both
camoufox-cli --session s1 snapshot -i
camoufox-cli --session s2 snapshot -i

セッションを分けるだけでは、ブラウザー側が分離されるにすぎません。精査に耐える必要がある複数アカウントの作業では、各セッションに独自のプロキシ（サイトは IP アドレスでアカウントを関連付けます。設定ファイルの sessions.<name>.proxy を使います）と --persistent も指定してください。指定しない場合は、起動のたびにフィンガープリントが再ランダム化され、ログインのたびに新しいデバイスとして認識されます。

ビジュアルブラウザー（デバッグ）

camoufox-cli --headed open https://example.com
camoufox-cli snapshot -i
camoufox-cli screenshot debug.png

セッション管理とクリーンアップ

複数のエージェントや自動化を同時に実行する場合は、競合しないように各エージェントに個別の名前を付けてください。分離レベルは次の2つです。

• --tab <name>（IDを共有。推奨されるデフォルト）：すべてのエージェントで1つのブラウザーを共有します。同じフィンガープリントとログイン状態を使いますが、それぞれ独立したタブが割り当てられます。低コストです。Firefoxは1つだけです。
• --session <name>（IDを分離）：各エージェントに、独自のフィンガープリントとCookieを持つブラウザーが割り当てられます。コストがかかります。セッションごとにFirefoxを1つ起動します。IDを分ける必要がある場合にのみ使用してください。

# Shared identity: 3 agents, one browser, one login
camoufox-cli --tab orders-audit-p2m open https://app.example.com/a
camoufox-cli --tab user-export-j8w open https://app.example.com/b
camoufox-cli --tab billing-check-r4t open https://app.example.com/c

# Isolated identities: 2 agents, two browsers
camoufox-cli --session shop-a-buyer open https://site-a.com
camoufox-cli --session shop-b-buyer open https://site-b.com
camoufox-cli sessions                  # Check active sessions

名前は単なる文字列で、一意性は強制されません。上記の「タブ名の選び方」のルール（タスクのスラッグ＋シェルで生成したランダムなサフィックスを、一度だけ選ぶ）に従ってください。セッション名にも同じルールが適用されます。

プロセスが残らないよう、終了時には必ずcloseを実行してください。closeはコマンドの対象であるタブを解放するため、ほかのコマンドと同じ--tab／--sessionフラグを指定してください。最後のタブを閉じるとブラウザーが終了するため、ほかのエージェントのことを知らなくても、各エージェントは同じ方法でクリーンアップできます。

camoufox-cli --tab orders-audit-p2m close       # Free this tab; browser exits if it was the last
camoufox-cli close                              # Same, for the default tab
camoufox-cli --session shop-a-buyer close       # Same, within a named session
camoufox-cli close --all                        # Force-close all sessions (cleanup escape hatch)

前のセッションが正しく閉じられていない場合、デーモンがまだ実行中の可能性があります。新しい作業を始める前に、camoufox-cli close（またはclose --all）を使ってクリーンアップしてください。

タイムアウトと遅いページ

特に動的コンテンツや大量のJavaScriptを含むページは、完全に読み込まれるまで時間がかかることがあります。スナップショットを取得する前に、明示的に待機してください。

# Wait for a specific element to appear
camoufox-cli wait @e1
camoufox-cli snapshot -i

# Wait for a URL pattern (useful after redirects)
camoufox-cli wait --url "*/dashboard"
camoufox-cli snapshot -i

# Wait a fixed duration as a last resort
camoufox-cli wait 3000
camoufox-cli snapshot -i

遅いページを扱う場合は、スナップショットを取得する前に必ず待機してください。早すぎるタイミングでスナップショットを取得すると、出力に要素が含まれないことがあります。

Refのライフサイクル（重要）

Ref（@e1、@e2など）は、スナップショットごとに連番で割り当てられる一時的な識別子です。ページが変化すると無効になります。

次の場合は必ずスナップショットを再取得してください。

• ページ遷移が発生するリンクやボタンをクリックした後
• フォームを送信した後
• 動的コンテンツ（ドロップダウン、モーダル、遅延読み込みコンテンツ）が読み込まれた後
• 新しいコンテンツが表示されるスクロールを行った後

# CORRECT: re-snapshot after navigation
camoufox-cli click @e5              # Navigates to new page
camoufox-cli snapshot -i            # MUST re-snapshot
camoufox-cli click @e1              # Use new refs

# CORRECT: re-snapshot after dynamic changes
camoufox-cli click @e1              # Opens dropdown
camoufox-cli snapshot -i            # See dropdown items
camoufox-cli click @e7              # Select item

# WRONG: using refs without snapshot
camoufox-cli open https://example.com
camoufox-cli click @e1              # Ref doesn't exist yet!

# WRONG: using old refs after navigation
camoufox-cli click @e5              # Navigates away
camoufox-cli click @e3              # STALE REF - wrong element!

ページ遷移後やページ変更後に要素を操作する前に、必ず新しいスナップショットを取得してください。

トラブルシューティング

「Ref @eN が見つかりません」

Refが無効になっています。新しいRefを取得するために、スナップショットを再取得してください。

camoufox-cli snapshot -i

スナップショットに要素が表示されない

# Scroll down to reveal element
camoufox-cli scroll down 1000
camoufox-cli snapshot -i

# Or wait for dynamic content
camoufox-cli wait 2000
camoufox-cli snapshot -i

画面には要素が表示されるが、スナップショットには表示されない

クロスオリジンのiframe内にあるチェックボックス（たとえば、Cloudflare Turnstileの 「人間であることを確認してください」ウィジェット）にはRefがありません。スクリーンショットで見つけ、 座標を使ってクリックしてください。座標はビューポートのCSSピクセル単位です。デフォルトの devicePixelRatioが1の場合、--fullを付けないスクリーンショットのピクセルと同じです。

camoufox-cli screenshot page.png     # Locate the checkbox in the image
camoufox-cli mouse click 660 380     # Click its center
camoufox-cli wait 3000
camoufox-cli screenshot page.png     # Confirm the check passed

スナップショットの要素が多すぎる

# Scope to a specific container
camoufox-cli snapshot -s "#main-content"
camoufox-cli snapshot -i -s "form.login"

ページが完全に読み込まれていない

# Wait for URL pattern after redirect
camoufox-cli wait --url "*/dashboard"
camoufox-cli snapshot -i

# Wait a fixed duration as last resort
camoufox-cli wait 3000
camoufox-cli snapshot -i

グローバルフラグ

--session <name>       Named session (default: "default")
--tab <name>           Named tab within the session's shared browser: same
                       fingerprint and cookies/login, independent page/refs/
                       history (default: "default")
--headed               Show browser window (default: headless)
--timeout <seconds>    Daemon idle timeout (default: 1800)
--json                 Output as JSON instead of human-readable
--persistent [path]    Persistent identity — reuse the same fingerprint + cookies across launches
                       (default path: ~/.camoufox-cli/profiles/<session>)
--proxy <url>          Proxy server (http:// or https://; auth: http://user:pass@host:port)
--no-geoip             Disable automatic GeoIP spoofing (auto-enabled with --proxy)
--locale <tag>         Force browser locale (e.g. "en-US" or "en-US,zh-CN")
--version              Print version and exit

設定ファイル（任意）。 フラグの繰り返しを避けるには、~/.camoufox-cli/config.json（$CAMOUFOX_CLI_CONFIGでパスを上書きできます）にデフォルト値を設定してください。defaultブロックはすべてのセッションに適用され、任意のsessions.<name>ブロックは--session <name>を実行するたびに、追加の上書き設定を重ねて適用します（名前は--sessionに渡した値であり、セッションを事前登録する必要はありません）。設定可能なキー：proxy、locale、geoip、persistent（true／false／パス）、headed、timeout、json。コマンドラインのフラグは常にファイルの設定より優先されます。設定は、セッションのデーモンが最初に起動するときにのみ読み込まれます。

{
  "default": { "persistent": true, "timeout": 3600 },
  "sessions": { "<your-session-name>": { "proxy": "socks5://127.0.0.1:1080", "locale": "zh-CN" } }
}

永続的な ID

デフォルトでは、起動するたびに新しいランダムなフィンガープリントが生成されます。--persistent [path] を追加すると、起動間で同じフィンガープリントと Cookie を再利用できます。フィンガープリント／OS／キャンバスとフォントのシード値は初回起動時に固定されます（リセットするにはディレクトリを削除してください）。--locale とプロキシから取得したタイムゾーン／位置情報は保存されますが、このフラグを指定するたびに更新されます。--proxy／--no-geoip は保存されないため、起動のたびに指定してください。

使用する場合：アカウントに紐づくタスク、並行して使用する独立した ID、またはサイトがデバイスの一貫性も確認するため cookies import/export だけでは不十分な場合など、訪問をまたいで同じデバイスに同じフィンガープリントを認識させる必要があるときです。使用しない場合：単発のスクレイピングや手早いデバッグでは不要です。

# Parallel identities, each with its own fingerprint + cookies
camoufox-cli --session a --persistent ~/.camoufox-cli/profiles/alice open https://app.example.com
camoufox-cli --session b --persistent ~/.camoufox-cli/profiles/bob   open https://app.example.com

# Reset an identity: just remove the directory
rm -rf ~/.camoufox-cli/profiles/alice

ドキュメント

• camoufox-cli のドキュメント -- README、セットアップガイド、インストール方法、コマンドリファレンス一式