Skip to main content
Version: 2025.12

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., 0.16.4) 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-v<VERSION>.tar.gz
  • Ubuntu 22.04: https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/ubuntu-22.04/stari_ubuntu_22_04-amd64-v<VERSION>.tar.gz
  • Ubuntu 24.04: https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/<VERSION>/linux/ubuntu-24.04/stari_ubuntu_24_04-amd64-v<VERSION>.tar.gz
  • 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-v<VERSION>.tar.gz
  • 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-v<VERSION>.tar.gz

macOS:

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

Windows:

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

Replace USERNAME:TOKEN with your actual credentials:

# Linux - Ubuntu 22.04 (example with version 0.16.4)
curl -u USERNAME:TOKEN -o stari_ubuntu_22_04-amd64-v0.16.4.tar.gz \
  https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/0.16.4/linux/ubuntu-22.04/stari_ubuntu_22_04-amd64-v0.16.4.tar.gz
tar -xzf stari_ubuntu_22_04-amd64-v0.16.4.tar.gz
cd stari_ubuntu_22_04-amd64
chmod +x stari_ubuntu_22_04-amd64

# Linux - RHEL 9 (example)
curl -u USERNAME:TOKEN -o stari_rhel_9-amd64-v0.16.4.tar.gz \
  https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/0.16.4/linux/rhel-9/stari_rhel_9-amd64-v0.16.4.tar.gz
tar -xzf stari_rhel_9-amd64-v0.16.4.tar.gz
cd stari_rhel_9-amd64
chmod +x stari_rhel_9-amd64

# macOS
curl -u USERNAME:TOKEN -o stari_macos-arm64-v0.16.4.tar.gz \
  https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/0.16.4/macos/stari_macos-arm64-v0.16.4.tar.gz
tar -xzf stari_macos-arm64-v0.16.4.tar.gz
cd stari_macos-arm64
chmod +x stari_macos-arm64

# Windows (PowerShell)
Invoke-WebRequest -OutFile stari_windows-amd64-v0.16.4.zip `
  -Uri "https://istaridigital.jfrog.io/artifactory/customer-istari-utilities/istari-digital-cli/0.16.4/windows/stari_windows-amd64-v0.16.4.zip" `
  -Headers @{ Authorization = "Basic "+ [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("USERNAME:TOKEN")) }
Expand-Archive -Path stari_windows-amd64-v0.16.4.zip -DestinationPath .
cd stari_windows-amd64

Linux Distribution Note:

Each Linux distribution has its own specific build to ensure compatibility with that system's libraries and dependencies. Choose the build that matches your distribution:

  • For Ubuntu systems: Use the build matching your Ubuntu version (20.04, 22.04, or 24.04)
  • For RHEL, Rocky Linux, AlmaLinux, or Oracle Linux: Use the build matching your major version (8 or 9)

Important:

  • The CLI is distributed as compressed archives (.tar.gz for Linux/macOS, .zip for Windows) containing the executable and all required dependencies
  • After extracting the archive, run the executable from within the extracted directory
  • For easier access, use ./stari path add to install the CLI to your PATH (see below)
  • Basic authentication is not considered secure and is not recommended. Artifactory recommends using a token.
  • Downloading from Artifactory using Powershell
  • Downloading from Artifactory using cURL

New in 2025.09.01: The CLI now includes automated PATH management with stari setup for guided configuration and stari path add for direct installation.

Quick Setup with stari setup (Easiest)​

The recommended way to get started is using the interactive setup command:

# Navigate to extracted directory first
cd stari_ubuntu_22_04-amd64  # or your platform's directory

# Run interactive setup
./stari setup

The setup command will:

  • Check if the CLI is already on your PATH
  • Guide you through adding it to PATH if needed
  • Provide helpful feedback about your installation status

Example when CLI is not on PATH:

Istari Digital CLI Setup
==================================================

⚠ The 'stari' CLI is not currently on your PATH.
You're running it from: /home/user/downloads/stari_ubuntu_22_04-amd64/stari

Would you like to add 'stari' to your PATH now? [Y/n]:

Example when CLI is already set up:

Istari Digital CLI Setup
==================================================

