Installing OWL Manually¶

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

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

If the AI tool you are currently using supports executing terminal commands, and you want to automatically complete the OWL CLI installation, authentication configuration, tool catalog sync, and OWL Skill installation, you can use Automatic Installation.

Prerequisites¶

Prepare the following information before installation:

OWL_REGISTRY_ENDPOINT must be set to the Guance 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 installation package
• OWL_REGISTRY_ENDPOINT is used by the CLI to access the OWL service at the Guance center
• OWL_TOKEN is the service access token used to identify the caller, corresponding to DF-API-KEY
• OWL_API_KEY is an alias environment variable of OWL_TOKEN; when both are set, OWL_API_KEY takes precedence

Permission Requirements¶

OWL_TOKEN uses a Guance API Key. The resources accessible to and the operations executable by the OWL CLI depend on the Open API permissions of this API Key.

Installation and initial verification require at least the following:

• Access to the current workspace
• Access to the OWL CLI Endpoint
• Basic access permissions required for syncing the tool catalog
• To execute specific tools, the API Key also needs 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 where the workspace is located.

Supported Platforms¶

The current installation package supports the following platforms:

Installation package file names use the owl-cli-* prefix, and the command after installation is uniformly owl.

Online Installation¶

Linux / macOS¶

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

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

• bash
• curl
• tar

Windows¶

$env:OWL_INSTALL_BASE_URL = "https://static.guance.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.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

Installing a Specific Version¶

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

Linux / macOS¶

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

Windows¶

$env:OWL_INSTALL_BASE_URL = "https://static.guance.com/owl"
$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.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 inaccessible, you can use offline installation.

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.guance.com" \
  --token "your-token" \
  --yes

Windows¶

powershell .\install.ps1 `
  -LocalPackage `
  -RegistryEndpoint "https://owl-api.guance.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; when 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:

Post-Installation Verification¶

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

owl --help
owl config show

If the commands can output the 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 with:

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 catalog.

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

Upgrade¶

When an update channel has been configured, run the following command to upgrade:

owl update

owl update uses the channel specified by the local update.base_url. Regular versions only upgrade and do not downgrade; the binary is retained for the same version. After the channel installation script is updated, historical testing-<SHA> builds can also migrate to the official version of that channel, retaining the existing configuration and verifying the SHA256 of the downloaded package; before migrating, confirm that the official version already includes the required testing features.

To reinstall, run the online installation command; to install a specific version, refer to Installing a Specific Version.

After upgrading to v1.4.0, run owl sync to fully refresh the tool catalog. owl.member.list has been migrated to owl.workspace.member.list, and the old name is retained as a calling alias. For details, see Cross-Workspace Query and Member Tool Migration.

Before upgrading, it is recommended to confirm 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

Uninstall¶

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

Deleting the configuration directory clears the local Token, cache, data files, and logs. Confirm that these contents are no longer needed before deletion.

Installing the Companion Skill for the Agent (Optional)¶

If you plan to use OWL in an AI Agent to access the diagnostic capabilities of the Guance center, 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 OWL synced tool catalog to complete diagnostic analysis of logs, metrics, events, traces, and more more reliably.

The corresponding skill address:

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

If you only need to use the OWL CLI manually for now, 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/GuanceCloud/ai-skills/tree/main/owl-diagnostics

After installation, restart Codex to make the newly installed skill take effect. When executing tasks related to Guance diagnostics in Codex later, Codex will use the local owl command together with this skill.

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

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