Installing OWL CLI¶

This document is intended for OWL users and describes the prerequisites, online installation, version-specific installation, offline installation, and post-installation verification for the OWL CLI.

owl is the command name for the OWL CLI. After installation, users can use owl locally to synchronize the tool catalog, view tool descriptions, and execute platform capabilities.

If your current AI tool supports executing terminal commands and you want to automatically complete the OWL CLI installation, authentication configuration, tool catalog synchronization, and OWL Skill installation, see Automatic Installation.

Prerequisites¶

Before installing, prepare the following information:

OWL_REGISTRY_ENDPOINT must be the TrueWatch central OWL CLI Endpoint corresponding to the site of the workspace. Do not manually append /api/v1.

• OWL_INSTALL_BASE_URL is used to download the installation script and package
• OWL_REGISTRY_ENDPOINT is used by the CLI to access the OWL service at TrueWatch
• OWL_TOKEN is the service access token used to identify the caller, corresponding to DF-API-KEY
• OWL_API_KEY is the alias environment variable for OWL_TOKEN; if both are set, OWL_API_KEY takes precedence

Permission Requirements¶

OWL_TOKEN uses a TrueWatch API Key. The resources that the OWL CLI can access and the operations it can perform depend on the Open API permissions of that API Key.

Installation and initial verification must meet at least the following conditions:

• Access to the current workspace
• Access to the OWL CLI Endpoint
• Basic access permissions required for synchronizing the tool catalog
• To execute specific tools, the API Key must also have the corresponding read or write permissions for the Open API

Endpoint List¶

The OWL CLI service provides independent Endpoints per site. Select the service address based on the site of your workspace.

Supported Platforms¶

The current installation package supports the following platforms:

The installation package file name uses owl-cli-*, and the command after installation is unified as owl.

Online Installation¶

Linux / macOS¶

OWL_INSTALL_BASE_URL="https://static.truewatch.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.truewatch.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://static.truewatch.com/owl/install.sh)" -- --yes

Before running, ensure that the following commands are installed on the system:

• bash
• curl
• tar

Windows¶

$env:OWL_INSTALL_BASE_URL = "https://static.truewatch.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.truewatch.com"
$env:OWL_TOKEN = "your-token"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Yes

If BitsTransfer is not available on the system, download the script using the following command:

Invoke-WebRequest -Uri "$env:OWL_INSTALL_BASE_URL/install.ps1" -OutFile .\owl-install.ps1

Version-Specific Installation¶

To install a specific version, specify the version number in the installation command.

Linux / macOS¶

OWL_INSTALL_BASE_URL="https://static.truewatch.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.truewatch.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://static.truewatch.com/owl/install.sh)" -- --version "1.3.0" --yes

Windows¶

$env:OWL_INSTALL_BASE_URL = "https://static.truewatch.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.truewatch.com"
$env:OWL_TOKEN = "your-token"
Set-ExecutionPolicy Bypass -Scope Process -Force
Import-Module BitsTransfer
Start-BitsTransfer -Source "$env:OWL_INSTALL_BASE_URL/install.ps1" -Destination .\owl-install.ps1
powershell .\owl-install.ps1 -Version "1.3.0" -Yes

Offline Installation¶

In environments where the online installation address is not accessible, use the offline installation method.

The offline installation directory must contain the following files:

• install.sh or install.ps1
• version
• SHA256SUMS
• The installation package corresponding to the current system

The offline installation package file names are as follows:

Linux / macOS¶

chmod +x ./install.sh
./install.sh \
  --local-package \
  --registry-endpoint "https://owl-api.truewatch.com" \
  --token "your-token" \
  --yes

Windows¶

powershell .\install.ps1 `
  -LocalPackage `
  -RegistryEndpoint "https://owl-api.truewatch.com" `
  -Token "your-token" `
  -Yes

Default Directories After Installation¶

Executable File¶

Configuration Directory¶

To customize the configuration directory, set the environment variable OWL_DIR. When OWL_DIR is set to a non-empty value, the OWL CLI uses that directory as the configuration directory, overriding the default paths in the table above. If not set, it falls back to the default paths ($HOME/.owl / %USERPROFILE%\.owl).

After initialization, the configuration directory contains the following:

Post-Installation Verification¶

After installation, reopen the terminal and run the following commands:

owl --help
owl config show

If the commands output the help information and current configuration correctly, the local executable and configuration file are ready.

To further verify connectivity between the current terminal and the OWL CLI Endpoint, run:

owl sync

If owl sync completes successfully, the current terminal can access the OWL CLI Endpoint, and OWL_TOKEN can be used to synchronize the tool catalog.

If owl sync returns authentication, permission, or network errors, see Troubleshooting.

Upgrading¶

To upgrade to a new version, re-run the online installation command. To upgrade to a specific version, see Version-Specific Installation.

Before upgrading, it is recommended to verify the following:

• The current terminal uses the OWL_REGISTRY_ENDPOINT corresponding to the target workspace
• The current OWL_TOKEN is still valid
• Whether local scripts or automated tasks depend on the behavior of the old version

Uninstalling¶

To uninstall the OWL CLI, delete the OWL executable and the local configuration directory.

Deleting the configuration directory will clear the local token, cache, data files, and logs. Ensure these contents are no longer needed before deleting.

Installing the Companion Skill for Agents (Optional)¶

If you plan to use the diagnostic capabilities of TrueWatch in an AI Agent through OWL, it is recommended to install the companion owl-diagnostics skill for the Agent after completing the OWL CLI installation and running owl sync once.

The owl-diagnostics skill depends on the owl command being installed and executable on the local machine. After installation, the Agent can combine the synchronized tool catalog from OWL to perform log, metric, event, and trace diagnosis more reliably.

The corresponding skill address:

https://github.com/TrueWatchTech/ai-skills/tree/main/owl-diagnostics

If you only need to use the OWL CLI manually, you can skip this step.

Using Codex as an Example

In Codex, you can install the owl-diagnostics skill with the following prompt:

Install this skill for me: https://github.com/TrueWatchTech/ai-skills/tree/main/owl-diagnostics

After installation, restart Codex to activate the newly installed skill. Subsequently, when performing tasks related to TrueWatch diagnosis in Codex, Codex can use the local owl command along with this skill.

If the terminal reports that owl is not found, handle it as follows:

• Windows: Close the current PowerShell and reopen it before running
• Linux / macOS: Close the current terminal window and reopen it before running