Zenn CLIの使い方｜インストールから記事作成・GitHub連携での公開まで【0.5.13対応】

Zenn CLIは、Zennの記事や本を手元のMarkdownファイルとして書き、ブラウザでプレビューするための公式ツールです。記事を公開するコマンドはありません。公開は、連携したGitHubリポジトリの登録ブランチへpushして行います。一方で2026年10月からは、Public API経由でScrapの投稿と画像のアップロードもCLIから実行できるようになり、CLIの役割が広がりました。

本記事では、2026年10月30日に公開されたzenn-cli 0.5.13をNode.js v26.5.0の環境で動かし、ヘルプとエラーメッセージ、プレビューの出力を確かめたうえで、インストールから公開、Scrap投稿までを順に解説します。

まとめ：Zenn CLIで押さえる要点

• 導入は npm init --yes → npm install zenn-cli → npx zenn init の3手順です。0.5.13はpackage.jsonで Node.js 22.12.0以上 を要求します（公式インストール記事の「14以上」は古い記述です）。
• 0.5.13のヘルプに表示されるコマンドは8つです。記事・本を扱う6つに、Public APIを使う zenn scrap と zenn image が加わりました。
• 記事のslugは半角英小文字・数字・ハイフン・アンダースコアの12〜50字です。front matterはtitle 70字以内、topicsは5つまで・各18字以内で、記号は使えません。slugを変えると別記事として扱われます。
• 公開はGitHub連携で行い、published: true が条件です。2026年8月26日からは個人の連携でも、PRの内容を下書きとしてデプロイできます。
• リポジトリに置く画像は /images 配下（サブフォルダ可）・3MB以内・png/jpg/jpeg/gif/webpです。zenn image upload でアップロードした画像は公開URLで配信されます。
• Scrapの操作には、APIキー設定ページで発行したキーを ZENN_API_KEY に設定します。Public APIは不安定版（v0）で、仕様は予告なく変わる可能性があります。

Zenn CLIの役割とWebエディタとの使い分け

Zennの投稿方法は、ブラウザ上のWebエディタと、GitHubリポジトリ連携の2通りです。Zenn CLIは後者のためのツールで、記事・本の執筆では「ファイルの雛形を作る」「手元でプレビューする」役割を担います。記事のアップロードやログインの機能はありません。

0.5.13で npx zenn --help を実行すると、次の8つのコマンドが表示されます。

Git管理の手間に見合うのは、記事を継続的に書く人や、エディタの補完・校正ツールを使いたい人です。1本だけ試すならWebエディタで足ります。

ブラウザ上のVS Code（github.dev）で書いてきた人は注意が必要です。Zennは2026年8月19日に、拡張機能「Zenn Preview for github.dev」の提供終了を予告しました。2026年10月末を目処にリポジトリをアーカイブし、Marketplaceからも削除する予定で、代替としてzenn-cliのプレビューを案内しています（2026年11月5日時点では、リポジトリはまだアーカイブされていません）。手元のエディタでMarkdownのプレビュー環境を整えるなら、Markdown Live Editorの使い方と注意点｜VS Code組み込みエディタとの違い【2026年10月】も参考になります。

インストール手順とNode.jsのバージョン要件

公式ガイド（Zenn CLIで記事・本を管理する方法）の手順は、作業用ディレクトリで次の3つを実行するものです。

npm init --yes
npm install zenn-cli
npx zenn init

npx zenn init の実行後にできるのは次のファイルです（node_modulesを除く）。articles と books の中身は空ディレクトリをGitに載せるための .keep だけで、設定ファイルは作られません。古い解説で見かける zenn.json は生成されません。

./README.md
./.gitignore
./package.json
./package-lock.json
./articles/.keep
./books/.keep

Node.jsのバージョンには注意が要ります。公式の「Zenn CLIをインストールする」は今も「Node.js 14以上が必要」と書いていますが、npmレジストリに登録された0.5.13のpackage.jsonは "engines": { "node": ">=22.12.0" } です。node -v で22.12.0以上であることを先に確かめてください。版の選び方はNode.jsとは？仕組み・版の選び方・標準機能で動かす手順を実装目線で解説で整理しています。

