jfrog

JFrog スキル

すべての JFrog エージェントとのやり取りの基盤となるスキルです。JFrog Platform の概念、jf CLI のセットアップと認証、ワークフロースキルへのインテントルーティングについて説明します。

概要（必ず読むコア部分）

このセッションでネットワークに接続する jf。<SID> が決まるまでの例外：jf --version、 jf config show。

Tier A — 必ず読む最低限の項目（最初の例外ではない jf の前）：

• UA： 環境チェック を一度実行 → 終了コードが 0/1 の場合、その正確な標準出力行を JFROG_CLI_USER_AGENT としてエクスポートし、jf を実行するすべての bash の先頭に設定します（UA を推測したり再構築したりしないでください）
• CLI の更新案内： 環境チェックの終了コードが 0/1 の場合に実行（jfrog-init／MCP のみの場合はスキップ）。NEWER_AVAILABLE → 決して処理を中断せず、すぐに --clear を実行（ほかのコマンドより先に）。タスクを完了し、返信の最後にアップグレードに関する注記を付けます。SKIP → 通知なし
• サーバー： デフォルトを一度解決 → --server-id <SID> はサブコマンドの後に指定します（jf api --server-id … のようにし、jf --server-id … api とはしません）。1 回のリクエストにつき 1 台のサーバーを使用します（ユーザーがサーバーを指定した場合を除く。例：compare <a> and <b>）
• エラー（401/403/404/タイムアウト）： サーバーを切り替えてはいけません。AQL でリポジトリを一覧表示します（ローカルまたは <remote>-cache）。401 → 同じサーバーに再ログインし、その後 1 回だけ再試行します（同一リクエストを再試行できる唯一の例外）。403/404/タイムアウト → 同じパスとクエリを再実行してはいけません（パッケージブロックによる 403 → jfrog-package-curation）。offset／page が空 → 停止します。ページャーは最大 20 ページです。同じパスで 403 → 停止します（サーバーの切り替えは 1 回まで）
• 事前の変更は禁止： リポジトリ／アーティファクト／ビルドが存在しない場合 → 停止して報告します。不足を補うために作成／コピー／移動／アップロードしてはいけません（回避策を尋ねることは許可を得たことにはなりません）
• ツールや jf api のパスを推測しないでください → ツール一覧／--help／references/ を確認します。404 → 停止します（推測した再試行はしません）。jf api には製品プレフィックス（/artifactory、/xray など）が必要です。リポジトリの一覧表示に GET /api/v1/artifacts を使ってはいけません
• 厳守ルールの確認先： 慎重な実行、サーバー選択ルール、以下の 注意点 の Tier A 項目。ヒントではありません
• 注意点の最低限（Tier A）： 対話形式の操作は禁止（jf config add、jf login、テンプレートウィザードなど）。--server-id を指定した呼び出しが失敗しても、これを省略して再試行してはいけません。401 → 再ログイン後に 1 回だけ再試行します。403/404/タイムアウト → 停止し、サーバーの切り替えやループをしてはいけません。--quiet は全コマンド共通ではありません。追加する前に --help を確認してください

Tier B — パスに応じて必須（jf api／AQL／高度な CLI 入出力／MCP 結果をシェル経由で扱うアンチパターンの前）：references/cli-gotchas.md、 references/jf-api.md、 references/preserving-command-output.md、 references/cli-command-discovery.md をすべて読みます。 セットアップ／jf setup／通常の CLI 操作には Tier B は不要です。

Tier C — 必要に応じて読む： references/INDEX.md の分野別リファレンス。必要に応じてログイン／CLI のインストールを行います。

目次（できれば SKILL.md 全体を参照してください。冒頭しか表示されない場合は、「概要」が Tier A の最低限です）：

セクション	トピック
ツール選択戦略	MCP と CLI と jf api
前提条件、環境チェック	最初の例外ではない jf の前
慎重な実行、サーバー選択ルール	Tier A の厳守ルール
注意点 — 厳守ルール	Tier A の確認事項。cli-gotchas.md 全体は Tier B
パスに応じて読む基本リファレンス	jf api／高度な CLI 操作の前に必須の Tier B
リファレンスファイルを読むタイミング → references/INDEX.md	Tier C の分野別リファレンス
コマンドの検出／jf api	該当するパスでは Tier B
構造化入力／バッチ処理／出力の保持	テンプレート／並列処理／一時ファイル

