CLI の出力と終了コード

hakocms-cli の出力の形と、終了コードの一覧です。スクリプトや CI から使うときの決まりも、このページにまとめます。

出力の形

指定	一覧	1 件	使うとき
なし（端末）	見出しのある表	`項目: 値` の行	人が読む
なし（パイプ、ファイル）	見出しのない、タブ区切りの行	`項目: 値` の行	`cut`、`awk` で読む
`--json`	JSON の配列（整えた形）	JSON のオブジェクト	ほかの道具に渡す
`--jq <式>`	式の結果	式の結果	必要な値だけを取り出す

端末に出したときの一覧の例です。

ID            STATUS     UPDATED AT                CREATED AT
pgxjuopeye1p  published  2026-10-23T04:18:29.693Z  2026-10-23T04:18:29.693Z
iazte4ghzm55  draft      2026-10-23T04:18:29.640Z  2026-10-23T04:18:29.640Z

パイプに渡したときは、見出しがなく、列の間はタブです。

pgxjuopeye1p  published  2026-10-23T04:18:29.693Z  2026-10-23T04:18:29.693Z
iazte4ghzm55  draft  2026-10-23T04:18:29.640Z  2026-10-23T04:18:29.640Z

環境変数 NO_COLOR があれば、色を付けません
日時は UTC の RFC 3339 で出ます（2026-10-23T04:18:29.693Z）

JSON（`--json`）

Admin API の応答を、そのまま出します。項目の意味は Admin API のリファレンスと同じです。

一覧はページの包み（totalCount など）を外した、中身の配列で出ます。--all で全部のページをたどっても、同じ形です
hakocms-cli が知らない新しい項目もそのまま出ます

jq の式（`--jq`）

JSON を jq の式で絞ります。--json を付けなくても、JSON に式を当てます。jq を別に入れる必要はありません。

式の結果	出かた
文字列	引用符を付けずに、そのまま 1 行で
数、真偽値、`null`	JSON で 1 行で
オブジェクト、配列	整えた JSON で、いくつもの行に
いくつもの結果（`.[]`）	結果ごとに、上の形で順に

hakocms-cli entries list -t posts --jq '.[].id'                    # ID を 1 行に 1 つ
hakocms-cli entries list -t posts --all --jq 'length'              # 件数
hakocms-cli entries list -t posts --jq '.[] | {id, status} | tojson'  # 1 行に 1 件の JSON

標準出力と標準エラー

出るもの	出る先
結果（表、JSON、jq の式の結果）	標準出力
進み具合（`uploaded 1/2: …`、`apply …: queued`）、警告、誤り	標準エラー

--json か --jq のときの誤りは標準エラーに JSON で出ます。

{"error":{"status":404,"message":"not found"}}

status は Admin API の HTTP の状態です。理由ごとの意味はエラーの一覧にあります。

一覧の件数

フラグ	中身
（なし）	30 件
`--limit <n>`	n 件
`--all`	全部のページをたどって、すべて

書き出しなど、いくつかの一覧は新しい順に 20 件までです。

確かめの聞き方

消すなど取り消せない操作の前には、続けてよいかを聞きます。

重さ	例	端末のとき	端末でないとき（パイプ、CI）
軽い	エントリーの保存・公開	聞かない	聞かない
中くらい	エントリー・メディア・Webhook の削除、API キーの失効、スキーマの反映	`[y/N]` で聞く	`--force` が要る
重い	スペース・コンテンツタイプ・ユーザーの削除、ユーザーの匿名化	対象の名前（スラッグ、コンテンツタイプ ID、ユーザーの ID）を打たせる	`--confirm <名前>` が要る（`--force` では足りない）

確かめの文には、つなぐ先の名前とスペースが入ります。

--no-input を付けると、何も聞きません。聞く必要があれば、誤りにして終わります
端末でないところで、--force や --confirm がないと、次のように表示して何もせずに終わります
```
error: `entries delete pgxjuopeye1p` needs --force when it cannot ask (not a terminal, or --no-input)
```

ジョブを待つ（`--wait`）

書き出し、取り込み、スキーマの反映は、Hako CMS の中のジョブとして動きます。--wait を付けると、ジョブが終わるまで 2 秒ごとに問い合わせ、結果を出します。

export k4uexuzi2q9f: queued
export k4uexuzi2q9f: succeeded

ジョブが失敗したときは、終了コード 1 で終わります。

終了コード

コード	意味	例
0	成功
1	誤り	API の誤り（404、400 など）、通信の失敗、確かめで「いいえ」と答えた、ジョブの失敗
2	使い方の誤り	フラグの書き間違い、要る引数がない、読めない JSON、知らないつなぐ先の名前
4	ログインが要る	つなぐ先が決まっていない、トークンがない・期限が切れた・取り消された

スクリプトでは、終了コードで処理を分けられます。

hakocms-cli entries get <エントリー ID> -t posts --json > entry.json
case $? in
  0) echo "取り出しました" ;;
  4) echo "ログインし直してください" >&2; exit 1 ;;
  *) echo "取り出せませんでした" >&2; exit 1 ;;
esac

版

hakocms-cli version

hakocms-cli 0.1.8 (Admin API 1)

hakocms-cli の版と、使う Admin API の大きい版が出ます。Hako CMS の Admin API の大きい版が違うと、コマンドのたびに警告が表示されます。そのときは、hakocms-cli を新しくします（CLI を入れる）。