CLI で困ったとき

hakocms-cli がうまく動かないときに、表示されたメッセージから原因を探します。どのメッセージも、先頭に error: が付いて標準エラーに出ます。

command not found と表示される

原因：hakocms-cli を置いたフォルダが PATH に入っていません。

直し方：置いたフォルダを PATH に足すか、PATH に入っているフォルダ（/usr/local/bin など）に置き直します（CLI を入れる）。PATH を変えたら、新しい端末を開きます。

macOS で実行が止められる

原因：ブラウザでダウンロードしたファイルを Finder で展開したので、macOS が実行を止める印を付けています。hakocms-cli には Apple の署名がありません。

確かめ方：xattr /usr/local/bin/hakocms-cli を実行します。com.apple.quarantine が表示されれば、印が付いています。

直し方：次のコマンドで印を外します。

xattr -d com.apple.quarantine /usr/local/bin/hakocms-cli

no host to connect to と表示される（終了コード 4）

error: no host to connect to; run `hakocms-cli auth login --host <url>`

原因：つなぐ先が決まっていません。まだログインしていないか、CI で HAKOCMS_HOST を入れていません。

直し方：hakocms-cli auth login --host https://<ホスト名>.hakocms.net でログインします。CI では、環境変数 HAKOCMS_HOST と HAKOCMS_TOKEN を入れます（CLI でログインする）。

invalid or expired access token と表示される（終了コード 4）

error: invalid or expired access token; run `hakocms-cli auth login --host https://<ホスト名>.hakocms.net`

原因：アクセストークンの期限が切れたか、取り消されています。管理画面の［アクセストークン］で取り消したときや、ほかのコンピューターで同じつなぐ先にログインし直したときにも起きます。

確かめ方：hakocms-cli auth status で、トークンの期限を見ます。

直し方：hakocms-cli auth login でログインし直します。CI のときは、管理画面で新しいトークンを作り、CI の秘密の変数を入れ替えます。

ブラウザが開かない、文字が見つからないと表示される

原因：SSH でつないだ先など、ブラウザのないところで動かしています。または、確かめの文字の期限（10 分）が切れています。

直し方：hakocms-cli auth login --host <URL> --no-browser を実行し、表示された URL を手元のブラウザで開きます。管理画面に「この文字のログインは見つかりません」と表示されたら、auth login をもう一度実行します。

unknown host name と表示される（終了コード 2）

error: unknown host name `test`; run `hakocms-cli auth status` to see the hosts

原因：--host に、ログインしていない名前を書いています。

直し方：hakocms-cli auth status で、ログインしているつなぐ先の名前を確かめます。名前の代わりに URL も書けます。

403 になる

error: you do not have permission to do this (HTTP 403)

原因：あなたのスペースのロールでは、その操作ができません。hakocms-cli はあなたと同じ権限で動きます。

［読み取りだけ］で作ったアクセストークンでは、取り出すコマンドのほかは、次のように 403 になります。

error: this access token can only read (HTTP 403)

確かめ方：hakocms-cli spaces list の［ROLE］で、自分のロールを見ます。ロールでできることは メンバーを招待する、ロールを決める にあります。

直し方：ロールが足りないときは、スペースのオーナーか管理者に、ロールを変えてもらいます。［読み取りだけ］のトークンのときは、トークンを［すべて（あなたと同じ）］で作り直します。

404 になる

error: not found (HTTP 404)

原因：スペース、コンテンツタイプ、エントリーのどれかが見つかりません。メンバーでないスペースも、404 になります。

確かめ方：順に一覧にして、名前を確かめます。

hakocms-cli spaces list                    # スペースのスラッグ
hakocms-cli content-types list -s <スラッグ>  # コンテンツタイプ ID（ENDPOINT の列）
hakocms-cli entries list -s <スラッグ> -t <コンテンツタイプ ID>

直し方：--space にはスペースのスラッグ、--type にはコンテンツタイプ ID（画面の［エンドポイント］）を渡します。表示名（「ブログ」「記事」）ではありません。

no space given と表示される（終了コード 2）

error: no space given; pass --space <slug> or run `hakocms-cli spaces use <slug>`

原因：--space を付けず、spaces use でも決めていません。hakocms-cli はスペースを勝手に選びません。

直し方：hakocms-cli spaces use <スラッグ> で決めるか、コマンドに --space <スラッグ> を付けます（CLI でログインする）。

CI で needs –force when it cannot ask と表示される

error: `schema apply` needs --force when it cannot ask (not a terminal, or --no-input)

原因：CI は端末でないので、確かめを聞けません。

直し方：消す・反映するなどの操作に --force を付けます。スペースやコンテンツタイプの削除のような重い操作には、--confirm <名前> を付けます（CLI の出力と終了コード）。

値を渡すと 400 や 422 になる

error: title: is required (HTTP 400)

原因：値の形がフィールドの種類に合っていません。メッセージの先頭に、合わないフィールドの ID が出ます。

直し方：フィールドの種類と値の形 で、書き込める値の形を確かめます。よくある間違いは次のとおりです。

間違い	直し方
画像のフィールドに URL の文字列を入れた（image: must be an object with url）	--set 'image={"url":"<URL>"}'
数の文字列を入れたい（--set code=3 が数になる）	--set code='"3"'
--data の JSON の形が違う（Failed to deserialize the JSON body）	値全体を { "フィールド ID": 値 } の形にする。ファイルは --data @post.json

Linux のサーバーで、トークンが hosts.toml に置かれる

(no system keyring is available; /home/you/.config/hakocms-cli/hosts.toml is readable only by you)

原因：デスクトップのない Linux には、OS の資格情報の保管庫（Secret Service）がありません。

直し方：そのままで使えます。hosts.toml は、あなただけが読める権限で置かれます。ほかの人も入るサーバーでは、ログインせずに、使うときだけトークンを環境変数 HAKOCMS_TOKEN で渡す方が安全です。

それでも分からないとき

--help で、コマンドの使い方を確かめます（hakocms-cli entries update --help）。hakocms-cli version の出力と、表示されたメッセージを添えて、問い合わせ から連絡してください。アクセストークン（hako_pat_ で始まる文字）は、問い合わせに書かないでください。