joule-cli

SAP Joule CLI スキル

SAP Joule CLI（@sap/joule-cli）のエキスパートです。SAP Joule デジタルアシスタントの構築、デプロイ、テスト、管理に使用するコマンドラインツールです。正しいコマンドの作成、複数ステップのワークフローの自動化、問題のトラブルシューティングを支援します。

CLI バイナリは joule と sapdas（従来のエイリアス）の両方で使用できます。以下の例ではすべて joule を使用します。

インストール

npm install -g @sap/joule-cli        # install
npm install -g -f @sap/joule-cli     # force update
npm uninstall -g @sap/joule-cli      # uninstall

Node.js v20.12.0 ～ v24 が必要です。Linux では、認証情報を安全に保存するために libsecret（または互換性のあるキーリング）が必要です。

グローバルオプション

これらのオプションはすべてのコマンドに適用されます。

オプション	説明
-V, --version	CLI のバージョンを表示します
-d, --debug	追加のデバッグログを表示して保存します
-w, --no-color	色付きの出力を無効にします
-h, --help	使用方法を表示します（joule help または joule <command> --help）

コマンドリファレンス

認証

joule login

Joule にアカウント全体の認証を行います。複数の認証方法に対応しています。

対話型ログイン（初回使用時に推奨）：

joule login

CLI が認証 URL の入力を求め、認証用のブラウザーを開きます。

SSO ログイン：

joule login --sso

PKCE を使用した Identity Authentication Service（IAS）経由のシングルサインオン用にブラウザーを開きます。

URL を明示してログイン：

joule login --authurl https://mytenant.authentication.eu10.hana.ondemand.com

本番ランドスケープでは、認証 URL から API URL が自動的に判定されます。変更する場合：

joule login --authurl <AUTH_URL> --apiurl <API_URL>

サービスキーでログイン（CI/CD）：

joule login --authurl <AUTH_URL> --clientid <ID> --clientsecret <SECRET> --username <USER> --password <PASS>

環境変数でログイン：

joule login --use-env              # reads from .env in current directory
joule login --use-env path/to/.env # reads from specific file

SSO パスコードでログイン：

joule login --sso-passcode <PASSCODE>

オプション	説明
-a, --authurl <url>	認証 URL（例：https://mytenant.authentication.eu10.hana.ondemand.com）
--apiurl <url>	API URL（例：https://mytenant.eu10.sapdas.cloud.sap）
-c, --clientid <id>	サービスインスタンスのクライアント ID
-s, --clientsecret <secret>	サービスインスタンスのクライアントシークレット
-u, --username <user>	ユーザー名
-p, --password <pass>	パスワード
-i, --default-idp	デフォルトの ID プロバイダーを使用します
-e, --unsecure-storage	シークレットをローカルの公開ストアに保存します（非推奨）
--sso-passcode [passcode]	ログイン用のワンタイムパスコード
--sso	IAS 経由のシングルサインオンを使用します
--use-env [path]	環境変数または .env ファイルから認証情報を読み込みます
--store-password	パスワードの保存を有効にします
--no-app-tid	IAS ログイン中に app_tid をスキップします

環境変数（--use-env または CI/CD 用）：JOULE_API_URL、JOULE_AUTH_URL、JOULE_USERNAME、JOULE_PASSWORD、JOULE_CLIENT_ID、JOULE_CLIENT_SECRET、JOULE_DEFAULT_IDP、JOULE_AUTH_SESSION、JOULE_TEST_TIMEOUT。

認証 URL のパターン：

• XSUAA：https://<tenant>.authentication.<landscape>.hana.ondemand.com
• IAS：https://<subdomain>.accounts[optional-suffix].<domain>

セッション情報： セッションには有効期限があります。joule status で確認してください。認証情報はデフォルトで OS のキーチェーン（keytar）を使用して安全に保存されます。--unsecure-storage を使用した場合は、ローカルの設定ファイルに保存されます。

設定ファイルの場所：

• macOS：~/Library/Preferences/joule-cli/config.json
• Linux：~/.config/joule-cli/config.json
• Windows：%APPDATA%\joule-cli\config.json

joule logout

joule logout

保存されているすべての認証情報とトークンを消去します。

joule status

joule status

現在のログイン状態（ログイン中／ログアウト中）、ユーザー名、API URL、認証 URL を表示します。

---

構築とデプロイ

joule compile

デザインタイムアーティファクト（DTA）、つまりローカルのケイパビリティのソースコードを、デプロイ可能なランタイムアーティファクト（DAAR ファイル）にコンパイルします。

joule compile                          # compile current directory
joule compile ./my-capability          # compile specific source folder
joule compile ./my-capability ./output # compile to specific target
joule compile --hide-warnings          # suppress warnings
joule compile -b 5                     # compile in batches of 5

