スクリプト作成と自動化

TeamCity CLI は、スクリプト作成、自動化、CI/CD 統合向けに設計された複数の出力フォーマットと機能を提供します。

JSON 出力

多くのコマンドは、機械可読な出力のための --json フラグをサポートしています。リストコマンドは、オプションのフィールド選択も受け付けます。

基本的な使用箇所

teamcity run list --json
teamcity job list --json
teamcity project list --json

   

使用可能なフィールドの確認

コマンドで使用可能なすべてのフィールドを表示するには、 --json= (空の値) を渡します。

teamcity run list --json=

特定のフィールドの選択

フィールドをコンマで区切ってリストを指定します。

teamcity run list --json=id,status,webUrl

フィールド選択（--json=... ）はリストコマンドでのみ使用できます。ビューコマンドとインスペクションコマンドでは、フィールド選択なしで --json を使用できます。

ネストされたフィールド

ネストされたフィールドにアクセスするにはドット表記を使用します。

teamcity run list --json=id,status,buildType.name,triggered.user.username

表示コマンドおよびインスペクションコマンドの JSON

teamcity run view 12345 --json
teamcity run log 12345 --json
teamcity run log 12345 --json --failed
teamcity run changes 12345 --json
teamcity run tests 12345 --json
teamcity run artifacts 12345 --json
teamcity agent view Agent-Linux-01 --json
teamcity project settings status MyProject --json
teamcity auth status --json

   

コマンド別の使用可能なフィールド

コマンド	例のフィールド
`teamcity run list`	`ID`、 `番号`、 `状況`、 `state`、 `branchName`、 `buildTypeId`、 `buildType.name`、 `buildType.projectName`、 `triggered.type`、 `triggered.user.name`、 `agent.name`、 `startDate`、 `finishDate`、 `webUrl`
`teamcity job list`	`ID`、 `お名前`、 `projectName`、 `プロジェクト ID`、 `paused`、 `href`、 `webUrl`
`teamcity project list`	`ID`、 `お名前`、 `説明`、 `parentProjectId`、 `href`、 `webUrl`
`teamcity queue list`	`ID`、 `buildTypeId`、 `state`、 `branchName`、 `queuedDate`、 `buildType.name`、 `triggered.user.name`、 `webUrl`
`teamcity agent list`	`ID`、 `お名前`、 `connected`、 `有効`、 `authorized`、 `pool.name`、 `webUrl`
`teamcity pool list`	`ID`、 `お名前`、 `maxAgents`

プレーンテキスト出力

標準的な Unix ツールで解析しやすいタブ区切り出力には、 --plain を使用してください。このフラグは、すべてのリストコマンド、および agent jobs と param list で使用できます。

teamcity run list --plain
teamcity agent list --plain
teamcity agent jobs 1 --plain
teamcity project param list MyProject --plain

  

よりクリーンなパイピングのためにヘッダー行を省略します。

teamcity run list --plain --no-header
teamcity agent list --plain --no-header | awk '{print $1}'

スクリプト例

失敗したビルドの ID を取得

teamcity run list --status failure --json=id | jq -r '.[].id'

ビルドデータを CSV にエクスポート

teamcity run list --json=id,status,branchName | jq -r '.[] | [.id,.status,.branchName] | @csv'

   

キュー内のビルドのウェブ URL を取得

teamcity queue list --json=webUrl | jq -r '.[].webUrl'

ステータス別にビルドをカウント

teamcity run list --since 24h --json=status | jq 'group_by(.status) | map({status: .[0].status, count: length})'

   

ビルドの完了を待機

teamcity run start MyProject_Build --watch --json

または、別々に開始して視聴することもできます。

BUILD_ID=$(teamcity run start MyProject_Build --json | jq -r '.id')
teamcity run watch "$BUILD_ID" --json

ジョブのキュー内のビルドをすべてキャンセル

teamcity queue list --job MyProject_Build --json=id | jq -r '.[].id' | xargs -I {} teamcity run cancel {} --yes

   

CI/CD 統合