更新は npm install zenn-cli@latest、版の確認は npx zenn -v で行います。npmレジストリには、2026年9月の0.5.4のあと10月30日の0.5.13までに8つの正式版が公開されました（GitHubでリリースされた0.5.12はnpmに公開されていません）。zenn-editorのREADMEは「厳密なセマンティックバージョニングに従っていません」「破壊的な変更を含むバージョンアップはマイナーバージョンアップで対応」と明記しています。実際には0.5.7のようにパッチ番号の更新でもチャプターの解釈が変わった例があるため（後述）、リリースノートを読んでから更新すると安全です。共同執筆やCIで版をそろえるには、ローカルインストール後のpackage-lock.jsonをGitで共有し、依存関係を復元するときは npm ci を使います。

記事の作成とfront matterの制約

new:articleのオプションとslugの規則

npx zenn new:article を引数なしで実行すると、ランダムなslugでファイルが作られます。slugは記事URLの一部になり、後から変えると別の記事として作成されてしまうため、内容が分かる文字列を最初から指定します。

npx zenn new:article --slug zenn-cli-issoh-test01 --title テスト --type tech --emoji ✨
created: articles/zenn-cli-issoh-test01.md

生成されたファイルの中身です。

---
title: "テスト"
emoji: "✨"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: []
published: false
---

slugの規則に反すると、ファイルは作られず次のエラーが出ます（12字未満の short を指定した例）。

error: slugの値（short）が不正です。小文字の半角英数字（a-z0-9）、ハイフン（-）、アンダースコア（_）の12〜50字の組み合わせにしてください

ほかに --published（既定はfalse）、--publication-name（Publicationに紐付ける場合）、--machine-readable（作成したファイル名だけを出力）があります。

front matterの項目と検証ルール

プレビュー画面は、front matterの誤りをエラーとして表示します。npmで配布されている0.5.13のパッケージから、クライアント側に組み込まれた検証ルールを抜き出すと次のとおりです。

topicsで記号が使えないため、C++は cpp、C#は csharp と書きます。tags と書くと「tagsではなくtopicsを使ってください」というエラーになります。

予約投稿と過去日時での公開（published_at）

公開日時を指定するときは published_at を追加します。タイムゾーンは日本時間（JST）で、日付だけを書くと00:00として扱われます。

---
title: "予約投稿の例"
emoji: "✨"
type: "tech"
topics: ["zenn", "markdown"]
published: true
published_at: 2026-12-01 09:00
---

未来の日時を指定するときも published: true にしておきます。検証メッセージは「公開日時を過ぎるとZennのサービス上で自動的に公開されます」という趣旨です。逆に過去の日時を書くと、その日時を公開日として公開されます。公式ガイドは、他のブログサービスから移行して元の公開日を残したい場合の使い方として紹介しています。どちらの場合も公開日時の指定は一度しかできず、設定済みの値は変更できないので、日時を確定させてからpushしてください。

プレビューの起動オプション

npx zenn preview を実行すると、既定では http://localhost:8000 でプレビューサーバーが起動し、ファイルを保存すると自動で再読み込みされます。

8000番を別のアプリが使っているなら npx zenn preview --port 3000 のように変えます。front matterの誤りや画像サイズの超過はプレビュー画面にエラーとして出るので、pushの前に一度開いて確認すると、デプロイの失敗を減らせます。本のチャプターも0.5.4から、目次と前後のチャプターへの移動リンク付きでプレビューされるようになりました（Zennの告知）。

0.5.13では、言語名を html-embed にしたコードブロックをプレビューが既定でiframeとして描画するようになりました。0.5.13で次のブロックを書いてプレビューのAPIが返すHTMLを確かめると、本文は https://embed.zenn.studio/html を読み込む sandbox="allow-scripts" 付きのiframeに置き換わっていました。

```html-embed
<div class="box">図</div>
<style>.box { padding: 16px; }</style>
```

ただし、この記法は公式のMarkdown記法一覧には載っていません。変換ライブラリzenn-markdown-htmlではこの機能が既定で無効のままで、有効にしているのはzenn-cliのプレビューだけです（PR #756）。プレビューで表示できても、zenn.devの本番で同じように表示されるとは限らないため、公開する記事では使わないでください。

画像の配置ルールと3MBの上限

記事に画像を入れる方法は3通りあります。Zennのダッシュボードのアップロードページで画像を上げてURLを貼る方法、GitHubリポジトリに画像を置く方法、0.5.5以降の zenn image upload でアップロードする方法です。記事と一緒にバージョン管理するなら、リポジトリに置く方法が扱いやすくなります。

リポジトリに置く場合のルールは次のとおりです。

• 置き場所はリポジトリ直下の /images ディレクトリです。中のフォルダ構成は自由です。
• ファイルサイズは3MB以内、拡張子は .png .jpg .jpeg .gif .webp のみです。違反するとデプロイがエラーになります。
• 参照は /images/ から始まる絶対パスで書きます。相対パスでは表示されません。

![](/images/zenn-cli/preview.png)
![](/images/zenn-cli/preview.png =250x)
*画像のキャプション*

URLの後ろに半角スペースを空けて =250x と書くと、表示幅をピクセル単位で指定できます。画像の直下の行を * で囲むとキャプションになります。

zenn image は、Public API経由で画像をZennに上げ、表示された画像URLを記事・本・ScrapのMarkdownに貼る使い方です。対応形式はJPEG・PNG・GIF・WebPで、3MB以下という条件はリポジトリに置く場合と同じです。アップロードには image:write、一覧の取得には image:read の権限を持つAPIキーが必要です（キーの発行は後述）。

npx zenn image upload ./images/diagram.png --confirm-public
npx zenn image list --count 20
npx zenn image delete IMAGE_ID --yes

--confirm-public は必須の確認フラグです。ヘルプは、アップロードした画像は公開URLで配信されURLを知る人が閲覧できること、自動的には削除されないこと、本で使用中の画像は削除できないことを明記しています。社内の画面キャプチャなど機密情報が写り得る画像は、このコマンドで上げないでください。

GitHub連携で記事を公開・更新する手順

公開までの流れは次のとおりです。リポジトリは公開・非公開のどちらでも連携できます。

1. GitHubにリポジトリを作り、npx zenn init を実行したディレクトリをpushします。
2. Zennのダッシュボードの「GitHubからのデプロイ」（https://zenn.dev/dashboard/deploys）で「リポジトリを連携」を選びます。
3. GitHub側の画面で「Only select repositories」を選んで対象リポジトリだけにチェックを入れ、「Install & Authorize」で許可します。
4. Zennのリポジトリ設定で、同期するブランチ名を確認します。
5. 記事のfront matterを published: true にして、登録ブランチへpushします。

登録ブランチへのpushとプルリクエストのマージで、zenn.devへの同期（デプロイ）が始まります。記事の更新も同じで、ファイルを直してpushするだけです。反映には少し時間がかかり、ログインしていない状態ではキャッシュされた古い内容がしばらく表示されることがあります。コミットメッセージに [ci skip] か [skip ci] を含めると、そのpushではデプロイされません。

削除だけは例外で、GitHubからファイルを消してもZenn上の記事は残ります。安全のための仕様で、完全に削除するにはダッシュボードの投稿管理とGitHubリポジトリの両方から削除します。GitHubにファイルを残すと、次回デプロイ時に記事が復活します。

PR下書きデプロイの設定と対象範囲

登録ブランチ向けのプルリクエスト（PR）を作成・更新・再オープンすると、その内容をZenn上の下書きとして自動でデプロイできます。2026年5月18日にPublicationで始まり、2026年8月26日から個人のGitHub連携でも使えるようになりました。GitHub上でレビューを進めながら、Zennでの表示を確認する用途です。

1. GitHubリポジトリ設定（https://zenn.dev/dashboard/deploys?tab=repo_settings）を開きます。
2. 対象リポジトリの「設定を変更」から「デプロイ対象ブランチに対するPRの作成・更新で下書きデプロイを実行する」を有効にします。
3. 2026年5月18日以前に連携を設定していた場合は、GitHubの https://github.com/settings/installations で、GitHub App「Zenn Connect」の権限更新リクエストを承認（Accept）します。

対象は同一リポジトリ内のPRだけで、ForkからのPRは含まれません。下書きとして保存されるのはPRの articles/ と新規の images/ で、公開済み・予約公開済みの記事は更新されません。注意したいのは後片付けで、PRをcloseやmergeしても、デプロイ済みの下書きや画像は自動では消えません。共同作業者のPRも対象になるため、機微な情報を含むPRがあり得るリポジトリでは有効にしないでください。

pushしても反映されないときの確認順

反映されない場合は、まずデプロイ履歴で同期の有無とエラーを確認し、続いてブランチ・公開設定・ファイル配置を点検します。

1. デプロイ履歴（https://zenn.dev/dashboard/deploys）にエラーが出ていないか。画像のサイズ超過やfront matterの誤りはここに表示されます。履歴そのものが無い場合は、GitHub側（Zenn Connect）で許可したリポジトリと、Zennで連携したリポジトリが一致しているかを確認します。
2. pushしたブランチが、連携時に登録したブランチと同じか。
3. front matterが published: false のままになっていないか。
4. ファイルが articles 直下にあり、ファイル名がslugの規則（12〜50字）を満たしているか。slugを途中で変えていれば、別記事として作られています。
5. コミットメッセージに [ci skip] などが入っていないか。
6. 連携対象として3つ以上のリポジトリを選んでいないか。上限は2つで、3つ以上選ぶと連携そのものが失敗します。

本（books）の構成とconfig.yaml

npx zenn new:book --slug zenn-cli-issoh-book01 を実行すると、次の3ファイルが作られます。本のslugも記事と同じく12〜50字の規則です。

created: books/zenn-cli-issoh-book01/config.yaml
created: books/zenn-cli-issoh-book01/example1.md
created: books/zenn-cli-issoh-book01/example2.md

生成された config.yaml です。

title: ""
summary: ""
topics: []
published: false
price: 0 # 有料の場合200〜5000
# 本に含めるチャプターを順番に並べましょう
chapters:
  - example1
  - example2

price は無料なら0、有料なら200〜5000円を100円単位で指定します。chapters にはチャプターファイルのslugを、拡張子 .md を付けずに表示順に並べます。example1.md なら example1 です。ここに書かなかったチャプターはZennに同期されません。拡張子を付けたりネストした配列を書いたりすると、プレビューでエラーになります。

チャプターは1冊あたり最大100個です。ファイル名を 1.intro.md 2.setup.md のように「チャプター番号.slug.md」にして番号順に並べる方法もあり、その場合は config.yaml の chapters を空にしておく必要があります。目次は既定でh1とh2まで表示され、toc_depth に0〜3を指定して深さを変えられます（0で非表示）。

有料の本でチャプターを無料公開する free は、小文字の true か false で書いてください。0.5.7でチャプターのfront matterの解析が記事と同じ方式（js-yamlのJSON_SCHEMA）に揃い（PR #730）、free: True は真偽値でなく文字列 "True" として読まれます。0.5.13のプレビューAPIでも free: True は文字列 "True" で返り、検証ルールの「free（無料公開設定）には true もしくは false のみを指定してください」に当たります。古い版で通っていた本を更新するときに引っかかりやすい点です。

Zenn独自のMarkdown記法

ZennのMarkdownは標準的な記法に加えて、独自のブロックと埋め込みを持ちます。いずれもプレビューで表示を確かめられます。