✓ The 'stari' CLI is already on your PATH
Location: /home/user/.istari_digital/bin/stari

You're all set! 🎉

The CLI provides commands to automatically detect and add itself to your system PATH. First, navigate to the extracted directory, then run:

Interactive setup (recommended for first-time users):

# Navigate to extracted directory first
cd stari_ubuntu_22_04-amd64  # or your platform's directory

# Interactive setup with guidance
./stari setup

Direct PATH management:

# Check current PATH status
./stari_ubuntu_22_04-amd64 path check  # or your executable name

# Automatically add to PATH (recommended: no sudo required)
./stari_ubuntu_22_04-amd64 path add --yes

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

The CLI will:

  • On macOS/Linux: Copy the entire CLI bundle (executable + dependencies) to ~/.istari_digital/bin/stari and create a wrapper script, then update your shell configuration (.zshrc or .bashrc)
  • On Windows: Copy the entire CLI bundle to %USERPROFILE%\istari_digital\bin\stari and create a wrapper script, then update your user PATH
  • With --system flag (Unix only): Copy the bundle to /usr/local/lib/stari and create a wrapper at /usr/local/bin/stari (requires sudo)

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

Tip: Run stari setup anytime to check your PATH configuration and get guided help.

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:

$ cd stari_macos-arm64
$ ./stari_macos-arm64 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​

The CLI is now distributed as a compressed archive containing the executable and all dependencies. After extraction:

Move the entire directory to a convenient location (optional):

# Move the extracted directory
sudo mv stari_ubuntu_22_04-amd64 /opt/stari

Create a wrapper script in your PATH:

# Create a wrapper script in /usr/local/bin
sudo tee /usr/local/bin/stari > /dev/null <<'EOF'
#!/bin/sh
exec "/opt/stari/stari_ubuntu_22_04-amd64" "$@"
EOF
sudo chmod +x /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 the extracted directory
mv stari_ubuntu_22_04-amd64 ~/.istari_digital/bin/stari

# Create wrapper script
cat > ~/.istari_digital/bin/stari_wrapper <<'EOF'
#!/bin/sh
exec "$HOME/.istari_digital/bin/stari/stari_ubuntu_22_04-amd64" "$@"
EOF
chmod +x ~/.istari_digital/bin/stari_wrapper
ln -sf ~/.istari_digital/bin/stari_wrapper ~/.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​

  1. Using PowerShell (Recommended):

    # Extract the ZIP if not already done
    Expand-Archive -Path stari_windows-amd64-v0.16.4.zip -DestinationPath .

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

    # Move the extracted directory
    Move-Item "stari_windows-amd64" "$env:USERPROFILE\istari_digital\bin\stari"

    # Create a wrapper batch script
    @"

@echo off "%USERPROFILE%\istari_digital\bin\stari\stari_windows-amd64.exe" %* "@ | Out-File -FilePath "$env:USERPROFILE\istari_digital\bin\stari.bat" -Encoding ASCII

Add to user PATH

$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User") if ($currentPath -notlike "$env:USERPROFILE\istari_digital\bin") { $newPath = $currentPath + ";$env:USERPROFILE\istari_digital\bin" [Environment]::SetEnvironmentVariable("PATH", $newPath, "User") }


2. **Using GUI (Alternative method):**
- Extract the ZIP archive to a folder like `%USERPROFILE%\istari_digital\bin\stari\`
- Create a batch file `stari.bat` in `%USERPROFILE%\istari_digital\bin\` that calls the executable
- Open System Properties → Advanced → Environment Variables
- Under "User variables", edit the PATH variable and add `%USERPROFILE%\istari_digital\bin`

## 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:

```sh
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

Note: Run stari <command> --help for details on each command and its options.

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:

Setup Command​

New in 2025.09.01

stari setup​

Interactive setup for the Istari Digital CLI.

This command provides a guided setup experience that checks if the CLI is on your PATH and helps you configure it if needed.

Usage:

stari setup

Options:

  • --help: Show this message and exit.

What it does:

  • Checks if stari is available on your system PATH
  • If already configured: Displays confirmation message with installation location
  • If not configured: Offers to run stari path add interactively with your confirmation
  • Provides helpful guidance for first-time setup and troubleshooting

