Version: 2025.10

Istari Digital CLI

The Istari Digital CLI (stari) provides tools and utilities to streamline the development of Istari Digital Integrations. stari also provides an interface for Istari Digital Client SDK.

Downloading the CLI

From Artifactory

Istari Digital CLI binaries are published to Artifactory for release with distribution-specific builds.

Artifactory Download URLs

Replace <VERSION> with the desired version (e.g., 1.2.3) and <DISTRO> with your specific distribution:

Linux (Distribution-Specific):

Ubuntu 20.04: https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/ubuntu-20.04/stari_ubuntu_20_04-amd64
Ubuntu 22.04: https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/ubuntu-22.04/stari_ubuntu_22_04-amd64
Ubuntu 24.04: https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/ubuntu-24.04/stari_ubuntu_24_04-amd64
RHEL 8 (and derivatives: Rocky Linux 8, AlmaLinux 8): https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/rhel-8/stari_rhel_8-amd64
RHEL 9 (and derivatives: Rocky Linux 9, AlmaLinux 9): https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/rhel-9/stari_rhel_9-amd64

macOS:

macOS (Apple Silicon): https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/macos/stari_macos-arm64

Windows:

Windows: https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/windows/stari_windows-amd64.exe

Replace USERNAME:TOKEN with your actual credentials:

# Linux - Ubuntu 22.04 (example)
curl -u USERNAME:TOKEN -o stari https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/ubuntu-22.04/stari_ubuntu_22_04-amd64
chmod +x stari

# Linux - RHEL 9 (example)
curl -u USERNAME:TOKEN -o stari https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/rhel-9/stari_rhel_9-amd64
chmod +x stari

# macOS
curl -u USERNAME:TOKEN -o stari https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/macos/stari_macos-arm64
chmod +x stari

# Windows (PowerShell)
Invoke-WebRequest -OutFile stari.exe https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/windows/stari_windows-amd64.exe -Headers @{ Authorization = "Basic "+ [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("USERNAME:TOKEN")) }

Adding to PATH and Creating Symlinks

Automated PATH Management (Recommended)

The CLI provides commands to automatically detect and add itself to your system PATH:

Check if CLI is on PATH:

# Check current PATH status
./stari path check

Automatically add to PATH:

# Recommended: Add to user directory (no sudo required)
./stari path add --yes

# Alternative: Add to system directory (requires sudo on Unix)
./stari path add --system --yes

The CLI will:

On macOS/Linux: Copy the executable to ~/.istari_digital/bin and update your shell configuration (.zshrc or .bashrc)
On Windows: Copy the executable to %USERPROFILE%\istari_digital\bin and update your user PATH
With --system flag (Unix only): Copy the executable to /usr/local/bin (requires sudo)

After setup, restart your terminal or run source ~/.zshrc (or ~/.bashrc) to use the stari command from anywhere.

Version Detection & Updates:

The CLI intelligently detects versions:

Same version: Skips installation if the same version is already on PATH
Different version: Prompts for confirmation before updating to a new version
Automated updates: Use --yes flag to skip confirmation prompts

Example updating from v1.0.0 to v2.0.0:

$ ./stari path add
⚠ Found stari CLI v1.0.0 on PATH at: ~/.istari_digital/bin/stari
Current executable: ./stari_macos-arm64 (v2.0.0)

This will update the PATH to use the current executable.

Proceed with updating to the new version? [y/n] (y):

Manual PATH Setup

If you prefer to manually configure your PATH, follow these instructions:

macOS and Linux

Move the executable to a directory in your PATH:

# Move to /usr/local/bin (requires sudo)
sudo mv stari /usr/local/bin/stari
sudo chmod +x /usr/local/bin/stari

Or create a symlink:

# Create a symlink from a directory in your PATH
sudo ln -sf /path/to/downloaded/stari /usr/local/bin/stari

Alternative: Add to your personal istari_digital directory:

# Create istari_digital bin directory if it doesn't exist
mkdir -p ~/.istari_digital/bin

# Move or symlink the executable
mv stari ~/.istari_digital/bin/stari
# OR
ln -sf /path/to/downloaded/stari ~/.istari_digital/bin/stari

# Make sure ~/.istari_digital/bin is in your PATH (add to ~/.bashrc, ~/.zshrc, etc.)
echo 'export PATH="$HOME/.istari_digital/bin:$PATH"' >> ~/.bashrc
# OR for zsh
echo 'export PATH="$HOME/.istari_digital/bin:$PATH"' >> ~/.zshrc

# Reload your shell configuration
source ~/.bashrc  # or source ~/.zshrc

Windows

Using PowerShell (Recommended):

# Create istari_digital bin directory
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\istari_digital\bin"

# Move the executable
Move-Item "stari.exe" "$env:USERPROFILE\istari_digital\bin\stari.exe"

# Add to user PATH
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
$newPath = $currentPath + ";$env:USERPROFILE\istari_digital\bin"
[Environment]::SetEnvironmentVariable("PATH", $newPath, "User")

Using GUI (Alternative method):
- Move stari.exe to a folder like %USERPROFILE%\istari_digital\bin\
- Open System Properties → Advanced → Environment Variables
- Under "User variables", edit the PATH variable and add your chosen directory

Configuration

The Istari Digital CLI uses a configuration file named istari_digital_config.yaml to store your API URL and authentication token.

Default Location

By default, the CLI looks for this file at the following location, depending on your operating system:

Linux: ~/.config/istari_digital/istari_digital_config.yaml
macOS: ~/Users/<user>/Library/Application Support/istari_digital/istari_digital_config.yaml
Windows: %APPDATA%\istari_digital\istari_digital_config.yaml

How to Set Up

You can create or update this file automatically by running:

stari client init <registry_url> <registry_api_key> --yes

This command will prompt you for confirmation and write the configuration to the correct location.

If you wish to edit the file manually, ensure it contains the following structure:

cli:
  istari_digital_registry_url: https://your-registry-url
  istari_digital_registry_auth_token: your-api-key

Usage

Executables

If using one of the executable releases, the subsequent commands must reference the executable.

Windows:

./stari.exe --help

POSIX:

./stari --help

Shell Autocompletion (Optional)

The CLI supports TAB autocompletion for commands, options, and dynamic values. To enable this feature:

# Install completion for your current shell
stari --install-completion

# Follow the on-screen instructions to reload your shell

After setup, you'll get TAB autocompletion for command names, script names from manifests, function names, and more.

CLI Commands

The CLI provides commands for interacting with the Istari Digital Platform:

Path Commands

Manage PATH configuration for the Istari Digital CLI.

`stari path check`

Check if the stari CLI is available on PATH.

Usage:

stari path check

Options:

--help: Show this message and exit.

Examples:

# Check if stari is on PATH
stari path check

Output:

✓ The stari CLI is available on PATH
Location: /usr/local/bin/stari
Current executable: /usr/local/bin/stari

Or if not on PATH:

⚠ The stari CLI is NOT on PATH
Current executable: /home/user/downloads/stari

Run 'stari path add' to add it automatically.

`stari path add`

Add the stari CLI to your system PATH automatically.

Usage:

stari path add [OPTIONS]

Options:

--system, -s: Install to system path (/usr/local/bin on Unix). Requires sudo on Unix systems. [default: False]
--yes, -y: Automatically confirm without prompting. [default: False]
--help: Show this message and exit.

Examples:

# Add to user directory (recommended, no sudo needed)
stari path add --yes

# Add to system directory (requires sudo on Unix)
stari path add --system --yes

# Interactive mode (will prompt for confirmation)
stari path add

# Update existing installation (will prompt if different version detected)
./stari path add

# Force update without prompts
./stari path add --yes

What it does:

On macOS/Linux:

Creates ~/.istari_digital/bin directory
Copies the CLI executable to the directory
Adds the directory to your PATH in your shell config (.zshrc or .bashrc)
With --system: Copies the executable to /usr/local/bin (requires sudo)

On Windows:

Creates %USERPROFILE%\istari_digital\bin directory
Copies the CLI executable to the directory
Updates your user PATH environment variable

Version Management:

The path add command intelligently handles version updates:

Same version detected: Skips installation and notifies you

✓ The stari CLI (v1.0.0) is already available on PATH
No action needed.

Different version detected: Prompts for confirmation before updating

⚠ Found stari CLI v1.0.0 on PATH
Current executable: v2.0.0

Proceed with updating to the new version? [y/n]:

Automated updates: Use --yes flag to skip prompts
```
./stari path add --yes
```

Note: After adding to PATH, you'll need to restart your terminal or run source ~/.zshrc (or ~/.bashrc) on Unix systems.

Agent Commands

`stari agent install`

Install the Istari Digital Agent from either a local file or download from Artifactory.

Usage:

stari agent install [OPTIONS]

Options:

--repository, -r TEXT: Artifactory repository name containing the agent artifacts [default: None]
--local-file, -l PATH: Path to a local agent installer file [default: None]
--version, -v TEXT: Specific version of the agent to install [default: None]
--force, -f: Force installation, override existing agent without prompting [default: False]
--help: Show this message and exit.

Note: Either --repository or --local-file must be specified, but not both.

Examples (Artifactory Installation):

# Install latest release agent for current OS
stari agent install --repository customer-istari-agents

# Install specific version
stari agent install --repository customer-istari-agents --version 9.7.2

# Force installation (skip existing agent check)
stari agent install --repository customer-istari-agents --force

# Using short flags
stari agent install -r my-agent-repo -v 9.7.2 -f

Examples (Local File Installation):

# Install from a local .deb file (Linux)
stari agent install --local-file /path/to/istari-agent.deb

# Install from a local .msi file (Windows)
stari agent install --local-file C:\Downloads\istari-agent.msi --force

# Using short flags
stari agent install -l /path/to/installer.deb -f

Configuration Required (Artifactory Only):

When using --repository, Artifactory configuration (URL, username, password) is required. Set up using:

stari client setup-artifactory \
    "https://yourcompany.jfrog.io/artifactory" \
    "your-username" \
    "your-password-or-token" \
    --yes

Note: The repository name is specified at runtime via the --repository flag rather than being stored in the configuration file. This allows for flexibility in targeting different repositories for agents and modules.

Features:

Automatic OS Detection: Automatically detects your operating system (Windows, Linux distributions, macOS) to download the appropriate installer package
Automatic Architecture Detection: Architecture is automatically detected based on the system
Automatic Version Selection: Latest version selected when no specific version requested
Smart Override Logic: Only prompts to override existing installations when actual agent files are detected

Installation Paths:

Linux/macOS: /opt/local/istari_agent/ (release)
Windows: %APPDATA%\local\istari_agent\ (release)

`stari agent init`

Initialize and configure the Istari Digital Agent.

This command will guide you through configuring the agent by prompting for the required configuration values and writing to the agent section of istari_digital_config.yaml.

Usage:

stari agent init [OPTIONS]

Options:

--help: Show this message and exit.

Examples:

# Configure the agent with API credentials
stari agent init

The command will interactively prompt for:

Agent Registry API URL: The URL of the Istari Digital Platform (e.g., https://fileservice-istari.example.com)
Agent Registry API Token: Authentication token for the agent (created via Istari Python SDK or API)

Configuration file locations:

Windows: %APPDATA%\istari_digital\istari_digital_config.yaml
Linux: ~/.config/istari_digital\istari_digital_config.yaml
macOS: ~/Library/Application Support/istari_digital/istari_digital_config.yaml

Client Commands

`stari client init`

Sets up the Istari Digital Client configuration.

Usage:

stari client init REGISTRY_URL REGISTRY_API_KEY [OPTIONS]

Arguments:

REGISTRY_URL: Istari Digital API URL [required]
REGISTRY_API_KEY: API key for authentication [required]

Options:

--yes, -y: Confirm writing configuration to the file(s) [default: False]
--help: Show this message and exit.

Examples:

# Set up client configuration
stari client init https://registry.istari.example.com your-api-key --yes

# Interactive confirmation (will prompt for confirmation)
stari client init https://registry.istari.example.com your-api-key

`stari client ping`

Instantiate a new Istari Digital Client connection and verify credentials.

Usage:

stari client ping [OPTIONS]

Options:

--help: Show this message and exit.

Examples:

# Verify configuration and connection
stari client ping

`stari client setup-artifactory`

Sets up the Artifactory configuration for agent and module installation.

Usage:

stari client setup-artifactory ARTIFACTORY_URL USERNAME PASSWORD [OPTIONS]

Arguments:

ARTIFACTORY_URL: Artifactory base URL (e.g., https://company.jfrog.io/artifactory) [required]
USERNAME: Artifactory username [required]
PASSWORD: Artifactory password or API token [required]

Options:

--yes, -y: Confirm writing configuration to the file(s) [default: False]
--help: Show this message and exit.

Examples:

# Set up Artifactory configuration
stari client setup-artifactory \
    "https://yourcompany.jfrog.io/artifactory" \
    "your-username" \
    "your-api-token" \
    --yes

# Interactive confirmation (will prompt for confirmation)
stari client setup-artifactory \
    "https://yourcompany.jfrog.io/artifactory" \
    "your-username" \
    "your-api-token"

Note: The repository name is no longer part of the configuration and must be specified at runtime when using commands like stari agent install --repository <repo-name>.

`stari client publish`

Publishes a module to the Istari Digital Platform's Registry Service.

This command requires the ISTARI_DIGITAL_REGISTRY_URL and ISTARI_DIGITAL_REGISTRY_AUTH_TOKEN must be set in the configuration.

Usage:

stari client publish MANIFEST_PATH [OPTIONS]

Arguments:

MANIFEST_PATH: Path to module manifest file [required]

Options:

--help: Show this message and exit.

Examples:

# Publish a module manifest
stari client publish path/to/module_manifest.json

# Publish from current directory
stari client publish ./module_manifest.json

Module Commands

`stari module create`

Interactively generate a module manifest file.

Usage:

stari module create [OPTIONS]

Options:

--output, -o TEXT: Output manifest path (default: checks for module_manifest.json in current directory)
--placeholder, -p: Generate manifest with placeholder values instead of interactive prompts [default: False]
--help: Show this message and exit.

Examples:

# Interactive manifest creation (prompts for all values)
stari module create

# Save to specific path
stari module create --output path/to/my_manifest.json

# Generate template with placeholder values
stari module create --placeholder --output template_manifest.json

`stari module lint`

Lint a module manifest file.

Usage:

stari module lint MANIFEST_PATH [OPTIONS]

Arguments:

MANIFEST_PATH: Path to module_manifest.json [required]

Options:

--output, -o TEXT: Output file path for lint results (default: print to console)
--help: Show this message and exit.

Examples:

# Lint manifest and print results to console
stari module lint module_manifest.json

# Save lint results to file
stari module lint module_manifest.json --output lint_results.json

# Lint specific manifest file
stari module lint path/to/custom_manifest.json

`stari module scaffold`

Generate a new module scaffold from template.

Usage:

stari module scaffold [MODULE_NAME] [OPTIONS]

Arguments:

MODULE_NAME: Name of the module to create [optional]

Options:

--output, -o TEXT: Output directory for the scaffold
--type, -t TEXT: Type of scaffold to generate
--author TEXT: Author name [default: Istari Engineering]
--email TEXT: Author email [default: gandalf@istaridigital.com]
--version TEXT: Module version [default: 1.0.0]
--description TEXT: Module description
--list: List available scaffold types [default: False]
--help: Show this message and exit.

Examples:

# List available scaffold types
stari module scaffold --list

# Generate a Python module scaffold
stari module scaffold my-new-module --type python-module

# Generate with custom metadata
stari module scaffold my-module \
  --type python-module \
  --author "Your Name" \
  --email "your.email@example.com" \
  --description "My custom module" \
  --version "1.0.0"

# Specify custom output directory
stari module scaffold my-module --type python-module --output /path/to/output

# Extract scaffold contents into current directory
stari module scaffold my-module --type python-module --output .

`stari module run`

Run a module script defined in the specified manifest file.

Usage:

stari module run SCRIPT_NAME [OPTIONS]

Arguments:

SCRIPT_NAME: Script name (install, build, test_unit, clean) [required]

Options:

--manifest, -m TEXT: Path to module manifest [default: module_manifest.json]
--os TEXT: Target OS - press TAB to see available options from manifest
--help: Show this message and exit.

Examples:

# Run a script (auto-detects current OS)
stari module run build

# Run script for specific OS
stari module run build --os "Ubuntu 22.04"
stari module run build --os windows

# Use specific manifest
stari module run test --manifest path/to/module_manifest.json --os linux

# Run clean script
stari module run clean

# Run install script with specific OS targeting
stari module run install --os "Windows 11"

Example Module Manifest Scripts Section:

{
  "scripts": [
    {
      "operating_systems": ["Windows 10", "Windows 11", "Windows Server 2019"],
      "install": "scripts/windows/install.ps1",
      "build": {
        "command": "scripts/windows/build.ps1",
        "output_path": "dist/"
      },
      "test_unit": "scripts/windows/test_unit.ps1",
      "clean": "scripts/windows/clean.ps1"
    },
    {
      "operating_systems": ["Ubuntu 22.04", "RHEL 8"],
      "install": "scripts/linux/install.sh",
      "build": {
        "command": "scripts/linux/build.sh",
        "output_path": "dist/"
      },
      "test_unit": "scripts/linux/test_unit.sh",
      "clean": "scripts/linux/clean.sh"
    }
  ]
}

Error Handling:

# Missing manifest
$ stari module run build
Error: No module_manifest.json found in current directory: /current/path
Tip: Run this command from a module directory or specify --manifest path

# Unsupported OS
$ stari module run build --os macos
Error: No scripts found for target OS 'macos'. Available: Ubuntu 22.04, RHEL 8, Windows 10

# Missing script
$ stari module run deploy --os linux
Error: Script 'deploy' not found. Available: install, build, test_unit, clean

# Multiple OS matches (conflicts in manifest)
$ stari module run build --os "Ubuntu 22.04"
Error: Multiple script sections match target OS 'Ubuntu 22.04'.
Matched OS names: ['Ubuntu 22.04', 'Ubuntu 22.04'] in sections [0, 1].
Please ensure each OS appears in only one script section.

Conflict Detection:

The CLI detects and prevents execution when the same operating system appears in multiple script sections within a manifest. This prevents unexpected behavior and ensures predictable script selection.

{
  "scripts": [
    {
      "operating_systems": ["Ubuntu 22.04"],
      "build": "scripts/basic/build.sh"
    },
    {
      "operating_systems": ["Ubuntu 22.04"],
      "build": "scripts/enterprise/build.sh",
      "deploy": "scripts/enterprise/deploy.sh"
    }
  ]
}

The above manifest will trigger a conflict error because "Ubuntu 22.04" appears in both sections.

Function Commands

Generate test files and explore functions defined in Istari Digital module manifests.

`stari function list`

List all available functions and their indices from module manifest.

Usage:

stari function list [OPTIONS]

Options:

--manifest, -m TEXT: Path to module manifest file [default: module_manifest.json]
--help: Show this message and exit.

Examples:

# List functions from default manifest (module_manifest.json)
stari function list

# List functions from specific manifest
stari function list --manifest path/to/module_manifest.json

# List functions from custom manifest
stari function list -m custom_manifest.json

`stari function generate test_files`

Generate function input and output test files from module manifest.

Usage:

stari function generate test_files [OPTIONS]

Options:

--function, -f TEXT: Function name (e.g., @istari:extract). If not specified, generates files for all functions. Use 'stari function list' to see available functions.
--index, -i INTEGER: Function implementation index. Use 'stari function list' to see available indices. [default: 0]
--manifest, -m TEXT: Path to module manifest file [default: module_manifest.json]
--output-dir, -o TEXT: Output directory for test files [default: test_files]
--placeholder: Generate files with placeholder values instead of prompting for input [default: False]
--help: Show this message and exit.

Examples:

# Generate test files for a function (interactive prompts)
stari function generate test_files --function @istari:extract

# Generate for specific function implementation
stari function generate test_files --function @istari:extract --index 1

# Generate with placeholder values (non-interactive)
stari function generate test_files --function @istari:extract --placeholder

# Generate test files for ALL functions with placeholder values
stari function generate test_files --placeholder

# Specify custom output directory
stari function generate test_files --function @istari:extract --output-dir my_tests

# Use specific manifest and generate for all functions
stari function generate test_files --manifest custom_manifest.json --placeholder

# Generate for specific function with custom manifest and output
stari function generate test_files \
  --function @istari:transform \
  --index 2 \
  --manifest path/to/manifest.json \
  --output-dir transform_tests

For more detailed information on test file generation, see the dedicated document

Schema Commands

Access and save JSON schemas for Istari Digital module components.

`stari schemas get`

Get a JSON schema by name.

Usage:

stari schemas get SCHEMA_NAME [OPTIONS]

Arguments:

SCHEMA_NAME: Schema name (module_manifest, function_schema, function_input, function_output) [required]

Options:

--output, -o TEXT: Output file path (default: auto-generated filename)
--help: Show this message and exit.

Examples:

# Save module manifest schema to default file (module_manifest_schema.json)
stari schemas get module_manifest

# Save to custom file
stari schemas get module_manifest --output my_schema.json

# Save to current directory with proper schema filename
stari schemas get module_manifest --output .

# Get function input schema
stari schemas get function_input

# Get function output schema with custom name
stari schemas get function_output --output custom_function_output_schema.json

# Available schemas: module_manifest, function_schema, function_input, function_output
stari schemas get function_schema --output ./schemas/function_schema.json

`stari schemas list`

List all available JSON schemas.

Usage:

stari schemas list [OPTIONS]

Options:

--help: Show this message and exit.

Examples:

# List all available schemas
stari schemas list

Downloading the CLI​

From Artifactory​

Artifactory Download URLs​

Adding to PATH and Creating Symlinks​

Automated PATH Management (Recommended)​

Manual PATH Setup​

macOS and Linux​

Windows​

Configuration​

Default Location​

How to Set Up​

Usage​

Executables​

Shell Autocompletion (Optional)​

CLI Commands​

Path Commands​

stari path check​

stari path add​

Agent Commands​

stari agent install​

stari agent init​

Client Commands​

stari client init​

stari client ping​

stari client setup-artifactory​

stari client publish​

Module Commands​

stari module create​

stari module lint​

stari module scaffold​

stari module run​

Function Commands​

stari function list​

stari function generate test_files​

Schema Commands​

stari schemas get​

stari schemas list​

Downloading the CLI

From Artifactory

Artifactory Download URLs

Adding to PATH and Creating Symlinks

Automated PATH Management (Recommended)

Manual PATH Setup

macOS and Linux

Windows

Configuration

Default Location

How to Set Up

Usage

Executables

Shell Autocompletion (Optional)

CLI Commands

Path Commands

`stari path check`

`stari path add`

Agent Commands

`stari agent install`

`stari agent init`

Client Commands

`stari client init`

`stari client ping`

`stari client setup-artifactory`

`stari client publish`

Module Commands

`stari module create`

`stari module lint`

`stari module scaffold`

`stari module run`

Function Commands

`stari function list`

`stari function generate test_files`

Schema Commands

`stari schemas get`

`stari schemas list`