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:4321

whoamiは接続した利用者、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:4321

post.jsonは入力データをまとめたファイルです。タイトルだけで十分か、本文も必須かは、先にschema get postsで確認します。本文に使うPortable Textは、段落や見出しを分けて保存する形式なので、HTMLの文字列をそのまま入れないでください。

作成後に返されたIDを控え、content getと管理画面の両方で、本文と下書き状態を確認します。

更新前には現在の版を読む

npx emdash content get posts ARTICLE_ID --url http://localhost:4321

ARTICLE_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
migrateEmDash内部の移行を扱う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です。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。