Examples:

# Run interactive setup
stari setup

Example output when already configured:

Istari Digital CLI Setup
==================================================

✓ The 'stari' CLI is already on your PATH
Location: /home/user/.istari_digital/bin/stari

You're all set! 🎉

Example output when not configured:

Istari Digital CLI Setup
==================================================

⚠ The 'stari' CLI is not currently on your PATH.
You're running it from: /home/user/downloads/stari_ubuntu_22_04-amd64/stari

Would you like to add 'stari' to your PATH now? [Y/n]:

When to use:

  • First time setting up the CLI after download
  • Verifying your CLI installation is configured correctly
  • Troubleshooting PATH-related issues
  • Getting interactive help with CLI configuration

Note: If you decline the setup, you can always run it again later or use stari path add directly for non-interactive installation.

Path Commands​

New in 2025.09.01

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​

New in 2025.09.01

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 or path 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.

Repository Path Format:

New in 2025.12.01: The --repository flag now supports nested paths.

The --repository flag supports two formats:

  • Simple repository name: customer-istari-agents
  • Nested path: customer-istari-dist/istari-agents (for artifacts stored in subdirectories within a repository)

This allows flexible artifact organization in Artifactory while maintaining backward compatibility with existing configurations.

Examples (Artifactory Installation):

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

# Install from nested repository path (new in 2025.12.01)
stari agent install --repository customer-istari-dist/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 or path 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 (if not provided as arguments) and writing to the agent section of istari_digital_config.yaml.

Usage:

stari agent init [API_URL] [API_TOKEN]

Arguments:

  • API_URL: Agent Registry API URL (optional - will prompt if not provided)
  • API_TOKEN: Agent Registry API Token (optional - will prompt if not provided)

Examples:

# Interactive mode - prompts for API URL and token
stari agent init

# Non-interactive mode - provide arguments
stari agent init https://fileservice.istari.example.com your-api-token

The command will interactively prompt for (if not provided as arguments):

  • 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

stari agent create token​

Create an Agent Personal Access Token (PAT) using the Istari Digital Client.

This command creates a new agent PAT through the Istari Digital Platform and optionally saves it to your agent configuration file.

Usage:

stari agent create token [OPTIONS]

Options:

  • --token_name, --token-name TEXT: Name for the agent token (used to identify the PAT) [required]
  • --save / --no-save: Save the PAT to the agent configuration file (istari_digital_config.yaml). Default is to not save. [default: no-save]
  • --help: Show this message and exit.

Requirements:

Before using this command, you must configure the Istari Digital Client:

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

Examples:

# Create a PAT (displays token but doesn't save to config file)
stari agent create token --token_name my-agent

# Create and save to agent configuration file
stari agent create token --token_name my-agent --save

# Explicitly don't save to config file (same as default behavior)
stari agent create token --token_name my-agent --no-save

# Alternative token name syntax with save to config file
stari agent create token --token-name production-agent --save

Default Behavior:

By default, the PAT is not saved to the configuration file. The token is displayed in the output, and you can manually add it to your configuration or use the --save flag to save it automatically.

Output:

Creating Agent PAT...
==================================================

Creating agent PAT for: my-agent

✅ Agent PAT created successfully!

Token Name: my-agent
Registry URL: https://fileservice.istari.example.com
PAT: eyJ0eXAiOiJKV1QiLCJhbGc...

PAT not saved to configuration.
You can manually add it to your configuration file or run 'stari agent init' later.

With --save:

Creating Agent PAT...
==================================================

Creating agent PAT for: my-agent

✅ Agent PAT created successfully!

Token Name: my-agent
Registry URL: https://fileservice.istari.example.com
PAT: eyJ0eXAiOiJKV1QiLCJhbGc...

Saving PAT to agent configuration...

✅ Agent configuration saved successfully!
Configuration file: ~/.config/istari_digital/istari_digital_config.yaml
Configuration: Top-level agent section

The agent is now ready for use with the configured settings.

stari agent list tokens​

List all Agent Personal Access Tokens (PATs) from the Istari Digital Platform.

This command retrieves and displays all agent PATs, filtering out human tokens to show only agent-specific tokens.

Usage:

stari agent list tokens [OPTIONS]

Options:

  • --help: Show this message and exit.

Requirements:

Before using this command, you must configure the Istari Digital Client:

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

Examples:

# List all agent tokens
stari agent list tokens

Output:

Listing Agent PATs...
==================================================

Retrieving agent PATs...

Found 2 agent PAT(s):

1. production-agent
   ID: abc-123-def-456
   Token: eyJ0eXAiOiJKV1QiLCJhbGc...
   Created: 2025-01-01 10:00:00+00:00
   Last Used: 2025-01-15 14:30:00+00:00

2. dev-agent
   ID: xyz-789-ghi-012
   Token: eyJ0eXAiOiJKV1QiLCJhbGc...
   Created: 2025-01-02 12:00:00+00:00
   Expires: 2026-01-02 12:00:00+00:00

When no agent tokens are found:

Listing Agent PATs...
==================================================

Retrieving agent PATs...

No agent PATs found.

Note: This command only displays agent tokens (tokens with user_type == 'agent'). Human tokens are automatically filtered out from the results.

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 or path is no longer part of the configuration and must be specified at runtime when using commands like stari agent install --repository <repo-name-or-path>.

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

stari client list functions​

New in 2025.11.01

List all available functions from the Istari Digital Platform.

This command retrieves functions published to the registry that are accessible with your current credentials. By default, only the latest version of each function and only active (non-deprecated) functions are shown.

Usage:

stari client list functions [OPTIONS]

Options:

  • --limit, -l INTEGER: Maximum number of functions to return per page [default: 10]
  • --page, -p INTEGER: Page number to display (1-indexed) [default: 1]
  • --show-deprecated, -d: Include deprecated functions in results [default: False]
  • --id, -i: Show function IDs in the output [default: False]
  • --os, -o: Show operating systems in the output [default: False]
  • --status, -s: Show function status (active/deprecated) in the output [default: False]
  • --all-versions, -a: Show all versions instead of just the latest [default: False]
  • --help: Show this message and exit.

Examples:

# List functions with default settings (10 per page, latest versions only, active only)
stari client list functions

# Show more results per page
stari client list functions --limit 50

# Navigate to a specific page
stari client list functions --page 2

# Show function IDs (useful for API calls)
stari client list functions --id

# Show operating systems for each function
stari client list functions --os

# Show function status (active/deprecated)
stari client list functions --status

# Include deprecated functions in results
stari client list functions --show-deprecated

# Show all versions instead of just the latest
stari client list functions --all-versions

# Combine multiple flags for detailed view
stari client list functions --limit 100 --show-deprecated --id --os --status

# Using short flags
stari client list functions -l 100 -dios

Output:

The command displays a formatted table with the following information:

Without --id flag (default):

  • Function Name
  • Tool
  • Version
  • Operating Systems (if --os is used)
  • Status (if --status is used)

With --id flag:

  • Function ID
  • Function Name
  • Tool
  • Version
  • Operating Systems (if --os is used)
  • Status (if --status is used)

Features:

  • Smart Pagination: Automatically fetches multiple API pages when needed to fulfill your requested limit
  • Latest Version Filtering: By default, shows only the latest version of each function using semantic versioning
  • Deduplication: When not showing IDs, groups functions by name/tool/version and aggregates operating systems
  • Active by Default: Only shows active (non-deprecated) functions unless --show-deprecated is used
  • Flexible Display: Choose which columns to display based on your needs
  • Pagination Hints: Provides helpful navigation hints for viewing additional pages

Requirements:

  • istari_digital_registry_url must be configured
  • istari_digital_registry_auth_token must be configured
  • Use stari client init to set up these credentials first

stari client list modules​

New in 2025.11.01

List all available modules from the Istari Digital Platform.

This command retrieves modules published to the registry that are accessible with your current credentials. By default, only the latest version of each module and only active (non-deprecated) modules are shown.

Usage:

stari client list modules [OPTIONS]

