エージェント最適化されたHubとの作業方法としてのhf CLIの設計

記事一覧に戻る

hf は、Hugging Face Hubへの公式コマンドラインエントリポイントです。Python SDKでHub上で行えることはすべて、ターミナルから実行できます：モデル、データセット、Spacesのダウンロードとアップロード、リポジトリ、ブランチ、タグ、プルリクエストの作成と管理、HFインフラ上でのJobsの実行、Buckets、Collections、webhooks、Inference Endpointsの管理などです。

hf CLIは、長年にわたり主にユーザー向けに構築されてきました。しかし、現在ではコーディングエージェント（Claude Code、Codex、Cursorなど）による利用がますます増えています。そこで、両方の対象者に同時に機能するよう再構築しました。このブログ記事では、私たちが行ったことと、そのベンチマーク方法をまとめます。複雑で複数ステップのタスクにおいて、CLIなしのベースライン（エージェントが手動でcurlやPython SDKを実行する場合）は、hf CLIの最大6倍のトークンを使用することがわかりました。

Hub上のAIエージェントトラフィック

2026年4月からHubのエージェント使用状況の追跡を開始しました。hf CLI（およびその基盤となるhuggingface_hub Python SDK）は、コーディングエージェントが設定する環境変数を読み取ることで、エージェントの使用を検出します：Claude Code用のCLAUDECODE/CLAUDE_CODE、Codex用のCODEX_SANDBOX、さらにCursor、Gemini、Pi、および汎用のAI_AGENTです。この単一のシグナルは2つの役割を果たします：CLIの出力を形成すること（以下で詳述）と、各Hubリクエストにagent/<name>ユーザーエージェントをタグ付けし、トラフィックを駆動するエージェントに帰属させることです。個別ユーザー数で最大のものはClaude CodeとCodexで、他のすべてを大きく引き離しており、本記事の後半でベンチマークを行う2つのエージェントです。

棒グラフはエージェントごとの個別ユーザー数を表し、サブラベルはリクエスト量を示します。Claude Codeだけで約40kユーザー、49M近くのリクエストがあり、Codexがそれに続きます。これらは初期の数字（2026年4月からエージェントトラフィックの帰属を開始したばかり）ですが、すでに規模は大きく、コーディングエージェントがHubとの標準的な作業方法になるにつれて、さらに増加すると予想されます。

人間とエージェントの両方に対応した設計

人間とコーディングエージェントは、同じhfコマンドに対して異なる出力を期待します。人間はリッチなターミナル出力を望みます：ANSIカラー、画面に収まるように切り詰められたパディング付きテーブル、成功時の緑の✅、ブール値用の✔、プログレスバー、散文形式のヒントなどです。一方、エージェントはその逆を望みます：ANSIなし、切り詰めなし、エージェントは人間よりはるかに高密度の出力を扱えるため、すべての値を完全な形で、トークン消費を抑えるためにコンパクトかつ構造化された形に保つこと。また、CLIプロンプトに応答できず、タイムアウト後にコマンドを再実行することを厭いません。このセクションの残りでは、hfがそれぞれのニーズに応える方法を説明します。エージェントモードの出力をhf v1.9.0で導入し、以降のリリースでCLIの残りの部分に徐々に移行しています。

1つのコマンド、複数のレンダリング

hfが（上記の環境変数を通じて）エージェントの使用を自動検出すると、同じコマンドを異なる方法でレンダリングします。フラグを渡すことなく、人間用またはエージェント用に最適化された出力形式を選択します：

# human (default in a terminal): aligned table, truncated to fit, with a hint
> hf models ls --author Qwen --sort downloads --limit 3
ID                       CREATED_AT DOWNLOADS LIBRARY_NAME LIKES PIPELINE_TAG    PRIVATE TAGS
------------------------ ---------- --------- ------------ ----- --------------- ------- -------------------------
Qwen/Qwen3-0.6B          2025-04-27  21156913 transformers  1285 text-generation         transformers, safetens...
Qwen/Qwen2.5-1.5B-Ins... 2024-09-17  15143953 transformers   725 text-generation         transformers, safetens...
Qwen/Qwen3-4B            2025-04-27  14808352 transformers   625 text-generation         transformers, safetens...
Hint: Use `--no-truncate` or `--format json` to display full values.

