Zenn CLIは、Zennの記事や本をローカルのMarkdownファイルとして書き、ブラウザでプレビューするための公式ツールです。ただしCLIに公開用のコマンドはありません。公開は、連携リポジトリの登録ブランチへpushし、公開設定と予約日時の条件を満たしてデプロイが完了すると行われます。この仕組みを知らないまま手順だけを追うと、pushしたのに記事が出ない、画像だけ表示されないといった所でつまずきます。
本記事では、2026年9月に公開されたzenn-cli 0.5.4をNode.js v26.5.0の環境で実際に動かし、コマンドの出力とエラーメッセージを確かめたうえで、インストールから公開までを順に解説します。
まとめ：Zenn CLIで押さえる要点
- 導入は
npm init --yes→npm install zenn-cli→npx zenn initの3手順です。0.5.4はpackage.jsonで Node.js 22.12.0以上 を要求しています（公式のインストール記事の「14以上」は古い記述です）。 - 通常のヘルプに表示されるサブコマンドは init・preview・new:article・new:book・list:articles・list:books の6つです。
zenn.jsonという設定ファイルは生成されません。 - 記事のslugは半角英小文字・数字・ハイフン・アンダースコアの12〜50字です。front matterはtitle 70字以内、topicsは5つまで・各18字以内で、記号は使えません。
- 公開はGitHub連携で行います。登録ブランチへのpushで同期され、front matterの
published: trueが公開の条件です。連携できるリポジトリは最大2つです。 - 画像はリポジトリ直下の
/imagesに置き、3MB以内・png/jpg/jpeg/gif/webpに限られます。参照は/images/から始まる絶対パスで書きます。 - 0.5.3以降には、環境変数で有効化する実験的な
zenn scrapコマンドがあります。通常のヘルプには表示されません。
Zenn CLIの役割とWebエディタとの使い分け
Zennの投稿方法は、ブラウザ上のWebエディタと、GitHubリポジトリ連携の2通りです。Zenn CLIは後者のためのツールで、記事・本の執筆では、主に「ファイルの雛形を作る」「手元でプレビューする」ために使います。記事のアップロードやログインの機能は持っていません。
0.5.4で npx zenn --help を実行すると、表示されるコマンドは次の6つです。
| コマンド | 用途 |
|---|---|
npx zenn init |
管理用ディレクトリを作成（初回のみ） |
npx zenn preview |
ブラウザでプレビュー |
npx zenn new:article |
記事ファイルを追加 |
npx zenn new:book |
本の雛形を追加 |
npx zenn list:articles |
記事の一覧を表示 |
npx zenn list:books |
本の一覧を表示 |
Git管理の手間に見合うのは、記事を継続的に書く人や、エディタの補完・校正ツールを使いたい人です。Git管理もローカルでの校正も要らず、1本だけ試しに書くなら、セットアップのいらないWebエディタを勧めます。VS Codeなど手元のエディタでMarkdownのプレビュー環境を整えたい場合は、Markdown Live Editorの選び方｜VS Code拡張と無料ツールを比較も参考になります。
インストール手順とNode.jsのバージョン要件
公式ガイド（Zenn CLIで記事・本を管理する方法）の手順は、作業用ディレクトリで次の3つを実行するものです。
npm init --yes
npm install zenn-cli
npx zenn initnpx zenn init の実行後にできるファイルは次のとおりです（node_modulesを除く）。articles と books は空ディレクトリをGitに載せるための .keep だけで、設定ファイルは作られません。旧来の解説で見かける zenn.json は、0.5.4では生成されません。
./README.md
./.gitignore
./package.json
./package-lock.json
./articles/.keep
./books/.keepNode.jsのバージョンには注意が要ります。公式の「Zenn CLIをインストールする」は今も「Node.js 14以上が必要」と書いていますが、npmレジストリに登録された0.5.4のpackage.jsonは "engines": { "node": ">=22.12.0" } です。古いNode.jsでは実行時に失敗する可能性があるため、node -v で22.12.0以上であることを先に確認してください。バージョンの選び方はNode.jsとは？仕組み・版の選び方・標準機能で動かす手順を実装目線で解説で整理しています。
更新は npm install zenn-cli@latest、現在の版の確認は npx zenn -v で行います。グローバルインストール（npm install -g zenn-cli）も公式に容認されていますが、リポジトリごとに版を固定できるローカルインストールの方が、共同執筆や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.4のパッケージから、クライアント側に組み込まれた検証ルールを抜き出して整理すると次のとおりです。
| 項目 | 値 | 検証ルール |
|---|---|---|
title |
記事タイトル | 70字以内 |
emoji |
アイキャッチの絵文字 | 1つだけ |
type |
tech または idea | 技術記事かアイデア記事か |
topics |
タグの配列 | 最大5つ・各18字以内・記号とスペース不可 |
published |
true または false | 引用符で囲まない真偽値 |
published_at |
公開日時（任意） | YYYY-MM-DD または YYYY-MM-DD hh:mm |
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-10-01 09:00
---未来の日時を指定する場合は published: true にしておく必要があります。0.5.4の検証メッセージも「published（公開設定）に true を指定してください（公開日時を過ぎるとZennのサービス上で自動的に公開されます）」という趣旨です。また公式ガイドによると、公開日時の指定は一度しかできず、設定済みの値は変更できません。日時を確定させてからpushしてください。
プレビューの起動オプション
npx zenn preview を実行すると、既定では http://localhost:8000 でプレビューサーバーが起動します。ファイルを保存すると自動で再読み込みされます。
| オプション | 動作 |
|---|---|
--port PORT（-p） |
ポートを変更（既定8000） |
--no-watch |
ホットリロードを無効化 |
--open |
起動時にブラウザを開く |
--host |
ホスト名を指定 |
8000番を別のアプリが使っているなら npx zenn preview --port 3000 のように変えます。front matterの誤りや画像の問題はプレビュー画面にエラーとして出るので、pushの前に一度開いて確認する習慣をつけると、デプロイ失敗を減らせます。
画像の配置ルールと3MBの上限
画像の入れ方は2通りです。Zennのダッシュボードにあるアップロードページで画像を上げてURLを貼る方法と、GitHubリポジトリに画像を置く方法です。CLIで管理するなら、記事と一緒にバージョン管理できる後者が扱いやすいでしょう。
リポジトリに置く場合のルールは次のとおりです。
- 置き場所はリポジトリ直下の
/imagesディレクトリです。中のフォルダ構成は自由です。 - ファイルサイズは3MB以内、拡張子は
.png.jpg.jpeg.gif.webpのみです。違反するとデプロイがエラーになります。 - 参照は
/images/から始まる絶対パスで書きます。相対パスでは表示されません。
*画像のキャプション*URLの後ろに半角スペースを空けて =250x と書くと、表示幅をピクセル単位で指定できます。画像の直下の行を * で囲むとキャプションになります。0.5.4のプレビュー側にも「ファイルサイズは3MB以内にしてください」という警告文が組み込まれており、pushの前にサイズ超過に気付けます。
GitHub連携で記事を公開・更新する手順
公開までの流れは次のとおりです。リポジトリは公開・非公開のどちらでも連携できます。
- GitHubにリポジトリを作り、
npx zenn initを実行したディレクトリをpushします。 - Zennのダッシュボードの「GitHubからのデプロイ」（
https://zenn.dev/dashboard/deploys）で「リポジトリを連携」を選びます。 - GitHub側の画面で「Only select repositories」を選んで対象リポジトリだけにチェックを入れ、「Install & Authorize」で許可します。
- Zennのリポジトリ設定で、同期するブランチ名を確認します。
- 記事のfront matterを
published: trueにして、登録ブランチへpushします。
登録ブランチへのpushとプルリクエストのマージで、zenn.devへの同期（デプロイ）が始まります。記事の更新も同じで、ファイルを直してpushするだけです。
レビューを挟みたい場合は、リポジトリ設定でPR下書きデプロイを有効にします。登録ブランチ向けのプルリクエストを作成・更新すると、記事が下書きとしてデプロイされます。ただし公開済み・公開予約済みの記事は更新されず、Forkリポジトリからのプルリクエストも対象外です。コミットメッセージに [ci skip] か [skip ci] を含めると、そのpushではデプロイされません。
削除だけは例外で、GitHubからファイルを消してもZenn上の記事は残ります。ダッシュボードの投稿管理から削除する必要があります。
pushしても反映されないときの確認順
反映されない場合は、まずデプロイ履歴で同期の有無とエラーを確認し、続いてブランチ・公開設定・ファイル配置を点検します。
- デプロイ履歴（
https://zenn.dev/dashboard/deploys）にエラーが出ていないか。画像のサイズ超過やfront matterの誤りはここに表示されます。履歴そのものが無い場合は、GitHub側（Zenn Connect）で許可したリポジトリと、Zennで連携したリポジトリが一致しているかを確認します。 - pushしたブランチが、連携時に登録したブランチと同じか。
- front matterが
published: falseのままになっていないか。 - ファイルが
articles直下にあり、ファイル名がslugの規則（12〜50字）を満たしているか。 - コミットメッセージに
[ci skip]などが入っていないか。 - 連携対象として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
- example2price は無料なら0、有料なら200〜5000円を100円単位で指定します。chapters にはチャプターファイルのslugを、拡張子 .md を付けずに表示順に並べます。ここに書かなかったチャプターはZennに同期されません。example1.md なら example1 です。拡張子を付けたりネストした配列を書いたりすると、プレビューでエラーになります。
チャプターは1冊あたり最大100個です。ファイル名を 1.intro.md 2.setup.md のように「チャプター番号.slug.md」にすると、その番号順に並べる方法もあります。この方法でデプロイする場合は、config.yaml の chapters を空にしておく必要があります。
各チャプターの目次は、既定でh1とh2の見出しまで表示されます。toc_depth に0〜3を指定して深さを変えられ、toc_depth: 0 で目次を非表示にできます。
Zenn独自のMarkdown記法
ZennのMarkdownは標準的な記法に加えて、独自のブロックと埋め込みを持ちます。プレビューで表示を確認できるので、CLIで書く利点が出やすい部分です。
| 用途 | 書き方 |
|---|---|
| メッセージ | :::message 〜 ::: |
| 警告メッセージ | :::message alert 〜 ::: |
| アコーディオン | :::details タイトル 〜 ::: |
| ファイル名付きコード | ```js:app.js |
| 差分のハイライト | ```diff js |
| 数式（KaTeX） | $$ で囲む（インラインは $） |
| リンクカード | @[card](URL) |
| YouTube動画 | @[youtube](URL) |
| X（旧Twitter） | @[tweet](URL) またはURLのみの行 |
| その他の埋め込み | @[speakerdeck] @[codepen] @[figma] など |
図を描く ```mermaid には制限があり、1ブロック2000字まで、& によるチェーンは10までです。大きな図は分割してください。記法そのものはMermaid記法の使い方を完全ガイド｜無料のLive Editorでフローチャート・シーケンス図を作成で解説しています。
ローカルでMarkdownを書く利点はもう1つあり、pushの前に校正ツールを通せます。表記ゆれや冗長な表現の検出にはtextlintとは何か？ 文章品質向上を支援するオープンソース校正ツールの特徴と導入メリットを解説で紹介しているtextlintが使えます。
実験的なScrap操作コマンド（0.5.3以降）
zenn-editorのリリースノートによると、2026年8月25日の0.5.3-alpha.5で「Secretlint必須の実験的Scrap投稿CLI」が、9月4日（日本時間）の0.5.4-alpha.1でScrapの取得・更新操作が追加されました。このコマンドは通常の --help には表示されず、npx zenn scrap --help を実行しても「該当するCLIコマンドが存在しません」と返ります。環境変数で有効にすると使えます。
ZENN_CLI_EXPERIMENTAL_SCRAP_API=true npx zenn scrap --help0.5.4で表示されるサブコマンドは list get create update comments post update-comment の7つです。利用には scrap:read または scrap:write スコープを持つAPIキーを ZENN_API_KEY に設定します。
投稿前には、APIキーなどの秘密情報を検出するSecret scanが既定で動きます。AIによる内容チェック（AI scan）は ZENN_CLI_AI_SCAN=true を指定し、プロバイダー（ZENN_CLI_AI_PROVIDER に openai または fireworks）とそのAPIキーを設定すると有効になります。送信対象にはタイトル・本文のほか、topics、notes-to-ai、AI scan用の追加プロンプトも含まれます。社内情報を扱う環境では、この送信先を理解したうえで有効にしてください。実験的機能のため、オプション名や挙動は今後の版で変わる可能性があります。記事や本の投稿には関係しない機能なので、通常の執筆では使わなくて構いません。
よくある質問
Zenn CLIに必要なNode.jsのバージョンは？
zenn-cli 0.5.4は、package.jsonでNode.js 22.12.0以上を要求しています。公式のインストール記事には「14以上」とありますが、現行版には当てはまりません。
Zenn CLIで記事を公開するコマンドはありますか？
ありません。記事は、Zennと連携したGitHubリポジトリの登録ブランチへpushすると公開されます。front matterの published がtrueになっている必要があります。
Zennで予約投稿はできますか？
できます。front matterに published_at: 2026-10-01 09:00 のように日本時間で指定し、published をtrueにしてpushします。公開日時の指定は一度しかできず、後から変更できません。
Zennに載せられる画像のサイズ上限は？
GitHubリポジトリの /images に置く画像は、1ファイル3MB以内で、png・jpg・jpeg・gif・webpに限られます。表示幅は画像URLの後ろに =250x のように書いて調整します。
Zennの記事に動画を埋め込めますか？
YouTubeなら @[youtube](動画のURL) と書くと埋め込めます。ほかにSpeaker Deck、CodePen、Figmaなども専用の記法で埋め込めます。
