camunda-c8ctl

Camunda c8ctl CLI

Camunda 8.8 以降に対応する、依存関係を最小限に抑えた CLI c8ctl をインストールして使用し、クラスターへの接続、リソースのデプロイ、プロセス自動化の管理を行います。c8ctl は、その他の camunda-* スキル（camunda-bpmn、camunda-connectors、camunda-feel、camunda-process-mgmt、camunda-ai-agents）の基盤となります。

前提条件

• Node.js ≥ 22.18.0（ネイティブの TypeScript サポートに必要です）— ローカルへのインストールについては camunda-development を参照してください

相互参照

• camunda-bpmn：c8ctl bpmn lint を使用します
• camunda-connectors：c8ctl element-template search/info/get-properties/apply を使用します
• camunda-feel：c8ctl feel evaluate を使用します
• camunda-process-mgmt：c8ctl deploy、c8ctl run、c8ctl watch、c8ctl list pi、c8ctl search inc、c8ctl complete ut、c8ctl resolve inc などを使用します
• camunda-ai-agents：AI Agent コネクターテンプレートの適用に c8ctl element-template search/apply を使用します

手順

簡単な準備状況の確認（導入時）

c8ctl を初めて使うユーザーに対し、詳しいセットアップの前にマシンの準備ができているか確認するには、この簡単なチェックを使用してください。

# Required runtime
node --version 2>/dev/null || echo "NOT FOUND"

# Required CLI
c8ctl --version 2>/dev/null || echo "NOT FOUND"

# Required default plugins for camunda-* skills
c8ctl bpmn --help >/dev/null 2>&1 && echo "bpmn: OK" || echo "bpmn: MISSING"
c8ctl element-template --help >/dev/null 2>&1 && echo "element-template: OK" || echo "element-template: MISSING"
c8ctl feel --help >/dev/null 2>&1 && echo "feel: OK" || echo "feel: MISSING"

# Optional: check current active profile
c8ctl which profile 2>/dev/null || echo "no active profile"

# Optional: check whether a local c8run cluster is already running
c8ctl cluster status 2>/dev/null || echo "local cluster: not running"

• Node.js と c8ctl が必要です。Node は ≥ 22.18.0 でなければなりません。いずれかがインストールされていない（または Node のバージョンが古い）場合は、先にインストールまたはアップグレードしてください。
• デフォルトプラグインが見つからない場合、インストール済みの c8ctl は 3.0.0 より古いバージョンです。アップグレードの前にユーザーへ確認してください — 確認なしにインストールを実行せず、その後 npm install -g @camunda8/cli を実行してください。
• プロファイルまたはローカルクラスターが見つからなくてもエラーではありません。プロファイルまたはクラスターのセットアップがまだ完了していないことを示すだけです。

インストール

npm から c8ctl をグローバルにインストールします。その他の camunda-* スキルは、c8ctl ≥ 3.0.0 が必要な bpmn、element-template、feel プラグインに依存します。

npm install -g @camunda8/cli

インストール後は、c8ctl と短縮形のエイリアス c8 の両方を使用できます。その他の camunda-* スキルでは、明確さを優先して c8ctl の形式を使用します。

確認します。

c8ctl --version
c8ctl help

デフォルトプラグインを確認する

その他の camunda-* スキルは、c8ctl ≥ 3.0.0 に同梱されている 3 つのプラグイン、bpmn、element-template、feel に依存します。それぞれが使用可能か確認してください。

c8ctl bpmn --help              # camunda-bpmn
c8ctl element-template --help  # camunda-connectors, camunda-ai-agents
c8ctl feel --help              # camunda-feel

いずれかのコマンドが 0 以外の終了コードを返す場合、インストール済みの c8ctl は 3.0.0 より古く、これらのプラグインがありません。インストールの前にユーザーへ確認してください — 確認なしにインストールを実行せず、その後、次を実行してください。

npm install -g @camunda8/cli

クラスターを選択する

c8ctl を使用するには、接続先のクラスターが必要です。プロファイルを設定する前に、ユーザーに使用するクラスターを確認してください。

1. ローカル開発クラスター（c8run）— 新しいプロジェクト、実験、ローカルでの反復開発に推奨されるデフォルトです。c8ctl から c8run をダウンロード、起動、管理できます。以下の「ローカルクラスター」を参照してください。
2. Camunda 8 SaaS — Camunda のクラウド上で管理されるクラスターです。ユーザーからクライアント認証情報を提供してもらいます。
3. セルフマネージド — ユーザー自身が運用する Camunda 8 クラスター（Kubernetes、Docker Compose など）です。ユーザーからベース URL と、セキュリティ保護されている場合は OAuth 認証情報を提供してもらいます。
4. Camunda Modeler プロファイル — Camunda Desktop Modeler をインストール済みで、接続が設定されている場合、c8ctl はそのプロファイルを自動的にインポートします。modeler: プレフィックスを付けて使用してください（例：modeler:Local Dev）。

ユーザーがまだ選択しておらず、ローカル開発を行う場合は、ローカルの c8run を提案してください — c8ctl cluster start 以外のセットアップは不要です。

