EmDash にはコマンドラインツール（CLI）が付いています。CLI にログインすると、記事の一覧取得や検索、スキーマの操作などをターミナルから行えます。管理画面にない設定を、API で変えることもできます。
EmDash の管理画面にはパスワードがなく、パスキーでログインします。CLI のほうは、「デバイス認可」という方式でログインします。
画像は、ローカル環境でダミーのユーザー（Dev Admin）を使って撮りました。本番のドメインは your-site.example.com に置き換えています。デバイス認可とは
テレビやゲーム機で動画サービスにログインするとき、「スマホで○○を開いてコードを入力してください」と表示されることがあります。デバイス認可は、それと同じ仕組みです。正式には OAuth 2.0 Device Authorization Grant といいます。
- CLI がサイトにログインを要求し、短いコードを受け取る
- あなたがブラウザで管理画面を開き、そのコードを入力して承認する
- CLI がトークンを受け取って保存する
ターミナルでパスワードを打つことはありません。本人確認は、ブラウザでのいつものパスキーログインで済みます。
準備
- EmDash のプロジェクトフォルダーがあること（CLI は
emdashパッケージに含まれています） - ログインしたいサイトに、ブラウザからパスキーでログインできること
手順
1. ターミナルで emdash login を実行する
プロジェクトフォルダーで次のコマンドを実行します。本番サイトなら、--url に本番の URL を指定します（省略すると http://localhost:4321 になります）。
pnpm emdash login --url https://your-site.example.com開く URL と、XXXX-XXXX 形式のコードが表示されます。CLI はそのまま承認を待ちます。
2. ブラウザで承認ページを開く
表示された URL（/_emdash/admin/device）をブラウザで開きます。管理画面にログインしていない場合は、先にパスキーでログインしてください。
3. コードを入力して［承認］を押す
ターミナルに表示されたコードを入力すると、CLI が求めている権限が表示されます。管理者のアカウントで承認すると、権限は「管理者フルアクセス」になります。
自分で実行した CLI のコードだけを承認してください。画面の下にも「操作中の CLI に表示されたコードと一致する場合だけ承認してください」と書かれています。ほかの人から「このコードを入力して」と頼まれても、絶対に承認してはいけません。承認すると、その人の CLI が、あなたの権限でサイトを操作できるようになります。
［承認］を押せば完了です。このページは閉じてかまいません。
4. ターミナルでログインを確認する
ターミナルに戻ると、Logged in as ... と表示されています。誰としてログインしているかは、emdash whoami で確かめられます。
pnpm emdash whoami --url https://your-site.example.com
トークンの保存場所
項目 | 内容 |
|---|---|
保存場所 |
|
中身 | サイトごとのアクセストークン、リフレッシュトークン、有効期限、ユーザー情報 |
有効期限 | アクセストークンは約 1 時間。期限が切れても、リフレッシュトークンで更新される |
本番サイト | URL ごとに保存される（例: |
ローカル |
|
ログアウトするときは、次のコマンドを実行します。
pnpm emdash logout --url https://your-site.example.comこのファイルには、管理者として操作できるトークンが入っています。Git にコミットしたり、チャットに貼ったりしないでください。
使いどころの例: 日本語の全文検索を設定する
CLI のトークンは、管理画面にない設定を API で変えたいときに役立ちます。
私のサイトでは、日本語の全文検索がうまく動きませんでした。EmDash の検索は、デフォルトでは SQLite FTS5 の porter unicode61 トークナイザーを使います。これは英語向けで、日本語の文を単語に分けられません。
テスト記事 3 本で比べた結果は次のとおりです。
検索語 | デフォルト（porter unicode61） | trigram |
|---|---|---|
パスキー / 管理画面 | ○ | ○ |
デプロイ / 自動で（文の途中にある語） | × | ○ |
画像 / D1（2 文字の語） | 文の区切りの直後にあるときだけ○ | × |
3 文字以上の語なら、文中のどこにあっても見つかる trigram に切り替えることにしました。ただし、この設定は管理画面からは変えられず、POST /_emdash/api/search/enable という API で行います。
そこで、CLI が保存したアクセストークンを使って API を呼び、検索を有効にしているすべてのコレクションに設定しました。
# CLI が保存したアクセストークンを取り出す（Node.js を使用）
TOKEN=$(node -p "require(process.env.HOME + '/.config/emdash/auth.json')['https://your-site.example.com'].accessToken")
# コレクションごとに trigram を設定する
for c in guides releases glossary posts pages; do
curl -s -X POST https://your-site.example.com/_emdash/api/search/enable \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d "{\"collection\":\"$c\",\"enabled\":true,\"tokenize\":\"trigram\"}"; echo
done
"success":true が返れば設定できています。indexed は索引に登録した記事の数で、記事がまだなければ 0 になります。
コレクション名（guides など）は、自分のサイトのものに置き換えてください。管理画面の「コンテンツタイプ」で確認できます。なお、trigram でも 2 文字の語（「画像」など）は見つかりません。2 文字の語を検索する方法は、別の記事で紹介する予定です。
自動化（CI）で使う場合
emdash login はブラウザでの承認が必要なので、人が手元で使うための方式です。GitHub Actions などの自動処理では、管理画面で発行する個人アクセストークン（ec_pat_ で始まる）を使います。
トークンのスコープは、必要な分だけに絞ります。たとえば記事の下書きを作るだけなら、content:write と media:write で足ります。自動処理には専用のユーザーを作り、ロールも必要最小限にしておきます。トークンの権限は、ユーザーのロールを超えません。トークンは CI の Secret に保存し、リポジトリには書きません。