部分読み込み時の下限： 最初の非除外 jf の前に Tier A（このセクション）を読み込みます。可能な場合は SKILL.md 全体を優先してください。次の操作で jf api／AQL／高度な CLI 入出力が必要な場合にのみ、Tier B を読み込みます（チェックリスト）。ドメインの詳細 → Tier C references/INDEX.md。

ツール選択戦略を参照し、3 つのツール階層を通じて JFrog Platform を操作します。コード例では、<skill_path> はこのスキルのディレクトリで、エージェントによって自動的に解決されます。解決されない場合は、この SKILL.md ファイルを探し、その親ディレクトリを使用します。

対象外：MCP サーバーの管理。 MCP サーバーのインストール、一覧表示、削除、設定（例：「MCP をインストールして」「インストールできる MCP は何？」「自分の MCP を一覧表示して」「使用できる MCP サーバーはどれ？」「承認済み MCP カタログには何がある？」）は、JFrog Agent Guard ワークフロー（@jfrog/agent-guard）で処理します。これはこのスキルとは別のワークフローです。

ツール選択戦略

各階層を順に試し、現在の階層で操作に対応できない場合、または失敗した場合にのみ次へ進みます。

1. JFrog MCP ツール（優先）：JFrog MCP サーバーに対して CallMcpTool を使用します。サーバーのツール一覧から利用可能なツールを確認し、ツール名を推測しないでください。
2. jf CLI サブコマンド（フォールバック）：jf rt upload、jf rt dl、jf build-publish などの専用コマンドを使用します。
3. jf api（最後の手段）：専用サブコマンドがない REST／GraphQL エンドポイントに使用します。まずパスを検証してください。慎重な実行のルール 6 を参照してください。

MCP と CLI では、使用するトークンのスコープが異なる場合があります。403 が 1 回発生したら、もう一方の階層を1 回だけ試します（package-block → jfrog-package-curation）。401 の場合は、その URL を1 回だけ再試行します。

前提条件

次のツールが PATH 上で利用可能である必要があります。

ツール	用途
jq	CLI および API 出力の JSON 解析

Tier 2 と Tier 3 のすべての JFrog HTTP 通信は、jf CLI 自体を経由します（jf api。下記のjf api による Platform API の呼び出しを参照）。JFrog とのやり取りにスタンドアロンの curl は必要ありません。

JFrog 呼び出しに必要なランタイム権限。 ネットワークにアクセスするすべての jf 呼び出しには、エージェントランタイムによる送信 HTTPS のエスカレーションが必要です。~/.jfrog/ への認証情報の保存（ログイン時の jf config add）には、さらにファイルシステムへの書き込み権限のエスカレーションが必要です。

ランタイム	ネットワーク	ネットワーク + ~/.jfrog/ への書き込み
Cursor	required_permissions: ["full_network"]	required_permissions: ["all"]
Claude Code	allowed-tools: Bash(jf:*) + ホスト許可リスト	同左 + ファイルシステム許可リスト
その他	ランタイム／サンドボックスレイヤーで設定	同左

jf が出力なしで終了コード 1 を返した場合、まずランタイムのネットワークゲートを確認してください。上記の適切なエスカレーションを指定して再実行します。

環境チェック

MCP（Tier 1）ではこのチェックを省略し、すぐに進みます。このセッションで Tier 2 または Tier 3（jf）を初めて実行する前に、環境チェックを実行してください。終了コードが 0／1 の場合は、標準出力の行をそのまま <UA> としてセッション終了まで記憶します。jfrog-init 中は CLI の提案を省略してください。

bash <skill_path>/scripts/check-environment.sh <model-slug>
# exit 0/1 stdout: exactly one opaque line — that line IS <UA>. Copy it byte-for-byte.
# Do not parse, rebuild, or approximate the export value from this comment.
# stderr: JSON state (cached 24h at ${JFROG_CLI_HOME_DIR:-$HOME/.jfrog}/skills-cache/jfrog-skill-state.json)