ローカルクラスター（c8ctl cluster）

c8ctl には、c8run をラップするデフォルトの cluster プラグインが付属しています。ローカルの Camunda 8 クラスターをダウンロードして起動・停止します。

新しいローカルクラスターを起動する前に、簡単な事前確認を実行してください。不要な再起動を避け、Java／ランタイムの問題を早期に把握できます。

# Is a local cluster already responding?
curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/v2/topology

# Is Java available (c8run needs JRE 21+)?
java -version

• トポロジーが 200 を返した場合、ローカルクラスターはすでに起動しています。作業を続けてください。
• Java がインストールされていないか、バージョンが古い場合は、まず JRE／JDK 21 以降をインストールしてください。
• 対話型ではないシェルによっては、JAVA_HOME が未設定のままでも java -version が動作することがあります（asdf／mise のシムでよく見られます）。Java がインストールされているのに起動に失敗する場合は、c8ctl cluster start を実行する前に JAVA_HOME を明示的に設定してください。

export JAVA_HOME="$(asdf where java 2>/dev/null || mise where java 2>/dev/null)"

例：

# Start the latest stable release (downloads on first run)
c8ctl cluster start

# Start a specific minor version (rolling release — auto-updates patches)
c8ctl cluster start 8.9

# Start a specific full version
c8ctl cluster start 8.9.0-alpha5

# Use the alpha alias for the latest pre-release
c8ctl cluster start alpha

# Check status (running? what version? connection details?)
c8ctl cluster status

# Verify the cluster is responding after start
c8ctl get topology

# Stream logs
c8ctl cluster logs

# Stop the cluster
c8ctl cluster stop

クラスターはデフォルトで http://localhost:8080 で実行されます。プロファイルが設定されていない場合、c8ctl は http://localhost:8080/v2 にフォールバックするため、ほとんどのコマンドは起動したばかりのローカルクラスターに対してそのまま動作します。

c8ctl クラスターコマンドの全リファレンス（list、install、list-remote、delete、キャッシュの場所、バージョンエイリアス）については、references/local-cluster.md を参照してください。

接続：プロファイル

プロファイルには、クラスターへの接続情報が保存されます。c8ctl に付属する local プロファイルは、すでに http://localhost:8080/v2 を指定しているため、ローカルの c8run を使う場合はセットアップ不要です。--profile=local を渡すだけで使用できます。Camunda Desktop Modeler のプロファイルは、modeler: プレフィックスを付けて自動的にインポートされます。

OAuth で保護されたクラスター（SaaS または Self-Managed）のプロファイル設定は、人が一度だけ行う作業です。add profile のフラグや認証情報の取り扱いについては、c8ctl のドキュメントを参照してください。エージェントの判断で add profile を実行しないでください。このスキルを使用する前に、ユーザーにプロファイルを設定してもらってください。

設定済みのプロファイルを使用します。

# Switch the active profile
c8ctl use profile prod

# Show the current active profile
c8ctl which profile

# List all profiles (includes Camunda Modeler profiles with `modeler:` prefix)
c8ctl list profiles

# Use a Modeler profile
c8ctl use profile "modeler:Local Dev"

# One-off override for a single command (active profile unchanged)
c8ctl list pi --profile=staging

マルチテナンシー、認証情報の解決順序、Modeler との連携の詳細については、references/profiles.md を参照してください。

安全性：正しいクラスターを対象にする

c8ctl は、デフォルトでグローバルにアクティブなプロファイルを通じてクラスター接続を解決します。これはリスクを伴います。アクティブなプロファイルが前のセッションで使用した本番環境やステージング環境を指したままで、クラスターにアクセスするコマンドが気付かれないままその環境を対象にする可能性があります。

クラスターにアクセスするコマンドでは、必ず --profile=<name> を明示的に渡してください。特に、状態を変更するコマンド（deploy、run、cancel、resolve、complete、publish、watch）では必ず指定してください。読み取り専用コマンド（get、list、search、feel evaluate）のリスクは低いものの、同じルールを守ることで、コマンド履歴を監査可能な状態に保ち、以前に実行した c8ctl use profile prod によって次のコマンドが意図せず別の環境を対象にするのを防げます。

セッション開始時：クラスターにアクセスする作業を始める前に、c8ctl which profile を実行し、ユーザーに確認してください。アクティブなプロファイル名が共有環境（prod、production、staging、live、saas で始まる名前、顧客名）を示している場合は、操作を行う前に確認してください。そのプロファイルが今回の作業に使うものだと決めつけないでください。

新しいローカル開発プロジェクトでは --profile=local を使用し、前のプロジェクトでアクティブになったプロファイルを引き継がないでください。

c8ctl cluster start/stop/status/logs はこの影響を受けません。プロファイル経由ではなく、ローカルの c8run プロセスを直接操作します。

CLI を使用する

c8ctl のコマンド形式は 2 種類です。

• コア API コマンドは <verb> <resource> の形式です。例：list pi、get inc <key>、complete ut <key>。リソースには短いエイリアスがあります（pi = process-instance、pd = process-definition、ut = user-task、inc = incident、msg = message）。
• プラグインコマンドは <plugin> <subcommand> の形式です。例：cluster start、element-template apply、bpmn lint、feel evaluate。最初のトークンがプラグイン名で、サブコマンドはプラグインによって定義されます。