オプション	説明
[source folder]	ソース DTA フォルダー（デフォルト：.）
[target folder]	コンパイル済み .daar の出力先フォルダー（デフォルト：.）
--hide-warnings	コンパイルの警告を非表示にします
-b, --batch-size <n>	一度にコンパイルするケイパビリティの数

ソースフォルダーには capability.sapdas.yaml ファイルが必要です。出力は .daar（Digital Assistant Archive）ファイルです。

joule link

AI Assistant 定義をリンクし、リンク済みアーカイブ（.aiaar ファイル）を作成します。

joule link                              # link current directory
joule link ./my-assistant ./output      # link with explicit paths
joule link --hide-warnings              # suppress warnings

オプション	説明
[source folder]	AI Assistant のソースフォルダー（デフォルト：.）
[target folder]	リンク済み .aiaar の出力先（デフォルト：.）
--hide-warnings	警告を非表示にします
-b, --batch-size <n>	リンク処理のバッチサイズ

ソースには ai_assistant.sapdas.yaml ファイルが含まれている必要があります。

joule deploy

デジタルアシスタントを Joule サービスにデプロイします。

joule deploy                                        # deploy from current dir
joule deploy ./da.sapdas.yaml                       # deploy specific config
joule deploy --compile                              # compile + link + deploy
joule deploy -n my_assistant                        # set assistant name
joule deploy -i ./compiled-daars                    # use pre-compiled DAARs
joule deploy ./da.sapdas.yaml --compile -b 5        # compile in batches, then deploy

オプション	説明
[source file]	da.sapdas.yaml へのパス（デフォルト：.）
-n, --name <name>	デプロイ先のデジタルアシスタント名
-c, --compile	デプロイ前にコンパイルしてリンクします
-i, --daars-input-dir <folder>	コンパイル済み .daar ファイルを含むフォルダー
-b, --batch-size <n>	コンパイルのバッチサイズ

アシスタント名のルール： 3～50 文字で、英数字とアンダースコアのみを使用し、英数字で始まり、英数字で終わる必要があります（^[a-zA-Z0-9]\w*[a-zA-Z0-9]$）。

デプロイのタイムアウト： 最大 15 分です。CLI は 5 秒ごとにジョブのステータスをポーリングします。

---

デプロイ済みアシスタントの管理

joule list

現在のテナントにデプロイ済みのすべてのデジタルアシスタントを一覧表示します。

joule list
joule list --sort name

オプション	説明
--sort <field>	並べ替えの基準：id、name、description、display_name

joule get

指定したデプロイ済みアシスタントの詳細を取得します。

joule get my_assistant
joule get my_assistant --capability my_cap

オプション	説明
<assistant name>	デプロイ済みアシスタントの名前
-c, --capability <name>	指定したケイパビリティの詳細を表示します

joule launch

デフォルトのブラウザーで Joule Web Client を開き、デプロイ済みアシスタントを起動します。

joule launch my_assistant

joule delete

デプロイ済みのデジタルアシスタントを削除します。

joule delete my_assistant

joule update

新規または変更されたケイパビリティを使用して、デプロイ済みアシスタントを更新します（モジュラー機能フラグが必要です）。

joule update my_assistant --capability-file ./my-cap.daar
joule update my_assistant --capability-file ./capability.sapdas.yaml -b 3
joule update my_assistant --mcp-server-file ./mcp-server.json

オプション	説明
<assistant name>	デプロイ済みアシスタントの名前
--capability-file <path>	.daar または capability.sapdas.yaml へのパス（複数指定可能）
--mcp-server-file <path>	MCP サーバーのメタデータ JSON へのパス（複数指定可能、ベータ）
--hide-warnings	警告を非表示にします
-b, --batch-size <n>	コンパイルのバッチサイズ

joule remove

デプロイ済みアシスタントから特定のケイパビリティを削除します（モジュラー機能フラグが必要です）。

joule remove my_assistant --capability com.example:my_capability

オプション	説明
<assistant name>	デプロイ済みアシスタントの名前
--capability <namespace:name>	削除するケイパビリティ（複数指定可能）

---

テストと品質

joule test

デプロイ済みアシスタントに対して、BDD（Cucumber）テストシナリオを実行します。

joule test my_assistant                              # run all tests
joule test my_assistant -t "@smoke"                  # filter by tag
joule test my_assistant --min-success 80             # allow up to 20% failures
joule test my_assistant --feature-path "tests/**/*.feature"
joule test my_assistant --use-env                    # auth from .env
joule test my_assistant -i ./my-cap.daar             # include DAAR files
joule test my_assistant --timeout 60000              # 60s timeout
joule test --init                                    # scaffold test setup

オプション	説明
[assistant name]	デプロイ済みアシスタントの名前
--init	テストセットアップ用のスキャフォールディングを初期化します
-f, --format <fmt>	結果フォーマッター：pretty（デフォルト）、json、html
-t, --tags <expr>	シナリオを絞り込む Cucumber タグ式
--use-env [path]	env / .env ファイルから認証情報を読み込みます
-i, --daar-input-file <files...>	テストに含める DAAR ファイル
--profile <profile...>	テスト実行に使用するユーザープロファイル
--config <file>	cucumber 設定ファイルへのパス
--min-success <pct>	最小合格率（0～100、デフォルト：100）
--feature-path [globs...]	.feature ファイルの Glob パターン（デフォルト：tests/features/**/*.feature）
--published-capabilities	デプロイ済みアシスタントからリモートの DAAR ファイルをダウンロードします
--timeout <ms>	テスト実行のタイムアウト（JOULE_TEST_TIMEOUT 環境変数でも設定可能）
--joule-language <lang>	テスト実行に使用する言語

Cucumber 設定は、次の順序で検索されます：cucumber.json、cucumber.yaml、cucumber.yml、cucumber.js、cucumber.cjs、cucumber.mjs。

テストステップの例（Gherkin 構文）：

Given I am user "[email protected]"
  And I log in
  And I start a new conversation
 When I say "Show my leave balance"
 Then first message has type text
  And first message content contains "balance"
  And response has 2 messages

joule lint

ケイパビリティのソースファイルに対して静的な lint チェックを実行します。

joule lint                                         # lint current directory
joule lint ./my-capability                         # lint specific path
joule lint "**/*.yaml"                             # lint with glob
joule lint -f json                                 # JSON output
joule lint --severity-level error                  # only show errors

オプション	説明
[file/dir/glob]	lint 対象のパスまたは glob パターン（デフォルト：現在のディレクトリ）
-f, --format <fmt>	出力形式：pretty（デフォルト）、json、html、combined
--severity-level <level>	最小重大度：info、warning（デフォルト）、error

エラーが見つかった場合は、コード 1 で終了します。lint ルールでは、シナリオの説明の一意性、ハードコードされた URL、アノテーションの使用方法、OData のページネーションなどをチェックします。

joule scenario-testing-to-feature

従来の YAML テストシナリオファイルを、Cucumber テストフレームワーク用の Gherkin .feature ファイルに変換します。

joule scenario-testing-to-feature
joule scenario-testing-to-feature --input-path "tests/scenarios/**/*.yaml"

オプション	説明
--input-path <glob>	YAML シナリオファイルの glob（デフォルト：tests/scenarios/**/*.yaml）

---

設定ファイル

da.sapdas.yaml（Digital Assistant 定義）

これはメインのデプロイメント記述子です。アシスタントを構成するケイパビリティを定義します。

schema_version: "3.4.0"
name: my_assistant
capabilities:
  # Local capability (from source)
  - type: local
    folder: ./capabilities/greeting
  # Local pre-compiled capability
  - type: local
    path: ./compiled/greeting.daar
  # Released capability from registry
  - type: release
    namespace: com.sap.example
    name: greeting
    version: "1.0.0"
  # Milestone (pre-release) capability
  - type: milestone
    namespace: com.sap.example
    name: greeting
    version: "1.0.0-SNAPSHOT"

名前の制約： 3～50 文字、パターン ^[a-zA-Z0-9]\w*[a-zA-Z0-9]$。 名前空間のパターン： ^(?!\.)[a-zA-Z0-9.]+$（先頭と末尾にドットは使用できません）。 バージョンのパターン： ^([0-9]+)\.([0-9]+)\.([0-9]+)(-)?( SNAPSHOT)?$

ai_assistant.sapdas.yaml（AI Assistant 定義）

ケイパビリティをオーケストレーションする AI Assistant を定義するために、joule link とともに使用します。

schema_version: "1.0.0"
metadata:
  namespace: com.example
  name: my_ai_assistant
  version: "1.0.0"
  display_name: "My AI Assistant"
  description: "An assistant that helps with daily tasks"
business_knowledge: "This assistant operates in the HR domain..."
capabilities:
  - namespace: com.example
    name: leave_management
    scenarios:
      - check_balance
      - request_leave

capability.sapdas.yaml

各ケイパビリティは個別のフォルダーに配置し、このファイルを含める必要があります。ケイパビリティで実行できることを定義するシナリオ定義、ダイアログ関数、フック、エージェントが含まれています。

一般的なワークフロー

開発の全サイクル

# 1. Log in
joule login --sso

# 2. Compile your capability
joule compile ./capabilities/my-cap ./output

# 3. Deploy the assistant
joule deploy ./da.sapdas.yaml --compile

# 4. Launch in browser to verify
joule launch my_assistant

# 5. Run automated tests
joule test my_assistant -t "@smoke"

# 6. Iterate — update a single capability
joule update my_assistant --capability-file ./capabilities/my-cap/capability.sapdas.yaml

CI/CD パイプライン

# Login via env vars (no interactive prompts)
joule login --use-env

# Lint first
joule lint ./capabilities/ --severity-level error

# Compile + deploy in one step
joule deploy ./da.sapdas.yaml --compile -n my_assistant

# Run tests with a minimum pass threshold
joule test my_assistant --min-success 90 -f json --use-env

すべてを再デプロイせずに単一のケイパビリティを更新する

joule update my_assistant --capability-file ./capabilities/updated-cap.daar

デプロイ済みのアシスタントからケイパビリティを削除する

joule remove my_assistant --capability com.example:old_capability

トラブルシューティング

ログインの問題

症状	考えられる原因	解決方法
ログインが失敗しても何も表示されない	認証 URL が正しくない	URL パターンを再確認してください。XSUAA は .authentication.<landscape>.hana.ondemand.com、IAS は .accounts.<domain> を使用します
AUTH_LOGIN_TIMEOUT（エラー 17）	ブラウザーで SSO が完了しなかった	joule login --sso-passcode で再試行するか、ユーザー名／パスワードのフローを使用してください
AUTH_FETCH_TOKEN_FAILED（エラー 14）	クライアントの認証情報が無効	サービスキーのクライアント ID とシークレットを確認してください
AUTH_UNSUPPORTED_AUTH_TYPE（エラー 16）	認証 URL の形式を認識できない	認証 URL が XSUAA または IAS のパターンに従っていることを確認してください
Linux で Keytar エラーが発生する	libsecret がない	libsecret-1-dev（Debian/Ubuntu）または libsecret-devel（RHEL）をインストールするか、--unsecure-storage を使用してください

コンパイル／デプロイの問題

症状	考えられる原因	解決方法
COMPILE_INVALID_SOURCE（エラー 22）	フォルダーに capability.sapdas.yaml がない	正しいディレクトリを指定していることを確認してください
DEPLOY_INVALID_SOURCE（エラー 32）	da.sapdas.yaml が見つからない	指定したパスにファイルが存在することを確認してください
INVALID_ASSISTANT_NAME（エラー 36）	名前がパターンに一致しない	3～50 文字の英数字とアンダースコアを使用し、先頭と末尾は英数字にしてください
JOB_MAX_WAITING_TIME_EXCEEDED（エラー 40）	デプロイに 15 分以上かかった	再試行してください。問題が続く場合は、サービスの稼働状況を確認するか、ケイパビリティの数を減らしてください
LINK_INVALID_SOURCE（エラー 172）	ai_assistant.sapdas.yaml がない	AI アシスタント定義ファイルが存在することを確認してください

テストの問題

症状	考えられる原因	解決方法
テストが見つからない	feature パスが正しくない	正しい glob を指定して --feature-path を使用してください（デフォルト：tests/features/**/*.feature）
テストがタイムアウトする	実行時間の長いシナリオ	--timeout <ms> または JOULE_TEST_TIMEOUT 環境変数でタイムアウト時間を延長してください
CUCUMBER_CONFIGURATION_ERROR（エラー 120）	Cucumber の設定が正しくない	cucumber.json／cucumber.yaml の構文を確認してください
ローカルではテストが成功するが、CI では失敗する	認証が不足している	--use-env を追加し、JOULE_* 環境変数を設定してください

一般的なデバッグ

• 任意のコマンドに -d（デバッグ）を追加すると、詳細なログが出力されます。デバッグファイルは現在のディレクトリに書き込まれます
• joule status を実行して、ログインしていること、および接続先の API／認証 URL を確認します
• joule get <assistant> を使用して、実際にデプロイされている内容を確認します
• Node.js のバージョン（node -v）を確認します。v20.12.0～v24 である必要があります

主な概念

用語	意味
DTA	Design Time Artifact — 機能のソースコード（YAML、ダイアログ、シナリオ、フック）
DAAR	Digital Assistant Archive — コンパイル済みの機能（joule compile の出力）
AIAAR	AI Assistant Archive — リンクされた AI アシスタント（joule link の出力）
RTA	Runtime Artifact — joule deploy 中にアップロードされる完全なデプロイパッケージ
Capability	capability.sapdas.yaml で定義される、単一の機能単位
Digital Assistant	da.sapdas.yaml で定義される、複数の機能をまとめたデプロイ済みインスタンス
AI Assistant	ai_assistant.sapdas.yaml で定義される、業務知識を備えたオーケストレーション層