CLIコマンドと実行場所を調べる
コマンド入力画面から使う命令を、調べる・変更する・組み立てるに分けて紹介します。実行フォルダーと接続先の確認も説明します。
目次
命令の前に、場所と対象を確認する
EmDashのCLIは、コマンド入力画面から記事や設定を確認・変更する道具です。emdashパッケージに含まれており、EmDashのプロジェクト内でnpx emdashと入力して使います。
このガイドでは、VS Codeのターミナルで入力します。Windowsではコマンドプロンプトを選びます。入力画面の開き方
実行前に、コマンド入力画面で、package.jsonがあるプロジェクトの一番外側のフォルダーへ移動します。同じ命令でも、実行するフォルダーや接続先のURLが違えば、操作するサイトが変わります。
このガイドはEmDash 1.4.0の主な命令を扱います。--helpで、その環境にインストールされた版の使い方も確認してください。
手元のSQLiteの状態を確認するならdoctor の診断項目と終了コード、サイトに登録した画像のIDや寸法を確認するならmedia list・media get の使い方を開いてください。
起動とCLIは別の命令
npm run devこれはプロジェクトの開発サーバーを起動します。通常、起動したコマンド入力画面はそのまま残し、CLI用にもう一つコマンド入力画面を開きます。
記事や入力欄の定義を読む命令は、起動中のサイトへ接続します。一方、初期データを入れるseedや、DBの構造を更新する移行の命令には、直接DBを扱うものもあります。接続先を--urlで指定するかどうかは、命令ごとに確認してください。
最初に使う読み取り命令
以下は、手元のサイトがhttp://localhost:4321で起動している場合の例です。別のポート番号で起動したら、4321をその番号へ置き換えます。
npx emdash whoami --url http://localhost:4321
npx emdash schema list --url http://localhost:4321
npx emdash schema get posts --url http://localhost:4321
npx emdash content list posts --status published --limit 10 --url http://localhost:4321whoamiは接続した利用者、schemaは記事の入れ物と入力欄、content listは記事一覧を確認します。開発用localhostには認証省略の仕組みがありますが、公開先で同じ条件が使えるわけではありません。
公開先などで認証する場合は、先に次を実行します。https://example.comは自分の対象URLへ置き換えます。
npx emdash login --url https://example.comブラウザーでコードの承認を完了すると、そのURLへ接続するための認証情報が手元のパソコンに保存されます。認証用の値をトークンと呼びます。複数の方法で指定した場合は、--token、環境変数のEMDASH_TOKEN、保存済みの認証情報の順で優先されます。
下書きを作るときは—draftを明示する
CLIのcontent createは、--draftを付けないと、新しい記事を自動で公開します。下書きとして作るときは、必ず--draftを付けてください。
たとえば、記事を入れるコレクションの入力ルールに合わせてpost.jsonを用意し、次の命令を実行します。
npx emdash content create posts --file post.json --slug practice-note --draft --url http://localhost:4321post.jsonは入力データをまとめたファイルです。タイトルだけで十分か、本文も必須かは、先にschema get postsで確認します。本文に使うPortable Textは、段落や見出しを分けて保存する形式なので、HTMLの文字列をそのまま入れないでください。
作成後に返されたIDを控え、content getと管理画面の両方で、本文と下書き状態を確認します。
更新前には現在の版を読む
npx emdash content get posts ARTICLE_ID --url http://localhost:4321ARTICLE_IDは実際の記事IDに置き換えます。取得結果の_revは、記事の版を見分ける値です。更新時にその値を--revへ渡すと、取得後に別の変更が入っていないかを確認できます。
npx emdash content update posts ARTICLE_ID --rev REVISION_TOKEN --file post.json --draft --url http://localhost:4321更新も--draftを付け、すぐに公開しない形で確認します。REVISION_TOKENを固定のサンプル値で使わず、直前の取得結果を使います。競合した場合は、現在の内容を読み直し、どの変更を残すか確認します。
目的別の命令
| 命令 | 目的 | 主な対象 |
|---|---|---|
types | 型情報を生成する | 起動中のサイト |
schema | 入れ物と欄を調べる・変更する | 起動中のサイト |
media | 画像などを扱う | 起動中のサイト |
taxonomy・menu | 分類・メニューを扱う | 起動中のサイト |
site | サイトパッケージの転送 | 起動中のサイト |
seed | 初期データを検査・適用する | ローカルSQLite |
export-seed | 新規作成用の定義を書き出す | ローカルSQLite |
migrate | EmDash内部の移行を扱う | build manifestが示すDB |
doctor | ローカル構成を診断する | プロジェクトとローカルDB |
secrets generate | 暗号化キーを生成する | ローカル出力 |
schemaやcontentは、同じ名前の下に読み取りと変更の両方があります。末尾のdelete、remove-field、publishなどまで読んでから実行します。
変更を伴わない確認を使う
seedファイルの書式だけを確かめる例です。
npx emdash seed seed/seed.json --validate--validateを省くとデータを実際に適用するため、書式の確認だけなら省かないでください。DBの内部移行では、--statusで状態を確認し、--checkで不一致がないかを調べます。これらを付けずにmigrateを実行すると、移行を適用します。
D1の移行では、--wrangler-config wrangler.jsoncなどで対象の設定ファイルを指定する必要があります。doctorが調べるのは手元の構成とSQLiteのDBです。そのチェックが失敗しても、公開先のD1に障害があるとは限りません。
結果を読み、操作を終える
エラーの後に次の変更命令を続けず、対象URLとエラーコードを確認します。--jsonに対応する命令では、機械処理用の結果を出せますが、すべての命令に同じフラグがあるわけではありません。
開発サーバーを止めるのは、そのコマンド入力画面でControl + Cです。CLIの保存済み認証を外す場合はlogout --url 対象URLを使います。元のサイトの停止や記事の削除とは別です。
全オプションと終了コードは公式CLIリファレンス(別タブで開く)にあります。プラグインの配布に使うemdash-pluginと、サイトを管理するemdashも別のCLIです。