はじめに

しばらく実務から離れ、個人開発に Git を使って取り組むことになったため、今までにしたことのなかった Git の使い方をしてみたいと思い、Qiita CLI を使い始めました。
また、作成した文章を Git 管理することで、自身の成長を振り返りやすいのではと思いました。

この記事では、Qiita CLI で記事を投稿するまでの手順と、初めて使って詰まったポイントとその原因 をまとめます。

この記事でわかること

Qiita CLI で記事を書き、GitHub Actions から Qiita に投稿するまでの手順
main にマージしても投稿されないときの原因と直し方
Qiita CLI でできること・できないこと（プレビュー／下書き／画像）
投稿した後に git pull が必要な理由

対象読者

Qiita の記事を GitHub で管理したい人
Qiita CLI や GitHub Actions を初めて使う人

Git の基本操作（ブランチ・コミット・Pull Request）ができる前提で書いています。

環境（2026年10月時点）

項目	バージョン
Qiita CLI（`@qiita/qiita-cli`）	1.12
Node.js	24

Qiita CLI を動かすには、Node.js 22.22.1以上が必要です（公式 README）。

Qiita CLI とは

Qiita CLI は、Qiita が公式に提供しているコマンドラインツールです。手元のエディタで記事を書き、Markdown ファイルとして管理できます。

主にできることは次の3つです。

ローカルでプレビューできる
npx qiita preview で、Qiita と同じ見た目の画面をブラウザで確認できます。
コマンドで投稿・更新できる
npx qiita publish で、手元のファイルを Qiita に投稿できます。
GitHub Actions で自動投稿できる
npx qiita init で投稿用のワークフローが作られます。main にマージすると、GitHub Actions が記事を投稿・更新します。

Qiita CLI を使ってよかった点は、ローカルでプレビューを確認できることと、GitHub で変更履歴を見返せることです。
投稿前にプレビューを確認すると、実際に読む方の立場で記事を読み直せるので便利です。

投稿までの手順

1. Qiita CLI をインストールする

記事を管理するフォルダで、次のコマンドを実行します。

npm install @qiita/qiita-cli --save-dev

公式のパッケージ名は @qiita/qiita-cli です。よく似た名前の別のパッケージがあるので注意してください（公式 README）。

2. `npx qiita init` で初期設定をする

npx qiita init

次の3つのファイルが作られます。

ファイル	役割
`.github/workflows/publish.yml`	main に push されたら記事を投稿するワークフロー
`qiita.config.json`	プレビューの設定（ホスト名・ポート番号など）
`.gitignore`	Git で管理しないファイルの設定

3. Qiita でアクセストークンを発行する

Qiita の「設定」→「アプリケーション」→「個人用アクセストークン」から、新しいトークンを発行します（発行画面）。

スコープ：read_qiita と write_qiita にチェックを入れる
説明：あとで見て、何に使っているトークンかわかる名前にする

トークンの値は、発行した直後の画面でしか表示されません。
また、トークンを知っている人は、あなたのアカウントで記事を投稿できます。
人に見せたり、リポジトリにコミットしたりしないでください。

4. `npx qiita login` でトークンを登録する

npx qiita login

聞かれたら、発行したトークンの値を貼り付けます。
トークンは手元の ~/.config/qiita-cli/credentials.json に保存されます。この設定はローカルのパソコンだけのもの です。

5. 記事ファイルを作る

npx qiita new 記事のファイル名

public/記事のファイル名.md が作られます。先頭の --- で囲まれた部分（front matter）に、記事の設定を書きます。

public/記事のファイル名.md

---
title: 記事のタイトル
tags:
  - タグ1
  - タグ2
private: false
updated_at: ''
id: null
organization_url_name: null
slide: false
ignorePublish: true
---

主な項目は次のとおりです。

項目	意味
`title`	記事のタイトル
`tags`	タグ。書いた順に登録される
`private`	`true` で限定共有記事、`false` で公開記事
`id`	最初は `null`。投稿すると記事の ID が自動で入る
`updated_at`	投稿すると更新日時が自動で入る
`ignorePublish`	`true` にすると投稿されない

npx qiita new で作ったファイルは、ignorePublish: false になっています。このまま main にマージすると、書きかけでも投稿されてしまいます。
書き終わるまでは ignorePublish: true にしておきましょう。

6. プレビューで確認する

npx qiita preview

ブラウザで http://localhost:8888 が開きます。最初に表示されるのは使い方の案内ページなので、画面左側の一覧から記事を選びます（→ ポイント1）。

7. GitHub にリポジトリを作る

GitHub で新しいリポジトリを作ります。

項目	設定した値	説明
Repository name	`qiita-articles`	好きな名前でよい
Choose visibility	`Private`	書きかけの記事を他の人に見られないようにするため
Add README	`Off`	手元のファイルを push するので、空のリポジトリにする
Add .gitignore	`No .gitignore`	`npx qiita init` で作成済み
Add license	`No license`	今回は不要

8. GitHub のリポジトリに `QIITA_TOKEN` を登録する

この手順を飛ばすと、main にマージしても投稿されません。

GitHub のリポジトリを開き、「Settings」→「Secrets and variables」→「Actions」→「Repository secrets」の「New repository secret」から登録します。

項目	入力する値
Name	`QIITA_TOKEN`
Secret	Qiita で発行したアクセストークンの値

私は QIITA_TOKEN の登録を忘れたまま main にマージしてしまい、記事が投稿されませんでした。リポジトリの「Actions」タブで確認すると、次のエラーが出ていました。

