Zenn CLI

Zenn CLI を使い、Public API 経由で Scrap の取得、作成、更新、コメント操作を行う。認証情報、公開範囲、投稿内容、機械可読出力を安全に扱う。

Zenn Scrap の考え方

Zenn 公式の説明では、Scrap はテーマを決めたスレッドへ、好きな単位・タイミングで知見やメモを足していく機能とされている。記事や本のような、学んだことを後から整理した完成稿とは異なり、今まさに取り組んでいる作業、まだ解決していない問題、学習の過程をリアルタイムに残すために使う。

公開中の Scrap 一覧には、調査や試行錯誤のログ、学習・開発記録、参考情報の収集、小さな問題の解決履歴などがある。コメントが 1 件だけの短いメモも、長期間にわたり多数のコメントを追加する記録もあり、最初から記事のように完成させる必要はない。必要に応じてトピックを付け、問題の解決や情報のまとまりを区切る時に Close する。他のユーザーとの意見交換を目的とする場合はコメント投稿を許可できる。

Scrap へ投稿する時は、次を意識する。

• 原則として、複数の話題を含む長文を 1 コメントにまとめるより、小さなコメントを複数追加する。
• 意味、作業対象、概念、使用したツール、または調査・作業の時系列上の一区切りを目安にコメントを分ける。1 つの発見、仮説、試行、結果、次の課題はそれぞれ自然な区切りになりうる。
• 区切りや順序を整えるためだけに、投稿済みのコメントを削除したり編集したりしない。訂正や追加情報は、新しいコメントとして積み上げてもよい。
• 形式を厳守して筆が止まることを避ける。タイトル、構成、結論が暫定的でも、作業中の知見をラフに追加していく。

セットアップ方法

npm または pnpm を使い、次の 3 種類から選ぶ。

方法	npm	pnpm	インストール後の実行
グローバルインストール	npm i -g zenn-cli	pnpm add -g zenn-cli	zenn scrap ...
プロジェクトへのインストール	npm i -D zenn-cli	pnpm add -D zenn-cli	npm exec -- zenn scrap ... または pnpm exec zenn scrap ...
直接実行	npx zenn-cli scrap ...	pnpm dlx zenn-cli scrap ...	インストール操作なしで実行

プロジェクトへインストールした場合は、そのプロジェクトのディレクトリで実行する。以降の zenn は、選んだ方法に応じて npm exec -- zenn、pnpm exec zenn、npx zenn-cli、または pnpm dlx zenn-cli に置き換える。

実行方法

API キーは、実行前に環境変数 ZENN_API_KEY に設定する。値を表示したり、コマンド引数へ直書きしたりしない。

操作前にエージェント自身が次のヘルプを読み、利用可能なコマンド、引数、オプション、必要な権限、環境変数、出力形式を確認する。

zenn --help
zenn scrap --help

ヘルプの確認は、ユーザーへ確認作業を依頼するための手順ではない。取得した仕様に従って目的の操作を実行する。

ユーザー向け環境変数

CLI を起動するシェルで設定する。以下はユーザーが実行時に設定する変数であり、ビルド用・開発内部用の変数は含めない。

API 接続

変数	必須条件・既定値	用途
ZENN_API_KEY	API 操作時に必須	Zenn の API キー。操作に必要な scope を持つキーを設定する。
ZENN_API_BASE_URL	任意。既定値は https://zenn.dev	開発・テスト用の接続先 origin。HTTPS、または http://localhost のみ使用できる。ポートは指定可能。認証情報、ルート以外のパス、クエリ、フラグメントは指定できない。API キーが送信されるため、信頼できる接続先だけを設定する。

Scrap の安全設定

変数	設定値・既定値	用途
ZENN_CLI_FORCE_SAFE	true / false。既定値は false	true では Secret scan と AI scan の両方を必須にし、scan のスキップを拒否する。AI scan を自動で有効にはしないため、ZENN_CLI_AI_SCAN=true とプロバイダーの設定も必要。
ZENN_CLI_FORCE_UNLISTED	true / false。既定値は false	true では Scrap 作成を常に限定公開にする。

Secret scan は既定で有効であり、有効化のための環境変数は不要。

AI scan

