Manual Installation of Owl¶

This document is intended for Owl users, introducing the pre-installation preparations, online installation, version-specific installation, offline installation, and post-installation verification methods for Owl CLI.

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

If the current AI tool supports executing terminal commands and you wish to automate the installation of Owl CLI, authentication configuration, tool catalog synchronization, and Owl Skill installation, you can use Automatic Installation.

Pre-installation Preparation¶

Prepare the following information before installation:

OWL_REGISTRY_ENDPOINT must be filled with the TrueWatch Center Owl CLI Endpoint corresponding to the site where the workspace belongs. Do not manually append /api/v1.

When installing and using Owl CLI on the client side, only OWL_REGISTRY_ENDPOINT and OWL_TOKEN need to be provided. The actual business interface addresses called by the tools are uniformly maintained by the platform side; the client side does not need to configure OWL_AI_API_BASE_URL.

Permission Requirements¶

OWL_TOKEN uses the TrueWatch API Key. The accessible resources and executable operations of Owl CLI depend on the Open API permissions of this API Key.

For installation and initial verification, at least the following conditions must be met:

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

Endpoint List¶

Owl CLI services provide independent Endpoints by site. Please select the corresponding service address based on the site where your workspace is located.

Supported Platforms¶

The current installation package supports the following platforms:

The installation package filename uses owl-cli-*, and the installed command is uniformly 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 following commands are installed on your 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, use the following command to download the script:

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

Version-Specific Installation¶

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 without access to the online installation address, 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 filenames 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¶

After initialization, the configuration directory contains the following:

Post-Installation Verification¶

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

owl --help
owl config show

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

To further verify the connectivity between the current terminal and the Owl CLI Endpoint, you can continue to execute:

owl sync

If owl sync completes normally, it indicates the current terminal can access the Owl CLI Endpoint, and the OWL_TOKEN can be used to synchronize the tool catalog.

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

Upgrade¶

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

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, you can delete the Owl executable file and the local configuration directory.

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

Installing the Companion Skill for Agent (Optional)¶

If you plan to use the TrueWatch Center diagnostic capabilities through Owl in an AI Agent, it is recommended to install the companion 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 with the tool catalog synchronized by Owl to perform more stable diagnostic analysis of logs, metrics, events, traces, etc.

Corresponding skill address:

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

If you currently only need to use Owl CLI manually, you can skip this step.

Taking 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 use the local owl command in conjunction with this skill.

When the terminal prompts that owl cannot be found, handle it as follows:

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