クイックツアー（簡潔にするため、例では --profile=<name> を省略しています。上記の安全性に関するルールに従い、明示的に渡してください）。

# Inspect the cluster
c8ctl get topology
c8ctl list pd                                  # deployed process definitions
c8ctl list pi                                  # running process instances
c8ctl search inc --state=ACTIVE                # active incidents

# Develop / deploy
c8ctl deploy ./process.bpmn                    # deploy a single resource
c8ctl deploy ./my-project                      # deploy a directory (supports _bb-* and .process-application)
c8ctl run ./order.bpmn --variables='{"orderId":"42"}'   # deploy + start in one step
c8ctl watch                                    # auto-redeploy on file save
c8ctl await pi --id=order-process              # block until completion

# Operate
c8ctl get pi 2251799813685249 --variables      # inspect an instance
c8ctl complete ut 2251799813685250 --variables='{"approved":true}'
c8ctl publish msg payment-received --correlationKey=order-42
c8ctl resolve inc 2251799813685251
c8ctl cancel pi 2251799813685249

動詞／リソースの一覧、プラグインコマンド、リソース固有のフラグについては、references/command-reference.md を参照してください。

出力モード（AI／スクリプト向け）

AI 駆動やスクリプトでの使用では、コマンドごとに JSON を要求し、--fields と組み合わせることで、安定した構造化出力を取得できます。

# Per-command JSON (deterministic, does not mutate session state)
c8ctl list pd --json --fields=key,bpmnProcessId,version,name

# Preview an API request without executing it
c8ctl deploy ./process.bpmn --dry-run

# Pagination / sort (on list and search commands)
c8ctl list pi --limit=50 --sortBy=startDate --desc

c8ctl output json よりも、呼び出しごとに指定する --json フラグを使用してください。後者は session.json を変更し、ほかのツールやセッションにも影響します。C8CTL_OUTPUT_MODE=json 環境変数も現在のシェルでは機能しますが、ほとんどのエージェントハーネスでは別々のツール呼び出しの間でシェルの状態が保持されないため、ある手順での export は次の手順には引き継がれません。構造化出力が必要な場合は、必ずコマンド自体に --json を指定してください。

プラグイン

デフォルトのプラグイン（cluster、bpmn、feel、element-template）は c8ctl にプリロードされているため、インストール手順は不要です。c8ctl list plugins で一覧を確認できます。追加のプラグインをインストールまたは管理する方法については、c8ctl docs を参照してください。

エージェントの判断で c8ctl load plugin を実行しないでください。プラグインコードは c8ctl ランタイム内で実行され、アクティブなプロファイルにフルアクセスできます。プラグインはユーザー自身にインストールしてもらってください。

トラブルシューティング

• c8ctl: command not found（または c8: command not found） — npm のグローバル bin ディレクトリが PATH に含まれていません。npm config get prefix を実行し、<prefix>/bin を PATH に追加してください。
• Node.js version too old — c8ctl がネイティブの TypeScript サポートに必要とする Node のバージョンは 22.18.0 以上です。nvm または asdf を使ってアップグレードしてください。
• ローカルクラスターが起動しない — c8ctl cluster status と c8ctl cluster logs を確認してください。よくある原因は、ポート 8080 がすでに使用されていること、Java がインストールされていないこと（c8run には JRE 21 以上が必要）、バイナリのダウンロードに必要なディスク容量が不足していることです。
• c8ctl cluster start で「port 8080 in use」と表示されるが、ポートは実際には空いている（lsof／nc でリッスン中のプロセスが表示されない） — ソケットのバインドをブロックするサンドボックス環境（一部のコーディングエージェント用ハーネス、制限付きコンテナーモード、macOS App Sandbox など）では、このような状態になります。エージェントのサンドボックス外にあるホストのターミナルで、ユーザーに c8ctl cluster start を直接実行してもらってください。
• c8ctl がデフォルトのデータディレクトリに書き込めない（サンドボックス化されたエージェント、制限付きファイルシステム） — c8ctl を呼び出す前に C8CTL_DATA_DIR=<writable-path> を設定してください。
• SaaS への OAuth エラー — プロファイルが正しく設定されていることを確認してください。SaaS のクラスター URL にはダッシュボード URL ではなく、Zeebe REST address を指定します。OAuth フラグについては、c8ctl docs を参照してください。

参考資料

詳細なリファレンス資料については、references/ から以下を参照してください。

• local-cluster.md — c8ctl cluster コマンドの詳細なリファレンス、バージョンの別名（stable／alpha／rolling）、キャッシュの場所、コネクターシークレットのブートストラップフロー
• profiles.md — プロファイル管理、OAuth フラグ、Modeler との統合、テナントの解決、認証情報の解決順序、環境変数
• command-reference.md — 動詞／リソースのマトリックス、プラグインコマンドの形式、リソースの別名、検索フラグ、グローバルフラグ、デフォルトのプラグイン