変数	必須条件・設定値・既定値	用途
ZENN_CLI_AI_SCAN	true / false。既定値は false	true で AI scan を有効にする。
ZENN_CLI_AI_PROVIDER	AI scan 利用時に必須。生成モデルは openai / fireworks / anthropic / openrouter、判定モデルは openai-decisions / jev / clef	送信先の AI プロバイダー。
ZENN_CLI_AI_MODEL	既定値は openai / openai-decisions が gpt-6-luna、jev が jev-latest、clef が clef-flash（clef も指定可）。fireworks / anthropic / openrouter では必須	利用するモデル ID。指定する場合は空文字不可。
ZENN_CLI_AI_EFFORT	none / low / medium / high。既定値は medium	生成モデルの推論量。none は推論設定を送信しない。モデルが対応する値を選ぶ。判定モデルでは使用しない。
ZENN_CLI_AI_SCAN_FAILURE_THRESHOLD	low / medium / high / critical。既定値は high	この重要度以上の指摘がある場合に投稿を拒否する。
ZENN_CLI_AI_SCAN_PROBABILITY_THRESHOLD	0 より大きく 1 より小さい数値。既定値は 0.5	判定モデルで、検知事項や重要度を該当とみなす確率。
ZENN_CLI_AI_SCAN_PROMPT	任意。未設定時は組み込みの検知方針。空文字不可	検知方針をカスタマイズするプロンプト。外部プロバイダーに送信されるため、機密情報を書かない。
ZENN_CLI_AI_JEV_IMAGES	true / false。既定値は false	true で Jev による画像の AI scan を許可する。TypeSafe の実験的機能のため、明示的に有効にする。
OPENAI_API_KEY	openai / openai-decisions 利用時に必須	OpenAI の API キー。
FIREWORKS_API_KEY	fireworks 利用時に必須	Fireworks の API キー。
ANTHROPIC_API_KEY	anthropic 利用時に必須	Anthropic の API キー。
OPENROUTER_API_KEY	openrouter 利用時に必須	OpenRouter の API キー。ZDR（Zero Data Retention）のエンドポイントだけへ振り分けるため、ZDR 非対応のモデルは利用できない。
TYPESAFE_API_KEY	jev 利用時に必須	TypeSafe の API キー。
CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID	clef 利用時に必須	Workers AI の API トークンとアカウント ID。

判定モデル（openai-decisions / jev / clef）は文章を生成せず、検知事項ごとの確率を返す。指摘には固定の分類名と確率だけを表示する。Clef は一度に検査できる長さ（24,576 トークン）を超えた場合や、処理したトークン数が上限に近く未検査の部分が残った可能性がある場合は、投稿せずに終了する。

画像操作に必要な権限と使い方は zenn image --help で確認する。ZENN_CLI_AI_SCAN=true の場合は画像のアップロード前にも AI scan を実行し、画像とファイル名を AI プロバイダーへ送信する。画像を扱えないモデルや形式（Jev では PNG・JPEG で縦横 280〜1568px、Clef では PNG・JPEG・WebP）や、全フレームを検査できないアニメーション画像の場合はアップロードせずに終了する。

判定モデルでは、認証情報を該当と判定した場合は critical、そのほかの分類は high 以上として扱い、重要度の回答だけで検知を弱めない。

Scrap 操作の方針

• 作成時は公開範囲と他者投稿可否を明示する。指定がなければ限定公開かつ他者投稿禁止とし、作業ログは通常 Open のまま開始する。
• 本文はまとまりごとに Markdown ファイルへ用意し、小さなコメントとして追加する。
• Scrap の本文やコメントを書く時は、Zenn の Markdown 記法一覧を参照し、Zenn で表示できる記法で書く。コードブロック（ファイル名・diff）、メッセージ（:::message）、アコーディオン（:::details）、リンクカードや各種埋め込み、数式、mermaid のダイアグラムなどは、この記法一覧に従う。
• 誤りの訂正や新しい知見は、新規コメントで追記することを優先する。既存本文そのものを直す必要がある場合だけ更新する。
• 既存 Scrap を公開へ変更する前に、対象、所有者、現在の公開範囲、タイトル、全コメント、トピックを確認し、公開してよい内容だけであることを再検査する。
• 限定公開 Scrap の URL と slug は秘密情報として扱う。
• 後続処理で結果を使う場合は、ヘルプに記載された機械可読出力を使い、説明文を標準出力へ混ぜない。

投稿前の安全確認

Zenn Scrap は不特定多数に公開される。限定公開でも URL または slug を知る人は閲覧できるため、投稿前に本文、タイトル、トピックを確認し、次の情報をマスクまたは除外する。

• 内部 URL、内部ドメイン、顧客名、個人情報、認証情報、未公開の事業情報
• リクエスト ID、GitHub Private リポジトリの URL、そのほか組織内部の識別子や運用情報

Secret scan は通常スキップしない。scan の有効化や設定方法は zenn scrap --help に従う。

AI scan は投稿内容や追加指示を外部プロバイダーへ送るため、送信先、保持、学習利用、リージョン、契約条件についてユーザーの許可と適合性を確認する。機密情報は scan 前にローカルで除去し、AI 向けの備考や追加プロンプトにも機密情報を書かない。