# agent (auto-detected): TSV, full ids + ISO timestamps + every tag, nothing truncated
$ hf models ls --author Qwen --sort downloads --limit 3
id      created_at      downloads       library_name    likes   pipeline_tag    private tags
Qwen/Qwen3-0.6B 2025-04-27T03:40:08+00:00       21156913        transformers    1285    text-generation False   ['transformers', 'safetensors', 'qwen3', 'text-generation', 'conversational', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-0.6B-Base', 'base_model:finetune:Qwen/Qwen3-0.6B-Base', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen2.5-1.5B-Instruct      2024-09-17T14:10:29+00:00       15143953        transformers    725     text-generation False['transformers', 'safetensors', 'qwen2', 'text-generation', 'chat', 'conversational', 'en', 'arxiv:2407.10671', 'base_model:Qwen/Qwen2.5-1.5B', 'base_model:finetune:Qwen/Qwen2.5-1.5B', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen3-4B   2025-04-27T03:41:29+00:00       14808352        transformers    625     text-generation False   ['transformers', 'safetensors', 'text-generation', 'arxiv:2309.00071', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-4B-Base', 'base_model:finetune:Qwen/Qwen3-4B-Base', 'license:apache-2.0', 'endpoints_compatible', 'deploy:azure', 'region:us']

人間には、整列されたテーブル、端末に収まるよう切り詰められた形式、追加情報を表示する方法を示すヒント、ステータスを示す色（成功時は緑の✓、エラー時は赤）が表示されます。エージェントには、完全なレコードがTSV形式で提供されます：完全なリポジトリID、完全なISOタイムスタンプ、すべてのタグ、ANSIコードなし、切り詰めなしで、解析しやすくトークン消費が少ない形式です。

実装では、.table(...)、.result(...)、.json()などのログメソッドを導入し、未加工のデータを入力として受け取り、フォーマットを処理します。人間モードとエージェントモードに加えて、コマンドをパイプでつなぎやすくするための--jsonと--quietオプションも導入しました。デフォルトモードはコンテキストに基づいて自動的に選択されますが、ユーザーはいつでも--format human | agent | json | quietで希望の形式を強制できます。

次のコマンドのヒント

CLIコマンドは単独で実行されることは稀です：1つのステップは通常次のステップを意味します（git add、次にgit commit）。多くのhfコマンドは現在、ヒントで終了します：使用したばかりのIDが事前に入力された正確な次のコマンドを示すことで、ユーザーやエージェントはゼロから考えることなく次のステップに直行できます。バックグラウンドでJobを開始するとログへのヒントが表示され、Spaceを作成するとブートステータスへのヒントが表示されます：

$ hf jobs run --detach python:3.12 python train.py
✓ Job started
  id: 6f3a1c2e9b
  url: https://huggingface.co/jobs/celinah/6f3a1c2e9b
Hint: Use `hf jobs logs 6f3a1c2e9b` to fetch the logs.

人間にとっては便利な機能です。エージェントにとってはレールのようなものです：次のアクションが名前付きで、正しいIDでパラメータ化され、実行準備が整っているため、何をすべきかを考えるステップが少なくなります。エラーも同様に振る舞い、単に失敗するのではなく修正方法を明示します：

Error: Not logged in. Run `hf auth login` first.

ヒント、警告、エラーはすべてstderrに出力され、データはstdoutに出力されるため、このようなガイダンスがエージェントが解析する出力を汚染することはありません。

ノンブロッキングで再試行に安全

hfは、エージェントが押せないキーを待つインタラクティブプロンプトに留まることはありません。破壊的なコマンドは依然として人間に確認を求めますが、エージェントモードではメッセージ内に修正方法を明記して即座に失敗します（Use --yes to skip confirmation.）し、-y/--yesでスキップできます。また、エージェントはタイムアウトやコンテキストの喪失時に再試行するため、操作は繰り返し安全に実行できるように設計されています：hf repos create --exist-okはリポジトリが既に存在する場合は何もしませんし、アップロードを再実行すればクリーンに再コミットされます。別途、実際のデータを移動するコマンドには--dry-runがあり、実行前に転送内容を正確に表示します。これは人間とエージェントの両方にとって便利で、長いダウンロードや盲目的な同期にコミットする必要がありません：

# agent mode: a destructive command without --yes refuses, with the fix in the message
$ hf repos delete my-org/old-model
Error: You are about to permanently delete model 'my-org/old-model'. Proceed? Use --yes to skip confirmation.

# commands that move data take --dry-run to preview the transfer first
$ hf download deepseek-ai/DeepSeek-V4-Pro config.json --dry-run
[dry-run] Will download 1 files (out of 1) totalling 1.8K.
file         size
config.json  1.8K

発見しやすく予測可能なコマンド

hfは探索可能に設計されています：hfを実行してリソースグループを表示し、必要なグループで--helpを実行すると、すべての--helpに実際のコピー＆ペースト可能な例が表示されます（エージェントは説明文を解析するよりもこの例に素早くマッチできます）：

