joule-cli

# SAP Joule CLI Skill 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`. ## 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. ## 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`) | ## 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 logout ```bash joule logout ``` Clears all stored credentials and tokens. #### joule status ```bash joule status ``` Shows current login status (logged in/out), username, API URL, and auth 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. #### 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. #### 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. --- ### 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` | #### 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 | #### joule launch Opens the deployed assistant in the Joule Web Client in your default browser. ```bash joule launch my_assistant ``` #### joule delete Deletes a deployed digital 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 | #### 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) | --- ### 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`.