Options:

  • --limit, -l INTEGER: Maximum number of modules to return per page [default: 10]
  • --page, -p INTEGER: Page number to display (1-indexed) [default: 1]
  • --show-deprecated, -d: Include deprecated modules in results [default: False]
  • --id, -i: Show module IDs in the output [default: False]
  • --os, -o: Show operating systems in the output [default: False]
  • --status, -s: Show module status (active/deprecated) in the output [default: False]
  • --all-versions, -a: Show all versions instead of just the latest [default: False]
  • --help: Show this message and exit.

Examples:

# List modules with default settings
stari client list modules

# Show more results per page
stari client list modules --limit 50

# Navigate to a specific page
stari client list modules --page 2

# Show module IDs (useful for API calls)
stari client list modules --id

# Show operating systems for each module
stari client list modules --os

# Show module status (active/deprecated)
stari client list modules --status

# Include deprecated modules in results
stari client list modules --show-deprecated

# Show all versions instead of just the latest
stari client list modules --all-versions

# Combine multiple flags for detailed view
stari client list modules --limit 100 --show-deprecated --id --os --status

# Using short flags
stari client list modules -l 50 -dios

Output:

The command displays a formatted table with the following information:

Without --id flag (default):

  • Module Name
  • Version
  • Tool
  • Operating Systems (if --os is used)
  • Status (if --status is used)

With --id flag:

  • Module ID
  • Module Name
  • Version
  • Tool
  • Operating Systems (if --os is used)
  • Status (if --status is used)

Features:

  • Smart Pagination: Automatically fetches multiple API pages to fulfill your requested limit
  • Latest Version Filtering: By default, shows only the latest version of each module using semantic versioning
  • Active by Default: Only shows active (non-deprecated) modules unless --show-deprecated is used
  • Version Management: View all module versions or filter to latest with --all-versions
  • Pagination Hints: Provides helpful navigation hints for viewing additional pages
  • Operating System Aggregation: When viewing all versions, displays OS support for each version

Requirements:

  • istari_digital_registry_url must be configured
  • istari_digital_registry_auth_token must be configured
  • Use stari client init to set up these credentials first

Module Commands​

stari module install​

New in 2025.12.01: Now supports nested repository paths.

Install Istari Digital Modules to agent directories from either a local file or download from Artifactory.

Usage:

stari module install MODULE_NAME [OPTIONS]

Arguments:

  • MODULE_NAME: Module name (e.g., @istari:dassault_cameo) [required]

Options:

  • --repository, -r TEXT: Artifactory repository name or path containing the module artifacts [default: None]
  • --local-file, -l PATH: Path to a local module archive file [default: None]
  • --version, -v TEXT: Specific version of the module to install [default: None]
  • --env, -e TEXT: Target agent installation environment (release, demo, dev, stage) [default: release]
  • --force, -f: Force installation, override existing module without prompting [default: False]
  • --help: Show this message and exit.

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

Repository Path Format:

The --repository flag supports two formats:

  • Simple repository name: customer-istari-modules
  • Nested path: customer-istari-dist/istari-integrations (for artifacts stored in subdirectories within a repository)

This allows flexible artifact organization in Artifactory while maintaining backward compatibility.

Examples (Artifactory Installation):

# Install from Artifactory (simple repository name)
stari module install @istari:dassault_cameo --repository customer-istari-modules

# Install from nested repository path (new in 2025.12.01)
stari module install @istari:dassault_cameo --repository customer-istari-dist/istari-integrations

# Install specific version
stari module install @istari:dassault_cameo --repository customer-istari-modules --version 2.8.1

# Install to specific environment
stari module install @istari:dassault_cameo --repository customer-istari-modules --env dev

# Force installation (skip existing module check)
stari module install @istari:dassault_cameo --repository customer-istari-modules --force

# Using short flags
stari module install @istari:my_module -r my-modules-repo -v 1.0.0 -f

Examples (Local File Installation):

# Install from a local ZIP file
stari module install @istari:dassault_cameo --local-file /path/to/module.zip

# Install from local TAR.GZ file with force
stari module install @istari:my_module --local-file ./module.tar.gz --force

# Using short flags
stari module install @istari:my_module -l /path/to/module.zip -f

Configuration Required (Artifactory Only):

When using --repository, Artifactory configuration is required:

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

Features:

  • Agent-Independent Installation: Modules can be installed without pre-existing agent installation
  • Automatic Directory Creation: Creates necessary directory structure automatically
  • Automatic OS Detection: Automatically detects your operating system to download the appropriate module package
  • Environment Support: Install modules for different environments (release, dev, demo, stage)
  • Automatic Version Selection: Latest version selected when no specific version requested
  • Multiple Archive Formats: Supports ZIP, TAR.GZ, TAR.BZ2, TAR.XZ
  • Smart Directory Stripping: Automatically handles modules with redundant top-level directories
  • Smart Override Logic: Prompts before overwriting existing modules unless --force is used

Installation Paths:

  • Linux/macOS: /opt/local/istari_agent/istari_modules/<module_name> (release)
  • Windows: %APPDATA%\local\istari_agent\istari_modules\<module_name> (release)
  • Environment-specific paths for dev/demo/stage: /opt/local/istari_agent/<env>/istari_modules/<module_name>

stari module update​

New in 2025.12.01: Update existing modules to newer versions.

Update installed Istari Digital Modules to newer versions from either a local file or download from Artifactory.

Usage:

stari module update MODULE_NAME [OPTIONS]

Arguments:

  • MODULE_NAME: Module name (e.g., @istari:dassault_cameo) [required]

Options:

  • --repository, -r TEXT: Artifactory repository name or path containing the module artifacts [default: None]
  • --local-file, -l PATH: Path to a local module archive file [default: None]
  • --version, -v TEXT: Specific version to update to (default: latest) [default: None]
  • --env, -e TEXT: Target agent installation environment (release, demo, dev, stage) [default: release]
  • --force, -f: Force update even if version is same or older [default: False]
  • --backup, -b: Create a backup before updating [default: False]
  • --dry-run: Show what would be updated without making changes [default: False]
  • --help: Show this message and exit.

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

Examples (Artifactory Update):

# Update to latest version
stari module update @istari:dassault_cameo --repository customer-istari-modules

# Update to specific version
stari module update @istari:dassault_cameo --repository customer-istari-modules --version 2.9.0

# Update from nested repository path
stari module update @istari:dassault_cameo --repository customer-istari-dist/istari-integrations

# Update with backup
stari module update @istari:dassault_cameo --repository customer-istari-modules --backup

# Dry-run (preview update)
stari module update @istari:dassault_cameo --repository customer-istari-modules --dry-run

# Update in dev environment
stari module update @istari:dassault_cameo --repository customer-istari-modules --env dev

# Using short flags
stari module update @istari:my_module -r my-repo -v 2.0.0 -b

Examples (Local File Update):

# Update from local file
stari module update @istari:dassault_cameo --local-file /path/to/module.zip

# Update with backup and force
stari module update @istari:my_module --local-file ./module.tar.gz --backup --force

# Using short flags
stari module update @istari:my_module -l /path/to/module.zip -b -f

Configuration Required (Artifactory Only):

When using --repository, Artifactory configuration is required:

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

Features:

  • Smart Version Comparison: Automatically compares current and target versions, skips update if target is not newer (unless --force is used)
  • Optional Backup: Create timestamped backups with --backup flag for easy rollback
  • Dry-Run Mode: Preview update without making changes using --dry-run
  • Automatic Rollback: If update fails and backup exists, automatically restores from backup
  • Version Detection: Reads current version from module_manifest.json
  • Automatic OS Detection: Automatically detects your operating system to download the appropriate module package
  • Environment Support: Update modules in different environments (release, dev, demo, stage)
  • Multiple Archive Formats: Supports ZIP, TAR.GZ, TAR.BZ2, TAR.XZ
  • Nested Repository Support: Works with both simple repository names and nested paths

Update Process:

  1. Checks if module is currently installed
  2. Compares current version with target version
  3. Optionally creates backup of current version
  4. Downloads new version (if from Artifactory)
  5. Removes old version
  6. Installs new version
  7. Verifies installation
  8. On failure: restores from backup automatically

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​

New in 2025.09.01

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​

New in 2025.09.01

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​

New in 2025.09.01

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​

New in 2025.09.01

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