$ hf models ls --help
...
Examples
  $ hf models ls --sort downloads --limit 10
  $ hf models ls --search "qwen" --author Qwen
  $ hf models ls Qwen/Qwen3-4B --tree

コマンドツリーは一貫性があり、リソース + 動詞で、明らかなエイリアス（hf models ls、hf repos create、hf jobs ps、hf collections delete；list/ls、remove/rm）が付いています。一度コマンドを学習すれば、エージェントは残りを推測できます。また、出力は合成可能です：-qは次のコマンドにパイプするためのIDを1行ずつ出力し、--jsonはjqに渡すためのものを提供します。

$ hf models ls --author Qwen -q | head -3
Qwen/Qwen3-0.6B
Qwen/Qwen2.5-1.5B-Instruct
Qwen/Qwen3-4B

コーディングエージェント向けhf CLIのベンチマーク

hf CLIがエージェントにとって本当に効率的かどうかを確認するため、測定を行いました。小規模な評価ハーネスを構築し、Hubを操作する同じ一連のタスクをそれぞれの方法で複数回実行し、すべての実行をライブHubに対して評価しました。方法論の前にヘッドラインをお伝えします：両方のエージェントにおいて、hf CLIが優位であり、特に複雑で複数ステップのタスクでトークン使用量が大幅に少ないことがわかりました。

(self-report error = 17の解決可能なタスクでエージェントが成功を報告したが、Hubがそうではなかったもの。hf CLIの行は、スキルがインストールされたCLIです。ベアCLIにスキルが追加するもの（主にツールコールの削減）は、スキルセクションで別途説明します。代表的なトランスクリプトはこのバケットに公開されています。)

セットアップ

18の非自明なHubタスクを定義しました。「ファイルをダウンロードする」ではなく、実際に依頼するような種類のものです：トレンドの組織のモデルを集約する、リポジトリのファイルとそのサイズを検査する、include/excludeルール付きでフォルダをアップロードする、ファイルを削除する、リポジトリ間でファイルをコピーする、ライセンスを追加するPRを開く、ブランチとタグ付きでリポジトリを作成する、バケットを同期・整理する、コレクションを構築する。各タスクは、新規のコーディングエージェントに、Hubと通信する1つの方法で与えられます：

• hf CLI、または
• curl / Python SDK：hf CLIを一切使用せず、エージェントはREST APIに対するcurlまたはhuggingface_hub Pythonライブラリにフォールバックします。

hf CLIは、スキルあり（後述のスキルセクションで触れます）とスキルなしの2つの構成で実行します。ただし、以下のヘッドライン比較は単にhf CLI vs curl / SDKです。スキルの増分効果は小さいため、メインの結果に混ぜるのではなく、別途分解して示します。

設定は意図的にクリーンにしています：実行ごとに新規インスタンス、カスタムMCPサーバーなし、CLAUDE.mdやAGENTS.mdなし、動作を誘導するコンテキスト内の情報なしです。タスクとツールは単一のプロンプトに入り、エージェントはTASK_COMPLETEまたはTASK_FAILEDマーカーで終了しますが、そのマーカーは信頼しません（エージェントは実際には完了していない作業で成功を報告する可能性があるため）。したがって、すべての実行をライブHubを再クエリして独立して評価します：ブランチは本当に作成されたか、ファイルは実際に削除されたか、バケットは存在するか？各タスク/ツールの組み合わせは10回実行します。コーディングエージェントは非決定的であるため、エージェントあたり約520回の実行（18タスク × 3ツール × 10回、請求対象のJobsタスク1つに上限を設けたため）となり、合計で約1,000回の評価となります。全体を2回実行し、2つの最も人気のあるコーディングエージェント（Sonnet 4.6搭載のClaude CodeとGPT-5.5搭載のOpenAI Codex）でテストしました。

結果

以下の2つのチャートは、上記の表を詳しく分解したものです。まず、curlとSDKが最も苦戦するエージェントであるSonnetでのタスク成功率です：

CLIなしの場合、curlとSDKは10ポイント差で遅れます。これはSonnetにおいて、書き込み部分などジョブの一部を完了できないためで、hf CLIはこれらをクリアします。

2番目の画像は、GPT-5.5でのトークンへの影響をタスクごとに分解したものです。各バーは、同じタスクにおけるcurl/SDKのトークン数をCLIのトークン数で割ったもので、2.4×は非hf版が同じ作業を行うのに2.4倍のトークンを消費したことを意味します：

