Manual Installation of OWL¶

This document is intended for OWL users, introducing the preparation before installing OWL CLI, online installation, installation of a specific version, offline installation, and the verification methods after installation.

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

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

Preparation Before Installation¶

Before installation, prepare the following information:

OWL_REGISTRY_ENDPOINT must be filled with the TrueWatch center 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 for CLI to access the OWL service in the TrueWatch center
• OWL_TOKEN is the service access token, used to identify the caller's identity, corresponding to DF-API-KEY
• OWL_API_KEY is an 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 OWL CLI can access and the operations it can perform depend on the Open API permissions of this API Key.

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

• Can access the current workspace
• Can access the OWL CLI Endpoint
• Has the basic access permissions required to sync the tool directory
• To execute specific tools, the API Key also needs to have read or write permissions for the corresponding Open API

Endpoint List¶

The OWL CLI service provides independent endpoints per site. Select the corresponding service address based on the site of the 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 execution, ensure the system has the following commands installed:

• 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 the system does not provide BitsTransfer, use the following command to download the script:

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

Installation of a Specific Version¶

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

To install a specific version, you can 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.0.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.0.0" -Yes

Offline Installation¶

In environments where the online installation address is not accessible, you can 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, OWL CLI will use that directory as the configuration directory, overriding the default paths in the table above; if not set, it falls back to the default paths in the table above ($HOME/.owl / %USERPROFILE%\.owl).

After initialization, the configuration directory contains the following:

Verification After Installation¶

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

owl --help
owl config show

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

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

owl sync

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

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

Upgrade¶

To upgrade to a new version, re-execute the online installation command; to upgrade to a specific version, refer to Installation of a Specific Version.

Before upgrading, it is recommended to confirm the following:

• The current terminal is using 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

Uninstallation¶

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

Deleting the configuration directory will clear the local Token, cache, data files, and logs. Before deletion, confirm that these contents are no longer needed.

Installing the Supporting Skill for Agent (Optional)¶

If you plan to use the OWL TrueWatch center diagnostic capabilities through the AI Agent, it is recommended to install the supporting owl-diagnostics skill for the Agent after completing the OWL CLI installation and executing 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 OWL-synced tool directory to more stably perform diagnostic analyses of logs, metrics, events, and traces.

Corresponding skill address:

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

If you only need to use 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:

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

After installation, restart Codex to make the newly installed skill effective. Subsequently, when performing tasks related to TrueWatch diagnostics in Codex, Codex can combine the local owl command and this skill.

When the terminal prompts that owl is not found, handle it as follows:

• Windows: Close the current PowerShell, reopen it, and then execute
• Linux / macOS: Close the current terminal window, reopen it, and then execute