本文へスキップ
mtbmtb

コマンドの命名規則 ​

コマンドは公式の OpenAPI 定義（v7）から機械的に生成しています。 規則を覚えれば、リファレンスのパスからコマンド名を導けます（コマンド名からパスを導くこともできます）。

4つの規則 ​

  1. パスのリテラルなセグメントがそのままコマンドのグループになります。 キャメルケースとスネークケースはケバブケースに変換します （contentTypes → content-types、formatted_texts → formatted-texts）
  2. パスパラメータ（{site_id} など）はコマンド名に含まれません。 フラグ（--site-id）か位置引数で渡します
  3. 末尾が動詞なら、その動詞がコマンド名になります （upload export import preview permutate grant revoke clonepublish refresh apply unlock enable disable synchronizebackup thumbnail search など）
  4. そうでなければ HTTP メソッドから動詞を決めます
パスの末尾GETPOSTPUTDELETE
リテラル（コレクション）listcreateupdatedelete
パラメータ（個別）getcreateupdatedelete
GET    /v7/sites/{site_id}/entries                        mtb sites entries list
POST   /v7/sites/{site_id}/entries                        mtb sites entries create
GET    /v7/sites/{site_id}/entries/{entry_id}             mtb sites entries get
PUT    /v7/sites/{site_id}/entries/{entry_id}             mtb sites entries update
DELETE /v7/sites/{site_id}/entries/{entry_id}             mtb sites entries delete
GET    /v7/sites/{site_id}/entries/export                 mtb sites entries export
POST   /v7/assets/upload                                  mtb assets upload
GET    /v7/sites/{site_id}/categories/{id}/children       mtb sites categories children list
POST   /v7/sites/{site_id}/themes/{theme_id}/apply        mtb sites themes apply
POST   /v7/groups/{group_id}/permissions/grant            mtb groups permissions grant

パスが分かっているなら、名前を探すより --help が速い

bash
mtb sites entries --help
mtb sites entries list --help

パラメータの渡し方 ​

パスパラメータはフラグでも位置引数でも渡せます。位置引数はパスの並び順です。

bash
mtb sites entries get --site-id 1 --entry-id 42
mtb sites entries get 1 42                    # 同じ

フラグ名は API のパラメータ名をケバブケースにしたものです（sortBy → --sort-by）。 --help に (API: sortBy) と併記されるので、公式リファレンスと照合できます。

種類書き方
クエリ・本文の単純な値--limit 50 --status Publish
リソース本体（JSON）--entry '{"title":"..."}'
JSON をファイルから--entry @entry.json
JSON を標準入力から--entry -
ファイルの添付--file ./photo.jpg
定義に無いクエリ--query key=value
定義に無い本文--form key=value

7つの例外 ​

規則どおりに命名すると意味を取り違えるもの、または名前が衝突するものだけを個別に定めています。

エンドポイントコマンド理由
GET /mtb openapiサーバ自身の OpenAPI 定義を返す
GET /versionmtb server-versionCLI 自身の --version と紛らわしい
POST /sites/{site_id}mtb sites create-blogブログ作成。POST /sites（ウェブサイト作成）と衝突する
DELETE /sites/{site_id}/logsmtb sites logs reset全ログ削除。1件削除と同名だと、誤って全件を削除するおそれがある
GET /publish/entriesmtb publish entriesGET だが再構築の実行。一覧ではない
GET /publish/contentDatamtb publish content-data同上
GET /sites/{site_id}/stats/providermtb sites stats provider1つを返す。コレクションではない

IDの有無で挙動が変わるもの ​

MT には「IDを取る版と取らない版」が対になっているエンドポイントがあります。 1つのコマンドにまとめてあり、IDを渡せばIDを取る版、省けば取らない版を呼び出します。

コマンドIDありIDなし
mtb plugins enable [plugin-id]そのプラグインを有効化全プラグインを有効化
mtb plugins disable [plugin-id]そのプラグインを無効化全プラグインを無効化
mtb sites entries preview [site-id] [entry-id]既存記事のプレビュー未保存の記事のプレビュー
mtb sites pages preview [site-id] [page-id]同上（ページ）同上
mtb sites templates preview [site-id] [template-id]同上（テンプレート）同上
mtb sites content-types data preview [...]同上同上

IDを省くと対象が広がるものがあります

plugins enable は全プラグインが対象になります。省略する意図がないなら 必ずIDを渡してください。

認証エンドポイントは生成していません ​

/authentication /token /authorization は mtb auth で扱います。 生のリクエストで呼び出すと、保存済みの認証情報と整合しなくなるので、使わないでください。

単数形の別名 ​

複数形のグループには単数形の別名があります。入力の手間を減らすためだけのもので、 動作は同じです。

bash
mtb sites entries list --site-id 1
mtb site entry list --site-id 1        # 同じ

定義に無いエンドポイント ​

埋め込んでいる定義は取り込み時点の v7 です。プラグインが追加したエンドポイントや MT 側で新しく追加されたエンドポイントは、生のリクエストで呼び出せます。

bash
mtb endpoints list --all --fields component,verb,route   # そのMTが実際に持つもの
mtb api GET /sites/1/things --all --fields id,label
mtb api POST /sites/1/things --set thing.label=ラベル --set thing.note=@note.txt

--all --fields --set --set-json は生成コマンドと同じように使えます。--set はここでは項目名を検査しません（エンドポイントが受け取る本体の形を事前に知らないため）。

Last updated: