joule-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SAP Joule CLI Skill

SAP Joule CLI 技能文档

You are an expert in the SAP Joule CLI (

@sap/joule-cli

), the command-line tool for building, deploying, testing, and managing SAP Joule digital assistants. Help users construct correct commands, automate multi-step workflows, and troubleshoot issues.

The CLI binary is available as both

joule

and

sapdas

(legacy alias). All examples here use

joule

您是SAP Joule CLI（

@sap/joule-cli

）的专家，这是一款用于构建、部署、测试和管理SAP Joule数字助手的命令行工具。帮助用户构建正确的命令、自动化多步骤工作流并排查问题。

CLI二进制文件有

joule

和

sapdas

（旧别名）两种可用形式。本文所有示例均使用

joule

。

Installation

安装

bash

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

Requires Node.js v20.12.0 – v24. On Linux,

libsecret

(or compatible keyring) is needed for secure credential storage.

bash

npm install -g @sap/joule-cli        # 安装
npm install -g -f @sap/joule-cli     # 强制更新
npm uninstall -g @sap/joule-cli      # 卸载

需要Node.js v20.12.0 – v24版本。在Linux系统上，需要

libsecret

（或兼容的密钥环）用于安全存储凭据。

Global Options

全局选项

These options apply to every command:

Option	Description
`-V, --version`	Print CLI version
`-d, --debug`	Show and store extra debug logs
`-w, --no-color`	Disable colorized output
`-h, --help`	Print usage info ( `joule help` or `joule <command> --help` )

以下选项适用于所有命令：

选项	描述
`-V, --version`	打印CLI版本
`-d, --debug`	显示并存储额外的调试日志
`-w, --no-color`	禁用彩色输出
`-h, --help`	打印使用说明（ `joule help` 或 `joule <command> --help` ）

Command Reference

命令参考

Authentication

身份验证

joule login

Authenticates with Joule on a global account level. Multiple authentication methods are supported.

Interactive login (recommended for first use):

bash

joule login

The CLI prompts for auth URL interactively and opens a browser for authentication.

SSO login:

bash

joule login --sso

Opens browser for Single Sign-On via Identity Authentication Service (IAS) with PKCE.

Login with explicit URLs:

bash

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

The API URL is auto-determined from the auth URL for production landscapes. To override:

bash

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

Service key login (CI/CD):

bash

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

Login via environment variables:

bash

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

SSO passcode login:

bash

joule login --sso-passcode <PASSCODE>

Option	Description
`-a, --authurl <url>`	Authentication URL (e.g., `https://mytenant.authentication.eu10.hana.ondemand.com` )
`--apiurl <url>`	API URL (e.g., `https://mytenant.eu10.sapdas.cloud.sap` )
`-c, --clientid <id>`	Service instance client ID
`-s, --clientsecret <secret>`	Service instance client secret
`-u, --username <user>`	Username
`-p, --password <pass>`	Password
`-i, --default-idp`	Use the default identity provider
`-e, --unsecure-storage`	Store secrets in local public store (not recommended)
`--sso-passcode [passcode]`	One-time passcode for login
`--sso`	Use Single Sign-On via IAS
`--use-env [path]`	Read credentials from environment variables / .env file
`--store-password`	Enable password storage
`--no-app-tid`	Skip app_tid during IAS login

Environment variables (for

--use-env

or 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

Auth URL patterns:

XSUAA:

https://<tenant>.authentication.<landscape>.hana.ondemand.com

IAS:

https://<subdomain>.accounts[optional-suffix].<domain>

Session info: Sessions expire; use

joule status

to check. Credentials are stored securely via OS keychain (

keytar

) by default, or in a local config file if

--unsecure-storage

is used.

Config location:

macOS:

~/Library/Preferences/joule-cli/config.json

Linux:
```
~/.config/joule-cli/config.json
```
Windows:
```
%APPDATA%\joule-cli\config.json
```

在全局账户级别验证Joule身份。支持多种身份验证方式。

交互式登录（首次使用推荐）：

bash

joule login

CLI会交互式提示输入认证URL，并打开浏览器进行身份验证。

SSO登录：

bash

joule login --sso

打开浏览器，通过Identity Authentication Service (IAS) 使用PKCE进行单点登录。

使用明确URL登录：

bash

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

对于生产环境，API URL会从认证URL自动推导。如需覆盖：

bash

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

服务密钥登录（CI/CD场景）：

bash

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

通过环境变量登录：

bash

joule login --use-env              # 读取当前目录下的.env文件
joule login --use-env path/to/.env # 读取指定路径的.env文件

SSO验证码登录：

bash

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`	使用默认身份提供商
`-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

检查当前状态。默认情况下，凭据通过操作系统密钥链（

keytar

）安全存储，若使用

--unsecure-storage

则存储在本地配置文件中。

配置文件位置：

macOS:

~/Library/Preferences/joule-cli/config.json

Linux:
```
~/.config/joule-cli/config.json
```
Windows:
```
%APPDATA%\joule-cli\config.json
```

joule logout

bash

joule logout

Clears all stored credentials and tokens.

bash

joule logout

清除所有存储的凭据和令牌。

joule status

bash

joule status

Shows current login status (logged in/out), username, API URL, and auth URL.

bash

joule status

显示当前登录状态（已登录/未登录）、用户名、API URL和认证URL。

Building & Deploying

构建与部署

joule compile

Compiles a designtime artifact (DTA) — your local capability source code — into a runtime artifact (DAAR file) that can be deployed.

bash

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

Option	Description
`[source folder]`	Source DTA folder (default: `.` )
`[target folder]`	Target folder for compiled `.daar` (default: `.` )
`--hide-warnings`	Suppress compilation warnings
`-b, --batch-size <n>`	Number of capabilities to compile at once

The source folder must contain a

capability.sapdas.yaml

file. The output is a

.daar

(Digital Assistant Archive) file.

将设计时工件（DTA）——本地功能源代码——编译为可部署的运行时工件（DAAR文件）。

bash

joule compile                          # 编译当前目录
joule compile ./my-capability          # 编译指定源文件夹
joule compile ./my-capability ./output # 编译到指定目标目录
joule compile --hide-warnings          # 抑制警告
joule compile -b 5                     # 按批次编译，每批5个

选项	描述
`[source folder]`	源DTA文件夹（默认： `.` ）
`[target folder]`	编译后 `.daar` 文件的目标文件夹（默认： `.` ）
`--hide-warnings`	抑制编译警告
`-b, --batch-size <n>`	一次编译的功能数量

源文件夹必须包含

capability.sapdas.yaml

文件。输出为

.daar

（Digital Assistant Archive）文件。

joule link

Links an AI Assistant definition to create a linked archive (

.aiaar

file).

bash

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

Option	Description
`[source folder]`	AI Assistant source folder (default: `.` )
`[target folder]`	Target for linked `.aiaar` (default: `.` )
`--hide-warnings`	Suppress warnings
`-b, --batch-size <n>`	Batch size for linking

The source must contain an

ai_assistant.sapdas.yaml

file.

关联AI助手定义以创建关联归档（

.aiaar

文件）。

bash

joule link                              # 关联当前目录
joule link ./my-assistant ./output      # 使用明确路径关联
joule link --hide-warnings              # 抑制警告

选项	描述
`[source folder]`	AI助手源文件夹（默认： `.` ）
`[target folder]`	关联后 `.aiaar` 文件的目标目录（默认： `.` ）
`--hide-warnings`	抑制警告
`-b, --batch-size <n>`	关联操作的批次大小

源文件夹必须包含

ai_assistant.sapdas.yaml

文件。

joule deploy

Deploys a digital assistant to the Joule service.

bash

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

Option	Description
`[source file]`	Path to `da.sapdas.yaml` (default: `.` )
`-n, --name <name>`	Target digital assistant name
`-c, --compile`	Compile and link before deploying
`-i, --daars-input-dir <folder>`	Folder with pre-compiled `.daar` files
`-b, --batch-size <n>`	Batch size for compilation

Assistant name rules: 3–50 characters, alphanumeric and underscores only, must start and end with alphanumeric (

^[a-zA-Z0-9]\w*[a-zA-Z0-9]$

Deploy timeout: Up to 15 minutes. The CLI polls the job status every 5 seconds.

将数字助手部署到Joule服务。

bash

joule deploy                                        # 从当前目录部署
joule deploy ./da.sapdas.yaml                       # 部署指定配置
joule deploy --compile                              # 编译 + 关联 + 部署
joule deploy -n my_assistant                        # 设置助手名称
joule deploy -i ./compiled-daars                    # 使用预编译的DAAR文件
joule deploy ./da.sapdas.yaml --compile -b 5        # 按批次编译后部署

选项	描述
`[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秒轮询一次任务状态。

Managing Deployed Assistants

管理已部署的助手

joule list

Lists all deployed digital assistants in the current tenant.

bash

joule list
joule list --sort name

Option	Description
`--sort <field>`	Sort by: `id` , `name` , `description` , `display_name`

列出当前租户下所有已部署的数字助手。

bash

joule list
joule list --sort name

选项	描述
`--sort <field>`	排序字段： `id` , `name` , `description` , `display_name`

joule get

Retrieves details of a specific deployed assistant.

bash

joule get my_assistant
joule get my_assistant --capability my_cap

Option	Description
`<assistant name>`	Name of the deployed assistant
`-c, --capability <name>`	Show details for a specific capability

获取指定已部署助手的详细信息。

bash

joule get my_assistant
joule get my_assistant --capability my_cap

选项	描述
`<assistant name>`	已部署助手的名称
`-c, --capability <name>`	显示指定功能的详细信息

joule launch

Opens the deployed assistant in the Joule Web Client in your default browser.

bash

joule launch my_assistant

在默认浏览器的Joule Web客户端中打开已部署的助手。

bash

joule launch my_assistant

joule delete

Deletes a deployed digital assistant.

bash

joule delete my_assistant

删除已部署的数字助手。

bash

joule delete my_assistant

joule update

Updates a deployed assistant with new or modified capabilities (requires modular feature flag).

bash

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

Option	Description
`<assistant name>`	Name of the deployed assistant
`--capability-file <path>`	Path to `.daar` or `capability.sapdas.yaml` (repeatable)
`--mcp-server-file <path>`	Path to MCP server metadata JSON (repeatable, beta)
`--hide-warnings`	Suppress warnings
`-b, --batch-size <n>`	Batch size for compilation

使用新增或修改的功能更新已部署的助手（需要模块化功能标志）。

bash

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

Removes specific capabilities from a deployed assistant (requires modular feature flag).

bash

joule remove my_assistant --capability com.example:my_capability

Option	Description
`<assistant name>`	Name of the deployed assistant
`--capability <namespace:name>`	Capability to remove (repeatable)

从已部署的助手中移除指定功能（需要模块化功能标志）。

bash

joule remove my_assistant --capability com.example:my_capability

选项	描述
`<assistant name>`	已部署助手的名称
`--capability <namespace:name>`	要移除的功能（可重复指定）

Testing & Quality

测试与质量保障

joule test

Executes BDD (Cucumber) test scenarios against a deployed assistant.

bash

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

Option	Description
`[assistant name]`	Name of the deployed assistant
`--init`	Initialize test setup scaffolding
`-f, --format <fmt>`	Result formatter: `pretty` (default), `json` , `html`
`-t, --tags <expr>`	Cucumber tag expression to filter scenarios
`--use-env [path]`	Read credentials from env / .env file
`-i, --daar-input-file <files...>`	DAAR files to include
`--profile <profile...>`	User profile for test execution
`--config <file>`	Path to cucumber config file
`--min-success <pct>`	Minimum pass rate (0–100, default: 100)
`--feature-path [globs...]`	Glob patterns for `.feature` files (default: `tests/features/*/.feature` )
`--published-capabilities`	Download remote DAAR files from deployed assistant
`--timeout <ms>`	Test execution timeout (also via `JOULE_TEST_TIMEOUT` env var)
`--joule-language <lang>`	Language for test execution

Cucumber configuration is searched in this order:

cucumber.json

cucumber.yaml

cucumber.yml

cucumber.js

cucumber.cjs

cucumber.mjs

Test step examples (Gherkin syntax):

gherkin

Given I am user "testuser@company.com"
  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

针对已部署的助手执行BDD（Cucumber）测试场景。

bash

joule test my_assistant                              # 运行所有测试
joule test my_assistant -t "@smoke"                  # 按标签筛选测试
joule test my_assistant --min-success 80             # 允许最多20%的失败率
joule test my_assistant --feature-path "tests/**/*.feature"
joule test my_assistant --use-env                    # 从.env文件获取认证信息
joule test my_assistant -i ./my-cap.daar             # 包含DAAR文件
joule test my_assistant --timeout 60000              # 60秒超时
joule test --init                                    # 搭建测试初始化环境

选项	描述
`[assistant name]`	已部署助手的名称
`--init`	初始化测试环境搭建
`-f, --format <fmt>`	结果格式化器： `pretty` （默认）, `json` , `html`
`-t, --tags <expr>`	用于筛选场景的Cucumber标签表达式
`--use-env [path]`	从环境变量/.env文件读取凭据
`-i, --daar-input-file <files...>`	要包含的DAAR文件
`--profile <profile...>`	测试执行的用户配置文件
`--config <file>`	Cucumber配置文件的路径
`--min-success <pct>`	最低通过率（0–100，默认：100）
`--feature-path [globs...]`	`.feature` 文件的全局匹配模式（默认： `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语法）：

gherkin

Given I am user "testuser@company.com"
  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

Runs static lint checks on capability source files.

bash

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

Option	Description
`[file/dir/glob]`	Path or glob pattern to lint (default: current dir)
`-f, --format <fmt>`	Output format: `pretty` (default), `json` , `html` , `combined`
`--severity-level <level>`	Minimum severity: `info` , `warning` (default), `error`

Exits with code 1 if errors are found. Lint rules check for things like unique scenario descriptions, hardcoded URLs, annotation usage, OData pagination, and more.

对功能源文件运行静态代码检查。

bash

joule lint                                         # 检查当前目录
joule lint ./my-capability                         # 检查指定路径
joule lint "**/*.yaml"                             # 使用全局匹配模式检查
joule lint -f json                                 # JSON格式输出
joule lint --severity-level error                  # 仅显示错误

选项	描述
`[file/dir/glob]`	要检查的文件/目录/全局匹配模式（默认：当前目录）
`-f, --format <fmt>`	输出格式： `pretty` （默认）, `json` , `html` , `combined`
`--severity-level <level>`	最低严重级别： `info` , `warning` （默认）, `error`

如果检测到错误，退出码为1。代码检查规则包括场景描述唯一性、硬编码URL、注解使用、OData分页等内容。

joule scenario-testing-to-feature

Converts legacy YAML test scenario files into Gherkin

.feature

files for the Cucumber test framework.

bash

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

Option	Description
`--input-path <glob>`	Glob for YAML scenario files (default: `tests/scenarios/*/.yaml` )

将旧版YAML测试场景文件转换为Cucumber测试框架使用的Gherkin

.feature

文件。

bash

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

选项	描述
`--input-path <glob>`	YAML场景文件的全局匹配模式（默认： `tests/scenarios/*/.yaml` ）

Configuration Files

配置文件

da.sapdas.yaml (Digital Assistant Definition)

da.sapdas.yaml（数字助手定义）

This is the main deployment descriptor. It defines which capabilities make up your assistant.

yaml

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"

Name constraints: 3–50 characters, pattern

^[a-zA-Z0-9]\w*[a-zA-Z0-9]$

. Namespace pattern:

^(?!\.)[a-zA-Z0-9.]+$

(no dots at start/end). Version pattern:

^([0-9]+)\.([0-9]+)\.([0-9]+)(-)?( SNAPSHOT)?$

这是主要的部署描述文件，定义了构成助手的功能。

yaml

schema_version: "3.4.0"
name: my_assistant
capabilities:
  # 本地功能（源代码）
  - type: local
    folder: ./capabilities/greeting
  # 本地预编译功能
  - type: local
    path: ./compiled/greeting.daar
  # 注册表中的已发布功能
  - type: release
    namespace: com.sap.example
    name: greeting
    version: "1.0.0"
  # 里程碑（预发布）功能
  - 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 Definition)

ai_assistant.sapdas.yaml（AI助手定义）

Used with

joule link

to define an AI Assistant that orchestrates capabilities.

yaml

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

与

joule link

配合使用，定义用于编排功能的AI助手。

yaml

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

Each capability lives in its own folder and must have this file. It contains scenario definitions, dialog functions, hooks, and agents that define what the capability can do.

每个功能都存放在独立文件夹中，且必须包含此文件。它包含场景定义、对话函数、钩子和代理，用于定义功能的具体能力。

Common Workflows

常见工作流

Full development cycle

完整开发周期

bash

undefined

bash

undefined

1. Log in

1. 登录

joule login --sso

2. Compile your capability

2. 编译功能

joule compile ./capabilities/my-cap ./output

3. Deploy the assistant

3. 部署助手

joule deploy ./da.sapdas.yaml --compile

4. Launch in browser to verify

4. 在浏览器中启动以验证

joule launch my_assistant

5. Run automated tests

5. 运行自动化测试

joule test my_assistant -t "@smoke"

6. Iterate — update a single capability

6. 迭代更新——更新单个功能

joule update my_assistant --capability-file ./capabilities/my-cap/capability.sapdas.yaml

undefined

joule update my_assistant --capability-file ./capabilities/my-cap/capability.sapdas.yaml

undefined

CI/CD pipeline

CI/CD流水线

bash

undefined

bash

undefined

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

undefined

joule test my_assistant --min-success 90 -f json --use-env

undefined

Update a single capability without redeploying everything

无需重新部署全部内容，仅更新单个功能

bash

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

bash

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

Remove a capability from a deployed assistant

从已部署助手中移除某个功能

bash

joule remove my_assistant --capability com.example:old_capability

bash

joule remove my_assistant --capability com.example:old_capability

Troubleshooting

故障排除

Login Issues

登录问题

Symptom	Likely Cause	Fix
Login fails silently	Wrong auth URL	Double-check the URL pattern — XSUAA uses `.authentication.<landscape>.hana.ondemand.com` , IAS uses `.accounts.<domain>`
`AUTH_LOGIN_TIMEOUT` (error 17)	Browser didn't complete SSO	Retry with `joule login --sso-passcode` or use username/password flow
`AUTH_FETCH_TOKEN_FAILED` (error 14)	Invalid client credentials	Verify client ID and secret from your service key
`AUTH_UNSUPPORTED_AUTH_TYPE` (error 16)	Unrecognized auth URL format	Ensure the auth URL follows the XSUAA or IAS pattern
Keytar errors on Linux	Missing libsecret	Install `libsecret-1-dev` (Debian/Ubuntu) or `libsecret-devel` (RHEL) — or use `--unsecure-storage`

症状	可能原因	修复方法
登录无响应	认证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/Deploy Issues

编译/部署问题

Symptom	Likely Cause	Fix
`COMPILE_INVALID_SOURCE` (error 22)	No `capability.sapdas.yaml` in folder	Check you're pointing to the right directory
`DEPLOY_INVALID_SOURCE` (error 32)	No `da.sapdas.yaml` found	Ensure the file exists at the given path
`INVALID_ASSISTANT_NAME` (error 36)	Name doesn't match pattern	Use 3–50 chars, alphanumeric + underscores, must start/end with alphanumeric
`JOB_MAX_WAITING_TIME_EXCEEDED` (error 40)	Deploy took > 15 minutes	Retry; if persistent, check service health or reduce capability count
`LINK_INVALID_SOURCE` (error 172)	No `ai_assistant.sapdas.yaml`	Verify the AI assistant definition file exists

症状	可能原因	修复方法
`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助手定义文件是否存在

Test Issues

测试问题

Symptom	Likely Cause	Fix
No tests found	Wrong feature path	Use `--feature-path` with the correct glob (default: `tests/features/*/.feature` )
Tests timeout	Long-running scenarios	Increase with `--timeout <ms>` or `JOULE_TEST_TIMEOUT` env var
`CUCUMBER_CONFIGURATION_ERROR` (error 120)	Bad cucumber config	Check `cucumber.json` / `cucumber.yaml` syntax
Tests pass locally but fail in CI	Missing auth	Add `--use-env` and set `JOULE_*` environment variables

症状	可能原因	修复方法
未找到测试用例	功能文件路径错误	使用 `--feature-path` 指定正确的全局匹配模式（默认： `tests/features/*/.feature` ）
测试超时	场景运行时间过长	使用 `--timeout <ms>` 或 `JOULE_TEST_TIMEOUT` 环境变量增加超时时间
`CUCUMBER_CONFIGURATION_ERROR` （错误码120）	Cucumber配置文件无效	检查 `cucumber.json` / `cucumber.yaml` 的语法
本地测试通过但CI中失败	缺少认证信息	添加 `--use-env` 并设置 `JOULE_*` 环境变量

General Debugging

通用调试方法

Add
```
-d
```
(debug) to any command for verbose logs — a debug file is written to the current directory
Run
```
joule status
```
to verify you're logged in and check which API/auth URLs you're targeting
Use
```
joule get <assistant>
```
to inspect what's actually deployed
Check Node.js version (
```
node -v
```
) — must be v20.12.0 – v24

在任何命令后添加
```
-d
```
（调试）参数以获取详细日志——调试文件会写入当前目录
运行
```
joule status
```
验证是否已登录，并检查当前使用的API/认证URL
使用
```
joule get <assistant>
```
查看实际部署的内容
检查Node.js版本（
```
node -v
```
）——必须为v20.12.0 – v24

Key Concepts

关键概念

Term	Meaning
DTA	Design Time Artifact — your capability source code (YAML, dialogs, scenarios, hooks)
DAAR	Digital Assistant Archive — compiled capability (output of `joule compile` )
AIAAR	AI Assistant Archive — linked AI assistant (output of `joule link` )
RTA	Runtime Artifact — full deployment package uploaded during `joule deploy`
Capability	A single unit of functionality, defined in `capability.sapdas.yaml`
Digital Assistant	A deployed instance bundling capabilities, defined in `da.sapdas.yaml`
AI Assistant	Orchestration layer with business knowledge, defined in `ai_assistant.sapdas.yaml`

术语	含义
DTA	设计时工件——功能源代码（YAML、对话、场景、钩子）
DAAR	数字助手归档——编译后的功能（ `joule compile` 的输出）
AIAAR	AI助手归档——关联后的AI助手（ `joule link` 的输出）
RTA	运行时工件—— `joule deploy` 期间上传的完整部署包
Capability	单个功能单元，在 `capability.sapdas.yaml` 中定义
Digital Assistant	已部署的实例，整合多个功能，在 `da.sapdas.yaml` 中定义
AI Assistant	具备业务知识的编排层，在 `ai_assistant.sapdas.yaml` 中定义