ワンショット読み取り（データセット行数のカウント、メタデータのバッチ処理）では、curlとSDKは問題なく、時には軽量です。しかし、タスクが複雑になり、複数の依存ステップが含まれるようになると、エージェントはRESTコールのチェーン全体を手動で構築するか（またはSDKを掘り下げる）必要があり、コストが急増します：ブランチとタグ付きのリポジトリ作成、ファイルの削除、リポジトリ間のコピー、バケットの同期などでは、CLIの2.4倍から6倍のコストがかかります。hf CLIにより、エージェントは複雑なワークフローを手動で作成するのではなく、いくつかの高レベルのコマンドとしてタスクを表現できます。

主な発見

• hf CLIはcurlやSDKよりもはるかに軽量です。 同じタスクで、同等またはそれ以上の成功率で、curlとSDKは約1.3倍から1.8倍のトークンを消費します。簡単な読み取りでは問題ありませんが、実際の複数ステップの作業では2倍から6倍のコストがかかります：CLIはRESTコールのチェーンをいくつかの高レベルのコマンドにまとめますが、curlやSDKは毎回手動でチェーンを再導出します。
• より強力なモデルでも、curlとSDKは動作するが無駄が多いままです。 Sonnetではジョブの一部（主に書き込み）を完了できません。GPT-5.5ではほとんど成功しますが、RESTコールを手動で構築（またはSDKを使用）するため、CLIのトークン消費量を大幅に上回ります。

hf-cliスキル

hfにはスキルが同梱されています：コマンドサーフェス全体のコンパクトなリファレンスで、エージェントがコンテキストとして読み込みます。これはライブのhfコマンドツリーから自動生成され、コマンドごとに1行（シグネチャ、1行の説明、重要なフラグ）で、リソースごとにグループ化され、一般的なオプションの短い用語集が付いています。自己説明的なフラグは意図的に省略して簡潔に保ち、コンテキストを軽くしており、毎リリースごとに再生成されます。hf skills previewで表示するか、以下でインストールできます：

# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills`
hf skills add
# includes the above + Claude Code
hf skills add --claude

これにより何が得られるでしょうか？主に、エージェントが推測をやめます。最も明確なビューは、スキルありとなしでの各実行のコマンド数を比較したものです：

両方のエージェントで、タスクあたりのコマンド数が約10から約7に減少し、ツールコールが約30%減少します。これは、エージェントが正しいコマンドと引数を見つけるために--helpを探索する必要がないためです。スキルはトークン消費を削減しません。コンテキストに固定の情報スライスを追加するため、同じタスクでトークン数はほぼ同じか、わずかに増加する可能性があります。また、スキルを追加してもCLIの信頼性は向上しませんが、エージェントがツールの使い方を調べるのではなく、タスクを実行する時間に集中できるようになります。これは、hfをローカルモデルと併用する場合に特に役立つ可能性があります。

各タスクを新規セッションで実行したため、スキルはタスクごとにコンテキストコストを支払います。実際の複数タスクセッションでは、このコストは償却されます（エージェントは一度コマンドサーフェスを学習する）。そのケースは測定していません。

自分で試してみる

これらすべてをベンチマークしたのは、それが重要だと考えるからです。エージェントはHubの実際のユーザーになりつつあります：モデルのトレーニング、データセットの構築とクリーニング、Spacesとしてのデモの提供など、ほとんど常に人の代わりに作業しています。エージェントにとって使いやすいHubは、それらを使用する人々にとってもより良いHubです。エージェントのツールが優れているほど、ユーザーのためにできることが増えます。

エージェントがHugging Face Hubとやり取りする場合は、hf CLIを使用することをお勧めします：

# macOS / Linux
curl -LsSf https://hf.co/cli/install.sh | bash

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

次に、スキルを提供して、エージェントが最初のターンからコマンドサーフェス全体を把握できるようにします：

hf skills add            # Codex, Cursor, OpenCode, Pi and other agents that load skills from .agents/skills
hf skills add --claude   # the above + Claude Code

次に、エージェントをHubに向けさせて作業させます。ログインしていることを確認し（hf auth login）、次のようなプロンプトを与えます：

Use `hf` to list my Hugging Face Hub models, datasets, and Spaces.
Take a look at how I am currently using the Hub and suggest a few ways you could help me.

エージェントは自らコマンドを見つけ出し、有用なものを返します。

完全なコマンドリファレンスはhf CLIガイドにあります。

エージェントハーネスの登録

エージェントハーネスを構築していますか？登録しましょう！ これによりhfがそれを検出する方法を学習し、Hubがそのトラフィックをハーネスに帰属させることができます。agent-harnesses.tsにエントリを追加する小さなPRを開くだけです。詳細はエージェントハーネスの登録ガイドをご覧ください。