終了コード

すべてのコマンドが、失敗の種類を示す終了コードを返します。スクリプトや エージェントは、出力を解析せずに分岐できます。

コード	意味	再試行の可否
0	成功
1	分類できないエラー	不可
2	コマンドラインの書き方が誤っている	不可
4	見つからない（workspace / サービス / プロジェクト）	不可
5	すでに存在する	不可
6	kobune.toml が見つからない	不可
7	kobune.toml が不正	不可
8	git リポジトリの外で実行された	不可
9	コンテナランタイムに接続できない	可
10	ランタイムの操作が失敗した	可
11	未対応の機能	不可
12	指定した名前が複数の workspace に当てはまる	不可
70	Kobune 自体の異常	不可
130	Ctrl-C による中断	不可

「再試行の可否」は、何も変更せずに再実行しても成功しうるかどうかを示します。 該当するのは 2 つです。9 は接続先がそもそも無い状態で、Docker または Apple Container を起動してから再実行してください。10 は操作そのものの失敗で、 ネットワークが復旧していれば 2 回目の pull は通ります。ただしビルドの通らない Dockerfile は何度試しても同じように失敗するため、繰り返すなら上限を決めます。

12 を返すコマンドは 1 つだけです。 kobune cd は名前を大まかに照合するため、2 つの workspace に同じ近さで当てはまる名前は、どちらかを選ばずに両方を返します。 どの 2 つかはメッセージに出ます。

残りの 3 つは、ほかのコードとは別の範囲にあります。2 は使い方の誤りを表す コードで、Kobune が何かを試した結果ではなく引数の解析が返します。フラグの 綴り間違いや、コマンドグループだけを指定した場合がこれです。70 は sysexits.h の EX_SOFTWARE で、マシンや設定ではなく Kobune 自体に問題が あったことを示します。130 は Ctrl-C です。128 にシグナル番号を足した値で、 中断されたプログラムにシェルが期待する値です。中断したコマンドが何を残すかは 中断する にあります。

exec は例外です

kobune exec は上表のコードではなく、実行したコマンドの終了コードを 返します。

$ kobune exec web -- npm test; echo $?
1

テストの成否を終了コードだけで判定できるようにするための仕様です。実行した コマンドが上表と同じ値を返した場合は区別できないため、確実に判定する必要が あるときは --json の出力を参照してください。

JSON 出力の場合

$ kobune url nope --json; echo $?
{
  "error": {
    "code": "not_found",
    "message": "no service named `nope`. Available: web, api",
    "hint": "…"
  }
}
4

error.code が機械可読な識別子で、終了コードはその数値表現です。hint が 含まれる場合は、次に取るべき操作が記述されています。

--json 指定時はエラーも stdout に出力されるため、呼び出し側は 1 つの ストリームと 1 つの終了コードのみを確認すれば済みます。