次に、終了コードが 0／1 の場合に限り：

bash <skill_path>/scripts/cli-newer-version-offer.sh
# SKIP → continue the original task; do not mention the offer.
# NEWER_AVAILABLE <cli_version> <latest> (suggest_upgrade) → never block or ask
# mid-task. Immediately run (before any other command):
#   bash <skill_path>/scripts/cli-newer-version-offer.sh --clear
# Then finish the original task (success or failure) and end the final reply
# with this line verbatim as its very last line (no other upgrade mention):
#   JFrog CLI <latest> is available (you have <cli_version>). Upgrade? Yes / No
# Yes (later turn) → references/jfrog-cli-install-upgrade.md, then
# check-environment.sh --force (Tier 2/3 only on exit 0/1). No → silent.
# Next offer = next new latest. JFROG_CLI_AVOID_NEW_VERSION_WARNING=true → SKIP.

終了コードが 2／3 の場合は <UA> が生成されません。下記の終了コード表に従い、Tier 2 または 3 に進まないでください。

自身のモデルスラッグを小文字にし、バージョンを付けて渡します（例：opus-4.7、gpt-5.6-sol、gemini-2.5-pro、composer-2-fast）。例は許可リストではありません。新規または未掲載の名前は unknown ではなく、そのまま出力してください。ハーネス／ロール（subagent、agent）やファミリー名のみ（claude、gpt）は使用しないでください。サブエージェントは親のスラッグを引き継ぎます。unknown は、本当に識別できない場合にのみ使用してください。

JFROG_CLI_USER_AGENT を決して捏造しない

終了コードが 0／1 の場合、スクリプトの標準出力の行がそのまま <UA> です。これをそのままエクスポートしてください（決して捏造、再構築、編集しないでください）。終了コードが 2／3 の場合、<UA> はありません。生成しないでください。現在、標準出力は jfrog-skills/ で始まり、model/ では始まりません。

• 親セッション： <UA> がない、または model/ で始まる（レガシー形式）場合は破棄し、check-environment.sh を再実行してください。終了コードが 0／1 で、かつ model/ で始まらない場合に限り、新しい標準出力の行をエクスポートしてください。それ以外の場合は停止してください（捏造しないでください）。
• サブエージェント： 親から渡された正確な <UA> のみを使用してください。スクリプトを再実行したり、代わりの値を組み立てたりしないでください。その値がない、または model/ で始まる場合は停止してください（エクスポートも捏造もしないでください）。再実行しないでください。

bash の呼び出しごとに JFROG_CLI_USER_AGENT を一度だけエクスポートする

jf を実行するすべての bash 呼び出しの先頭で、<UA> を一度だけエクスポートしてください。その呼び出し内のすべての jf 呼び出しで、その値が使われます。

export JFROG_CLI_USER_AGENT='<UA>'
export JFROG_CLI_AI_MODEL='<model-slug>'   # jf >= 2.120.0 emits ai-model/<slug> from this
jf config show
jf api /artifactory/api/system/version

JFROG_CLI_AI_MODEL には、環境から CLI が推測できないモデルを設定します。<UA> と合わせて（スクリプトに渡したものと同じ <model-slug> を）エクスポートしてください。古い CLI はこの変数を無視しますが、スクリプトで記録された場合、記憶された <UA> にはすでにスラッグが含まれています。