Error: ENOENT: no such file or directory, open '/home/runner/.config/qiita-cli/credentials.json'

原因は、npx qiita login で登録したトークンが手元のパソコンに保存されるだけで、GitHub Actions が動くサーバーには引き継がれないことです。
QIITA_TOKEN を登録し、失敗した処理を再実行すると投稿できました。再実行するのは、一番新しい処理だけで十分です。

9. GitHub に push する

手元のファイルをコミットして、GitHub に push します。<ユーザー名> と <リポジトリ名> は自分のものに置き換えてください。

# 今のフォルダを Git で管理できるようにする
git init

# すべてのファイルをコミットの対象にする（.gitignore に書いたものは除かれる）
git add .

# 対象にしたファイルをコミットする
git commit -m "chore: Qiita CLIの初期設定"

# ブランチ名を main にする
git branch -M main

# GitHub のリポジトリを、origin という名前で接続先に登録する
git remote add origin git@github.com:<ユーザー名>/<リポジトリ名>.git

# main を GitHub に push する（-u を付けると、次からは git push だけで済む）
git push -u origin main

git remote add を実行するのは、リポジトリごとに最初の1回だけです。

main に push すると GitHub Actions が動きます。ignorePublish: false の記事があると、その時点で投稿されるので注意してください。

10. `ignorePublish: false` にして main にマージする

記事が書き終わったら ignorePublish: false に変え、Pull Request を作って main にマージします。
GitHub Actions が動き、記事が Qiita に投稿されます。

投稿に成功すると、GitHub Actions が Updated by qiita-cli というコミットを main に追加します。このコミットで、front matter の id と updated_at に値が入ります（→ ポイント3）。

詰まったポイント

ポイント1：Qiita CLI が扱うのは `public/` のファイルだけ

プレビューに記事が表示されなかった

npx qiita preview を開くと、使い方の案内ページが表示されて、記事が見当たりませんでした。原因は2つありました。

記事は、画面左側の一覧から選ぶ仕組みだった
本文を、Qiita CLI の外にある下書きファイルに書いたままだった。npx qiita new で作ったファイルには front matter しか入っていなかった

本文を public/ の記事ファイルに移すと、プレビューで確認できるようになりました。
下書き用と投稿用でファイルを分けると、片方だけ直してしまう事故が起きやすいので、投稿用のファイル1つにまとめました。

Qiita CLI には「下書きとして保存する」機能はありません。
private: true は 限定共有記事（URL を知っていれば誰でも読める）になるだけで、下書きの代わりにはなりません。書きかけの記事は ignorePublish: true にしておきます。

ポイント2：画像はプレビュー画面のリンクからアップロードする

Qiita CLI のコマンドには、画像をアップロードする機能がありません（公式 README にも、画像についての記載はありません）。
画像は、プレビュー画面のリンクからアップロードできます。

npx qiita preview の画面の左上にある「画像をアップロードする」を押す
開いたページで画像をアップロードし、URL をコピーする
記事ファイルに ![画像の説明](コピーした URL) の形で貼り付ける

[] の中の文字は img タグの alt として出力される ので、ファイル名ではなく、画像の内容がわかる説明にするのがおすすめです。

注意したのは次の3点です。

個人情報はアップロードする前に隠す
アップロードした画像は、URL を知っていれば誰でも見られます。
画像は投稿する前に入れる
URL は投稿前でも発行できます。画像が無いまま投稿すると、未完成の記事が一時的に公開されてしまいます。
箇条書きの直後に画像を置くときは、空行を1行入れる
空行が無いと、画像が箇条書きの中に入ってしまいます。

GitHub のリポジトリに画像を置き、その URL を使う方法もあります。ただし、リポジトリが private だと画像が表示されないため、今回は使いませんでした。

ポイント3：投稿した後は、必ず `git pull` してから次の作業をする

投稿に成功すると、GitHub Actions が Updated by qiita-cli というコミットを main に追加し、front matter の id と updated_at に値が入ります。

-updated_at: ''
-id: null
+updated_at: '2026-10-28T09:06:37+09:00'
+id: 25e20c272c4669348313

手元の main は、このコミットを取り込むまで id: null のままです。
Qiita CLI は id で Qiita 上の記事と結びつけているので、id: null のまま修正して push すると、未投稿の記事と判断されて、同じ記事が新しく投稿されるおそれがあります（仕組みからの推測で、実際には試していません）。

記事を直すときは、次の順番で作業します。

git switch main
git pull
git switch -c docs/fix-xxx

まとめ

Qiita CLI を使うと、記事を Markdown ファイルとして GitHub で管理し、main へのマージで Qiita に投稿できる
GitHub Actions で投稿するには、リポジトリの Secrets に QIITA_TOKEN を登録する。npx qiita login の設定はローカルだけのもの
失敗した処理を再実行するのは、一番新しいものだけ
Qiita CLI が扱うのは public/ のファイルだけ
画像はプレビュー画面のリンクからアップロードし、URL を記事ファイルに貼る
投稿した後は git pull して、id が入った状態から次の作業をする

そもそも Qiita 投稿自体をやったことがない状態だったので、本当にできるか不安でしたが、手順どおりにやればスムーズに設定できました。
他にも Git 管理できることがあれば、積極的に触れていきたいです！

参考

increments/qiita-cli（GitHub）（インストール、init・login・new・preview・publish、front matter の項目、GitHub Actions の設定）
Qiita：個人用アクセストークンの発行