図を描く ```mermaid には制限があり、1ブロック2000字まで、& によるチェーンは10までです。大きな図は分割してください。記法そのものはMermaid記法の使い方｜無料のLive Editor（mermaid.live）でフローチャート・シーケンス図を作成で解説しています。

ローカルでMarkdownを書くと、pushの前に校正ツールを通せます。表記ゆれや冗長な表現の検出には、textlintとは？日本語の文章校正をVS Code・CIで回す設定手順【v15.8対応】で紹介しているtextlintが使えます。

Public APIによるScrap投稿の手順（0.5.7以降）

Zennは2026年10月20日にZenn Public APIをリリースし、CLIからScrapの作成・コメント投稿と画像のアップロードができるようになりました。告知はこれらのコマンドに0.5.7以上が必要だとしています。0.5.4の時点では環境変数 ZENN_CLI_EXPERIMENTAL_SCRAP_API=true を付けたときだけ動く隠しコマンドでしたが、0.5.5でこの実験フラグが撤去され、通常のヘルプに表示されるようになりました。記事・本の公開には関係しない機能です。

APIキーの発行とscrapコマンド

APIキーはAPIキー設定ページで、使う操作に必要な権限を選んで発行します。キーは発行時に一度だけ表示されるので、安全な場所に保存し、環境変数 ZENN_API_KEY に設定します。Scrapの読み取りには scrap:read、作成・投稿には scrap:write の権限が必要です。キーが無いまま実行すると「ZENN_API_KEY を環境変数に設定してください」で止まります。

npx zenn scrap create --title "開発中の調査メモ" --file ./memo.md --unlisted --disallow-others-post
npx zenn scrap post 'ScrapのURL' --file ./next-memo.md
npx zenn scrap list
npx zenn scrap get 'ScrapのURL'

--file に渡したMarkdownが最初のコメントになり、- を指定すると標準入力から読みます。サブコマンドは、list get create update comments post update-comment delete delete-comment の9つです。delete と delete-comment は取り消せない操作のため --yes が必須で、追加時のPRによると、Scrapの削除は自分のアーカイブ済みScrapだけが対象です。後続の処理で結果を使うなら --machine-readable を付けると、createとpostはURL、それ以外はレスポンスのJSONを1行で出力します。

限定公開（--unlisted）でも、URLを知っている人は閲覧できます。CLIなどAPI経由で作ったScrapや投稿したコメントには、日時表示に「APIで投稿」のような文言が付き、Web UIからの投稿と区別されます。Public APIは不安定版（v0）で、APIやコマンドの仕様は予告なく変更される場合があります。スクリプトに組み込むなら版を固定し、更新のたびにヘルプを読み直してください。

投稿前のSecret scanとAI scan

Scrapの投稿前には、APIキーなどの秘密情報を検出するSecret scanが既定で動きます。AIによる内容検査（AI scan）は ZENN_CLI_AI_SCAN=true を指定し、ZENN_CLI_AI_PROVIDER とプロバイダーの認証情報を設定したときだけ有効になります。openai・openai-decisions・jev・clef以外のプロバイダーは既定モデルを持たないため、ZENN_CLI_AI_MODEL でモデルIDの指定も必要です。0.5.13で選べるプロバイダーは、openai・fireworks・anthropic・openrouter・bedrock・vertex・vertex-anthropic・azureの生成モデル8種と、openai-decisions・jev・clefの判定モデル3種の計11種です（0.5.4ではopenaiとfireworksの2種）。

AI scanでは、タイトル・本文・topics・notes-to-ai・AI scan用のプロンプトが、選んだプロバイダーへ送信されます。公式のZenn CLI Skillは、bedrockとazureでAPIキーを設定しない場合や、vertex系を使う場合は、手元の既定の認証情報（AWSプロファイル、Azure CLI、gcloudのADCなど）が自動で使われると注意しています。会社のクラウドアカウントに課金や呼び出しログが残る可能性があるため、社内情報を扱う端末では送信先のアカウントを確かめてから有効にしてください。ZENN_CLI_FORCE_SAFE=true は両方のscanを必須にしますが、AI scanを自動で有効にはしません。別途AI scanの有効化とプロバイダー・モデル・認証情報の設定が必要です。

このSkillはAIコーディングエージェント向けの手順書で、npx skills add zenn-dev/zenn-editor --skill zenn-cli で取り込めます。なお告知は、記事・本では引き続き「人が主体となって情報を発信すること」を大切にするとし、AIと調べた内容や作業の記録はScrapに残す使い分けを勧めています。

よくある質問

Zenn CLIに必要なNode.jsのバージョンは？

zenn-cli 0.5.13は、package.jsonでNode.js 22.12.0以上を要求しています。公式のインストール記事には「14以上」とありますが、現行版には当てはまりません。

Zenn CLIで記事を公開するコマンドはありますか？

ありません。記事は、Zennと連携したGitHubリポジトリの登録ブランチへpushすると公開されます。front matterの published がtrueになっている必要があります。CLIからAPIで投稿できるのはScrapと画像だけです。

Zennで予約投稿はできますか？

できます。front matterに published_at: 2026-12-01 09:00 のように日本時間で指定し、published をtrueにしてpushします。公開日時の指定は一度しかできず、後から変更できません。

Zennに載せられる画像のサイズ上限は？

1ファイル3MB以内です。GitHubリポジトリの /images に置く場合はpng・jpg・jpeg・gif・webp、zenn image upload の場合はJPEG・PNG・GIF・WebPに対応します。表示幅は画像URLの後ろに =250x のように書いて調整します。

Zennの記事に動画を埋め込めますか？

YouTubeなら @[youtube](動画のURL) と書くと埋め込めます。ほかにSpeaker Deck、CodePen、Figmaなども専用の記法で埋め込めます。

関連記事

• Node.jsとは？仕組み・版の選び方・標準機能で動かす手順を実装目線で解説
• Mermaid記法の使い方｜無料のLive Editor（mermaid.live）でフローチャート・シーケンス図を作成
• textlintとは？日本語の文章校正をVS Code・CIで回す設定手順【v15.8対応】
• Markdown Live Editorの使い方と注意点｜VS Code組み込みエディタとの違い【2026年10月】
• MkDocsとは？使い方とMaterial for MkDocsの設定・日本語検索・GitHub Pages公開【2026年版】