
2026/01/14 23:34
**Show HN:Webctl — コマンドラインベースで動作し、MCPではなくCLIを利用したエージェント向けブラウザ自動化ツール**
RSS: https://news.ycombinator.com/rss
要約▶
日本語訳:
Webctl は、Playwright のブラウザ自動化エンジンをラップした軽量なコマンドラインインターフェースです。
start・navigate・click・type・select・wait・stop --daemon などの基本コマンドを提供し、ユーザーは「クリックボタン」や「ページへ移動」といった意味的なクエリを発行できます。Webctl は ARIA ロール(例:
role=button name~="Submit")による 意味的要素ターゲティング をサポートし、CSS の変更に対しても安定した要素選択が可能です。出力は
--interactive-only・--limit・--within・--roles などのフラグでフィルタリングでき、grep や jq といった Unix ツールへパイプできます。セッションはローカルプロファイルディレクトリ(
~/.local/share/webctl/profiles/)にクッキーを永続化するため、再ログインせずに同じ状態で次回実行が可能です。CLI はステートレスであり、JSON‑RPC を介して Chromium と Playwright のセッションを管理するデーモンと通信します。これによりスクリプト作成、CI 統合、および AI エージェントのトリガーが容易になります。
デバッグユーティリティとして
webctl console・webctl status・webctl query があり、提案やエラー出力を確認できます。インストールには Python 3.11+ が必要で、
pip install webctl を実行すると Chromium と Playwright の依存関係が自動的に取得されます(またはソースから uv sync && uv run webctl setup を使用)。Linux ユーザーは playwright install-deps chromium を実行する必要があります。今後の計画として、並列実行サポート、より AI 専用のフック(
init・agent-prompt)の追加、およびアイドルタイムアウトなど拡張設定オプションが予定されています。Webctl は MIT ライセンスでリリースされています。
本文
webctl ― コマンドラインブラウザ自動化
速やかな始め方
pip install webctl # Python 3.11以上が必要です webctl setup # Chromium(約150 MB)をダウンロードします
インストール確認:
webctl start webctl navigate "https://example.com" webctl snapshot --interactive-only webctl stop --daemon
ソースからの場合:
git clone https://github.com/cosinusalpha/webctl cd webctl uv sync && uv run webctl setup
Linux の依存パッケージ
playwright install-deps chromium # もしくは手動で: sudo apt-get install libnss3 libatk1.0-0 libatk-bridge2.0-0 …
コアコンセプト
| 機能 | CLI | MCP |
|---|---|---|
| 出力フィルタ | 既定フラグ + // | サーバー側で決定 |
| デバッグ | エージェントと同じコマンドを実行 | 不透明 |
| キャッシュ | (各呼び出しでサーバーへアクセス) | — |
| スクリプト | へ保存、バージョン管理、揮発性 | — |
| タイムアウト | (内部のみ) | サーバー依存 |
| 並列実行 | ・・ | サーバー依存 |
| 人間介入 | 同じコマンド、異なるインタフェース | — |
セッション
- ブラウザはコマンド間で開いたままで、クッキーがディスクに永続化されます。
webctl start # 可視ブラウザ webctl start --mode unattended # ヘッドレス webctl -s work start # 名前付きプロファイル(別々のクッキー) webctl stop --daemon # 全てをシャットダウン
要素検索
ARIA ロールに基づくセマンティックターゲティングで、CSS リファクタリングに強い。
| 構文 | 例 |
|---|---|
| 任意のボタン |
| 完全一致 |
| 部分一致(推奨) |
| 入力フィールド |
| リンク |
出力制御
webctl snapshot # 人間が読みやすい形式 webctl --quiet navigate "…" # イベントを抑制 webctl --result-only --format jsonl navigate "…"
コマンド一覧
ナビゲーション
| コマンド | 説明 |
|---|---|
| URLへ移動 |
| 履歴を戻る |
| 履歴を進む |
| ページをリロード |
観測
| コマンド | 説明 |
|---|---|
| 完全なアクセシビリティツリー |
| ボタン・リンク・入力のみ |
| 出力を制限 |
| コンテナ内に限定 |
| ロールでフィルタ |
| デバッグ用クエリ、提案取得 |
| スクリーンショット |
インタラクション
webctl click 'role=button name~="Submit"' webctl type 'role=textbox name~="Email"' "user@example.com" webctl type 'role=textbox name~="Search"' "query" --submit # タイプ+Enter webctl select 'role=combobox name~="Country"' --label "Germany" webctl check 'role=checkbox name~="Remember"' webctl press Enter webctl scroll down webctl upload 'role=button name~="Upload"' --file ./doc.pdf
待機条件
webctl wait network-idle webctl wait 'exists:role=button name~="Continue"' webctl wait 'visible:role=dialog' webctl wait 'hidden:role=progressbar' webctl wait 'url-contains:"/dashboard"'
セッション管理
| コマンド | 説明 |
|---|---|
| 現在の状態(コンソールエラー数を含む) |
| クッキーを今すぐ永続化 |
| プロファイル一覧 |
| タブ一覧 |
| タブ切替 |
| タブ閉じる |
コンソールログ
webctl console # 最新100件を取得 webctl console --count # レベル別のカウントのみ(LLM向け) webctl console --level error # エラーだけ抽出 webctl console --follow # 新しいログを継続的にストリーム webctl console -n 50 -l warn # 最新50件の警告のみ
設定とセットアップ
webctl setup # ブラウザをインストール webctl doctor # インストール診断 webctl init # エージェント設定に追加(CLAUDE.md など) webctl config show # 設定表示 webctl config set idle_timeout 1800
エージェント統合
-
エージェントプロンプトを生成
webctl init # CLAUDE.md, GEMINI.md 等を作成 webctl init --agents claude -
または手動で エージェント設定にウェブ閲覧用項目を追加。
-
詳細な指示は
で取得。webctl agent-prompt
AI エージェント向けクイックリファレンス
# ブラウザ起動 webctl start # ナビゲーション webctl navigate "https://site.com/login" # インタラクション webctl type 'role=textbox name~="Email"' "user@example.com" webctl type 'role=textbox name~="Password"' "secret" --submit # ページ遷移待ち webctl wait 'url-contains:"/dashboard"' # ブラウザ停止 webctl stop --daemon
クエリ構文
| 部分 | 意味 |
|---|---|
| ARIA ロールが button の要素 |
| 部分文字列一致(推奨) |
| 完全一致 |
ヒント
- 出力量を減らしたい場合は
を使用。--interactive-only - テキストの微小変更に強くするため、必ず
を使うこと。name~= - 要素が見つからないときは
で提案を確認。webctl query "…" - イベント出力を抑制したい場合は
を付与。--quiet - セッションはクッキーを永続化するので、ログインは一度だけ行えば済む。
- デバッグ前に
でコンソールエラー数を確認。webctl status - ログの概要は
、エラーのみはwebctl console --count
。--level error
アーキテクチャ
┌─────────────┐ TCP/IPC ┌─────────────┐ │ CLI │ ◄──────────────► │ Daemon │ │ (webctl) │ JSON-RPC │ (browser) │ └─────────────┘ └─────────────┘ │ │ ▼ ▼ エージェント/ユーザー Chromium + Playwright
- CLI – 状態を保持せず、コマンドだけをデーモンへ送信。
- Daemon – ブラウザ管理、最初のコマンドで自動起動。
- プロファイル –
~/.local/share/webctl/profiles/ - 設定 –
~/.config/webctl/config.json
ライセンス
MIT