環境変数認証

CI/CD パイプラインでは、認証に環境変数を使用します。

export TEAMCITY_URL="https://teamcity.example.com"
export TEAMCITY_TOKEN="your-access-token"

PowerShell:

$env:TEAMCITY_URL = "https://teamcity.example.com"
$env:TEAMCITY_TOKEN = "your-access-token"

Cmd:

set TEAMCITY_URL=https://teamcity.example.com
set TEAMCITY_TOKEN=your-access-token

詳細は認証を参照してください。

非対話モード

自動化された環境で対話型プロンプトを無効にするには、 --no-input を使用します。プロンプトが抑制されている場合、CLI は適切なデフォルトを使用します。

teamcity run cancel 12345 --no-input

あるいは、それをサポートするコマンドで --yes を使用します。

teamcity queue remove 12345 --yes

読み取り専用モード

TEAMCITY_RO=1 を設定すると、書き込み操作が一切行われなくなります。このモードでは、データを変更するコマンド（ビルドのトリガー、キャンセル、ピン留め、パラメーターの変更など）は、リクエストが送信される前に拒否されます。

export TEAMCITY_RO=1
teamcity run list              # works — read-only
teamcity run start MyBuild     # blocked — would trigger a build

   

これは、ダッシュボード、レポートスクリプト、偶発的な変更を防ぐ必要がある共有環境の監視に役立ちます。このフラグは、GET 以外のメソッドによる teamcity api 経由の書き込み操作もブロックします。

許容される値については構成を参照してください。

クワイエットモード

不要な出力を抑制するには、 --quiet を使用します。

teamcity run start MyProject_Build --quiet

終了コード

ほとんどのコマンドは、成功時には終了コード 0 を、失敗時には 1 を返します。 teamcity run watch フロー（teamcity run start --watch を含む）は以下を返します。

実行がキャンセルされたときの 2
124 タイムアウト

teamcity run start MyProject_Build --watch --quiet --timeout 30m
case $? in
  0) echo "Build succeeded" ;;
  1) echo "Build failed" ;;
  2) echo "Build cancelled" ;;
  124) echo "Timed out" ;;
  *) echo "Unknown error" ;;
esac

   

構造化エラー

--json がアクティブな状態でコマンドが失敗した場合、エラーはプレーンテキストではなく、構造化された JSON として標準エラー出力に書き込まれます。

{
  "error": {
    "code": "auth_expired",
    "message": "Authentication failed: invalid or expired token",
    "suggestion": "teamcity auth login"
  }
}

  

エラーコード:

コード	意味
`auth_expired`	トークンが無効か、期限切れです
`permission_denied`	権限が不足しています
`not_found`	要求されたリソースは存在しません
`network_error`	サーバーに到達できません
`read_only`	書き込み操作は `TEAMCITY_RO` によってブロックされています
`validation_error`	無効な入力 (フラグ、引数)
`internal_error`	予期しないエラー

suggestion フィールドは、修正可能な箇所がない場合に省略されます。 code フィールドは常に存在し、プログラムによるマッチングにおいて安全です。

JSON 互換性ポリシー

--json の出力は機械可読な契約書です。以下の規則が適用されます。

以前のリリースでは、フィールドの削除や名前変更はありませんには非推奨期間が設けられていませんでした。
追加フィールドは常に許可されます — 新しいキーはどのリリースにも含まれる可能性があります。
エラーコードは安定しています — 既存の法令の意味は変更されません。
エンベロープ構造は固定されています — 成功時の出力はリソースデータであり、エラー時の出力は標準エラー出力に {"error": {...}} エンベロープを使用します。

消費者は、不明なフィールドを無視し、フィールドの順序に頼るべきではない。

Raw API アクセス

専用コマンドでカバーされていない操作の場合は、 teamcity api を使用して直接 REST API リクエストを実行します。

teamcity api '/app/rest/server'
teamcity api '/app/rest/builds' --paginate --slurp

詳細は REST API アクセスを参照してください。

2026 年 9 月 11 日