jf を呼び出すたびに代入を繰り返さないでください（各行で JFROG_CLI_USER_AGENT='<UA>' jf … としないでください）。これはセッション全体に適用される不変条件です。基盤となるこのスキルを利用するワークフロースキルに従って実行する jf 呼び出しも含め、セッション内のすべての jf 呼び出しに適用されます。このスキル内および references/*.md 内の例では、読みやすさのためにエクスポートを省略していますが、このルールは全体に適用されます。サブエージェントを起動する際は、プロンプトに <UA> と、CLI のアップグレード案内がすでに表示されたかどうかを渡してください（捏造しないを参照）。サブエージェントにはアップグレード案内を表示しません。NEWER_AVAILABLE の場合は --clear を実行してその行を返し、親が返信の末尾に案内を付けます。

終了コード	意味
0	キャッシュは最新です — CLI の準備完了（ティア 2 と 3 が利用可能）。続行してください
1	キャッシュを更新しました — CLI の準備完了（ティア 2 と 3 が利用可能）。続行してください
2	jf がインストールされていません — ティア 2 と 3 は利用できません。MCP（ティア 1）のみ利用できます
3	jf が最小バージョン未満です — ティア 2 と 3 は利用できません。MCP（ティア 1）のみ利用できます

終了コードが 2 または 3 の場合、標準出力には <UA> が出力されません。このファイルや jf --version から値を捏造したり、手作業で組み立てたりしないでください。

終了コードが 2 または 3 でも、致命的なエラーではありません。CLI のインストールまたはアップグレードを試みてください（references/jfrog-cli-install-upgrade.md を参照）。インストールに成功したら、環境チェックを再実行してください。インストールできない場合（権限がない、環境が制限されているなど）は、MCP（ティア 1）のみで続行してください。jf CLI コマンド（ティア 2）と jf api（ティア 3）のどちらにも、動作する jf のインストールが必要です。

JSON の解析（jq）

CLI と API の出力から JSON を解析する際は、すべて jq を使用してください（パイプ、-r、フィルター）。

~/.jfrog/skills-cache/ — 許可されるファイルのみ

${JFROG_CLI_HOME_DIR:-$HOME/.jfrog}/skills-cache/ は、一般的な作業用または一時ディレクトリではありません。以下の 2 つの成果物に限って使用してください。

1. jfrog-skill-state.json — scripts/check-environment.sh が書き込むファイル（CLI チェックの 24 時間キャッシュ）。
2. onemodel-schema-${JFROG_SERVER_ID}.graphql — キャッシュされた OneModel のスーパーグラフスキーマ（references/onemodel-graphql.md を参照）。

HTTP レスポンス本文、GraphQL クエリの結果、その場限りの JSON、レポート、その他の一時ファイルを skills-cache/ に保存しないでください。代わりに、JF_TMP=$(mktemp -d) && echo "$JF_TMP" を使ってセッションごとに一度、専用ディレクトリを作成し、そこに保存してください（/tmp 直下に予測可能な名前を使わないでください）。後続の Shell 手順では、出力されたディレクトリを再利用してください。下記のコマンド出力の保持と同じ方法です。

慎重な実行

厳守事項 — 決して省略しないでください。 推測に基づく操作、準備のための操作、憶測による操作は禁止されています。JFrog CLI コマンド、MCP ツール呼び出し、または API 呼び出しを行う前に、必ず次の手順を実施してください。

1. その操作がユーザーの依頼を満たすために必要であることを確認します。 依頼が曖昧な場合や、複数のシステムを指す可能性がある場合（例： 「ビルド」が Artifactory のビルド情報を指すのか、CI/CD パイプラインの実行を指すのか） は、推測するのではなく、ユーザーに確認してください。誤ったシステムから データを取得してはいけません。誤った回答をするより、質問する方が適切です。
2. 以下のサーバー選択ルールに従って対象サーバーを特定します — 使用するサーバーに曖昧さがあってはなりません。
3. 変更を伴う操作（作成、更新、削除、アップロード）については、意図が明確に示されている場合を除き、ユーザーに確認します。これはすべての階層（MCP ツール、CLI コマンド、jf api の POST／PUT／DELETE）に適用されます。
4. 変更を加える前に、まず読み取り操作を行い、現在の状態を把握します。
5. 準備のための変更を決して捏造しないでください。 前提条件が満たされていないために依頼された操作が失敗した場合（指定されたリポジトリにアーティファクトがない、リポジトリが存在しない、パッケージが想定された場所にない、ビルドが見つからないなど）は、停止して不足している点をユーザーに報告してください。前提条件を満たすために、コピー、移動、アップロード、リポジトリ作成、その他の変更を行ってはいけません。「ダウンロードが成功するようにそこへ置く」「動くようにする」「必要なことは何でもする」も、依頼された操作ではなく回避策です。欠けているアーティファクトを独自の判断で用意する許可にはなりません。その変更自体がユーザーの依頼内容である場合（このファイルを公開する、このリポジトリを作成する、このアーティファクトを移動する）に限り、その変更を実行してください。こうした「補助的な」変更は、ユーザーが想定していない連鎖的な影響を招くことがあります。仮想リポジトリの解決結果の変化、ストレージクォータの消費、レプリケーションの実行、Xray の再インデックス、権限の伝播などです。
6. ツール名や API パスを決して推測しないでください。 MCP ツールについては、サーバーのツール一覧にそのツールが存在することを確認します。jf api のパスについては、<skill_path>/references/（またはウェブにアクセスできる場合は JFrog OpenAPI specifications） に照らして検証します。404 が発生したら停止して報告してください — 推測した別のパスで再試行してはいけません。
7. 失敗した呼び出しをループで再試行しないでください。 AQL は <repo>-cache に対して実行します（仮想リポジトリは -cache ではありません）。401 の場合は、その後一度だけ再試行します。ページネーションは 20 ページが上限です — cli-gotchas.md を参照してください。GET /api/v1/artifacts を捏造してはいけません。

サーバー選択ルール（必須）

厳守事項 — 決して省略したり緩めたりしないでください。 間違ったサーバーに関する回答や、黙ってサーバーを切り替えることは、停止して確認するよりも重大です。

単一サーバーの不変条件。 <SID> が特定された後は、その後のネットワーク接続を伴うすべての jf 呼び出しで、--server-id <SID>（以下で特定されるデフォルト値）を必ず指定します。ブートストラップ時の jf --version／jf config show は、特定されるまではこのルールの対象外です。1 件のユーザー依頼に対して、すべてのネットワーク jf 呼び出しで使用する server-id は必ず 1 つだけです。ただし、ユーザーが比較対象のサーバーを指定した場合（例：compare <a> and <b>）は除きます。その場合は、各呼び出しで対象の --server-id を指定します。

JFrog MCP と CLI の認証は独立しています。 MCP ツールは MCP サーバーのセッションを通じて認証され（jf config は使用しません）、CLI コマンドは jf config を通じて認証されます。jf config use で CLI の対象サーバーを切り替えても、MCP 接続は引き続き元のサーバーを参照します。同じセッションで、異なるサーバーを対象にする MCP 呼び出しと CLI 呼び出しを混在させないでください。ユーザーからサーバーの切り替えを求められた場合は、MCP 接続を再確立するまで、MCP ツールは引き続き元のサーバーを対象とすることを警告してください。

401／403／404、空の結果、または不完全な結果を受けて、2 つ目の設定済みサーバーで再試行してはなりません。また、「my」／「our」という表現や jf config show に追加のエントリーが表示されることから、複数サーバーを対象とする意図を推測してはなりません。例外： ユーザーが別の ID を明示的に指定した場合（「<id> で、…」「<id> を使って」「<a> と <b> を比較して」）に限り、対象サーバーを変更できます。推測された意図は例外の根拠になりません。

セッションごとにデフォルトを一度だけ解決する

最初の jf 呼び出しの前に、デフォルトの server-id を解決し、セッション中は <SID> として記憶しておきます。<UA> と同じパターンです。

jf config show 2>/dev/null \
  | awk '/^Server ID:/{id=$NF} /^Default:[[:space:]]*true/{print id; exit}'
# stdout: the default server-id; if empty, stop and ask which to use

以降のすべての jf 呼び出しに --server-id <SID> を指定します。このフラグは jf 自体の後ではなく、サブコマンド名の後に置きます。

• ✅ jf api --server-id <SID> /artifactory/api/system/version
• ✅ jf rt ping --server-id <SID>
• ❌ jf --server-id <SID> api /… — flag provided but not defined で失敗します

サブエージェントを起動するときは、プロンプトに <SID> を渡します。サブエージェントは 再解決しません。このスキル内のほかの箇所や references/*.md の例では、 読みやすさのため --server-id を省略していますが、このルールは JFROG_CLI_USER_AGENT と同様に全体に適用されます。新しいサーバーを追加するには、 references/jfrog-login-flow.md を読んでください。

エラーが発生したら停止し、切り替えない

jf 呼び出しが 403、404、ネットワークエラー、タイムアウト、または 401 以外の エラーを返した場合は、それ以上 jf を呼び出さずに停止して応答します。401 の場合は 同じサーバーに再ログインし、その後一度だけ再試行します。失敗した場合は停止します。

<server-id> が <endpoint> に対して <code> を返しました。理由：<short reason>。ほかに 設定済みのサーバー：<list> — 明示的な指示がない限り、そちらには問い合わせません。 どのように進めますか？

パス条件付きの基本リファレンス（jf api／高度な CLI の前に必須）

これら4つのファイルは基本スキルの Tier B です。以前はこの SKILL.md に含まれていた 内容です。任意の INDEX ドメイン参照ではなく、すべての CLI／セットアップの経路で 必須というわけでもありません。

jf api、jf api 経由の AQL、高度な CLI I/O（一時ファイル／stdout-stderr の パターン）、またはシェル／jq を使った MCP の結果の処理を行う前に、必ずすべてを 最初から最後まで読みます。通常の jf（例：jf setup、既知のフラグを使った jf rt …）では Tier A のみが必要です（概要）。

Tier A にある短い注意点の箇条書きは、セッションで 最低限必要な内容です。Tier B に進む場合、これらの箇条書きは references/cli-gotchas.md を最後まで読むことの 代わりにはなりません。

Tier B — 必ず最初から最後まで読む（パス条件付き）	対象範囲
references/cli-gotchas.md	注意点、留意事項、既知の問題、すべきこと／すべきでないこと、I/O と認証の落とし穴
references/jf-api.md	製品プレフィックスの表、フラグ、例、GraphQL ペイロード
references/preserving-command-output.md	プライベートな mktemp -d ディレクトリ、jq のための再取得禁止
references/cli-command-discovery.md	名前空間、トップレベルのコマンド、Pipelines の提供終了

Tier B の経路でこれらのいずれかを省略すると、基本スキルの読み込みが不完全となり、 ハードルール違反になります。Tier A のみの経路（セットアップ／単純な CLI）で 省略しても、違反にはなりません。

リファレンスファイルを読むタイミング

この SKILL.md は全体を読むことを推奨します。概要 は、部分的に読む場合に最低限必要な Tier A です。上記の パス条件付きの基本リファレンスは Tier B（該当する経路では必須ですが、すべてのセッションで必要なわけではありません）です。 references/INDEX.md にあるその他すべての内容は、 ドメインの詳細を扱う Tier C です。タスクに最も関連するファイルを2～3個以下読み、 使わないドメインは読み飛ばします。

references/INDEX.md には、すべての references/*.md ファイル（Tier B + Tier C）が 記載されています。ファイルの追加／名前変更／削除を行う場合は、同じ変更で INDEX も更新します。 一致しない場合、CI（tests/jfrog/test_reference_index_contract.py）が失敗します。

コマンドの確認

オプションを確認するには --help を実行します。記憶しているコマンドに頼らないでください。

1. jf --help → 2. jf <namespace> --help → 3. jf <command> --help

Tier B — --help を超えるコマンド確認に依存する前に、必ず最初から最後まで読みます： references/cli-command-discovery.md （名前空間、トップレベルのライフサイクル／セキュリティコマンド、Pipelines の提供終了）。

jf api によるプラットフォーム API の呼び出し

プラットフォーム REST/GraphQL の Tier 3。認証は自動で行われます。jf rt curl / jf xr curl は使用しないでください。 常に製品プレフィックス（/artifactory、/xray、/access など）を含めてください。省略すると 404 になります。

Tier B — jf api を使う前に必ず全文を読んでください： references/jf-api.md （プレフィックス、フラグ、例、OneModel GraphQL ペイロード）。本文は stdout、ステータスは stderr に出力されます。注意点 と cli-gotchas.md（Tier B）全文を参照してください。

構造化入力

対話型ウィザード（jf rt rpt / ptt / rplt）はエージェントでは使用できません。 REST を使って既存の設定を取得し、編集してください：

jf api /artifactory/api/repositories/<repo-key>

その他の REST／テンプレートのパターン → references/INDEX.md 経由で references/artifactory-api-gaps.md または references/platform-admin-api-gaps.md を参照してください。

注意点 — 厳守事項（必ず確認してください）

ヒントではありません。 以下の Tier A の箇条書きは、常に読むべき最低限の内容です。完全版の references/cli-gotchas.md は Tier B です — jf api / AQL / 高度な CLI I/O / MCP のシェル経由利用の前に必ず確認してください。すべての CLI 操作や jf setup の前に読む必要はありません。Tier B 対象の操作では、短い箇条書きはファイル全文の代わりにはなりません。

Tier A の最低限の内容（免除対象を除くすべての jf セッション）：

• --quiet はグローバルではありません。追加する前に --help を確認してください
• --server-id： これを指定した呼び出しが失敗した場合、指定を外して再試行しないでください（デフォルトサーバーへの切り替えが通知されないため）。サーバー選択ルールを参照してください
• 非対話型のみ — jf config add、jf login、*template ウィザードは避けてください。references/jfrog-login-flow.md／REST を使用してください
• 認証エラー： 401 → 同じサーバーに再ログインしてから、1 回だけ再試行してください。 403 → 中止してください（package-block → jfrog-package-curation）。404 → パスの問題なので中止してください

Tier B の注意事項（以下の操作を行う前に cli-gotchas.md 全文と関連する Tier B の参照資料を読み込んでください）：

• MCP： 構造化されたツールの結果を直接読み取ってください。シェル／jq にパイプしないでください
• jf api の I/O： 本文 → stdout、ステータス → stderr。stdout を jq にパイプしてください。 2>&1 | jq は絶対に使用しないでください。 -L / -o は使用せず、リダイレクトしてください：jf api … > "${JF_TMP:?}/<label>.json"
• 製品プレフィックス はすべての jf api パスで必須です（Tier B の jf-api.md を参照）
• jq の再試行のために再取得しないでください — まず出力を保存してください （コマンド出力の保持 と Tier B の preserving-command-output.md を参照）

バッチ実行と並列実行

独立した操作には、最も軽量な並列化方法を使用してください：（1）1 つの Shell 内でループ／&、（2）並列の Shell 呼び出し、（3）大規模な多重展開にはサブエージェント。詳細 → references/general-parallel-execution.md。

コマンド出力の保持

ネットワーク応答はプライベートな mktemp -d ディレクトリに保存してください（ディレクトリは一度だけ作成し、そのパスを表示して再利用します）。jq で再読み込みし、解析を修正するために同じネットワーク呼び出しを再実行しないでください。

Tier B — 高度な I/O／再解析パターンを使用する前に必ず全文を読んでください： references/preserving-command-output.md （JF_TMP ディレクトリと表示、再取得なし／コンテキストをまたいだ再利用なし）。

jf を実行する前に — クイックチェックリスト

概要 Tier A は必須です。次のアクションで jf api ／高度な CLI が必要な場合にのみ Tier B を追加してください。

• export JFROG_CLI_USER_AGENT='<UA>' — check-environment.sh の終了コード 0/1 で出力される正確な行です。CLI の案内を完了するか、該当なしとします（jfrog-init）。NEWER_AVAILABLE は返信の最後に記載する通知であり、タスクの途中で停止する理由にはなりません
• ネットワーク経由で jf を使う場合：サブコマンドの後に --server-id <SID> を指定します（SID 指定前の jf --version ／ jf config show は除く）
• サーバーは 1 つにします。エラーが発生したら停止し、切り替えないでください（ユーザーが指定した場合／compare の場合に限り複数可）。不足分を埋めるための事前の作成／コピー／移動／アップロードは禁止です
• ツール／パスを推測しないでください → 一覧表示／--help ／references/ を確認します。404 が返されたら停止します。jf api では製品のプレフィックスを指定します。同じパスで 403/404 が返されたら停止します（ページャーを使わないでください）。GET /api/v1/artifacts は使用しないでください
• Tier A の必須ルール：慎重な実行 + サーバーの選択 + 落とし穴の基本事項（対話形式／--server-id での再試行／エラー時に停止／--quiet）
• Tier B（jf api ／AQL ／高度な CLI 入出力）：cli-gotchas.md、jf-api.md、preserving-command-output.md、cli-command-discovery.md をすべて確認します