Auto-install Owl¶

This document is intended for users who need to use Owl in AI tools. It describes how to complete the installation of Owl CLI, authentication configuration, tool catalog synchronization, and Owl Skill via the auto-install method.

Owl Skill is a companion capability for AI tools, designed to help AI tools recognize the local owl command, understand the Owl tool catalog, and more stably invoke diagnostic capabilities such as logs, metrics, events, and traces. The auto-install process will install Owl Skill after installing Owl CLI.

If you only need to use Owl CLI manually in the terminal, you can skip Owl Skill.

If the current environment cannot execute terminal commands, cannot access the external network or the Owl CLI Endpoint within the enterprise network, or requires offline installation, please use Manual Installation of Owl.

Use Cases¶

Applicable to the following scenarios:

• The AI tool has permission to execute terminal commands.
• The current environment can access the Owl CLI Endpoint and installation resource addresses.
• The current environment allows writing Owl configuration under the local user's home directory.
• The user can provide the Owl CLI Endpoint and temporary authorization code corresponding to the workspace.

Not applicable to the following scenarios:

• The current tool is a pure chat tool and cannot execute terminal commands.
• The current environment is a restricted network or offline environment.
• The current environment does not allow the AI tool to write local configuration.
• Each step of the installation commands requires manual review before execution.

Installation Instructions¶

Copy the following content into the AI tool's conversation window for execution. Before copying, complete the following replacements:

• Replace <OWL_REGISTRY_ENDPOINT> with the Owl CLI Endpoint corresponding to the site where the workspace belongs.
• Replace <YOUR_TEMP_CODE> with the temporary authorization code generated in the TrueWatch console.

Read https://static.truewatch.com/owl/skill.md and follow the document to install and configure Owl CLI and Owl Skill in the current environment.

The installation parameters are as follows:
OWL_REGISTRY_ENDPOINT="<OWL_REGISTRY_ENDPOINT>"
OWL_TEMP_CODE="<YOUR_TEMP_CODE>"

Parameter Description¶

For OWL_REGISTRY_ENDPOINT, only fill in the root Endpoint address. Do not manually concatenate /api/v1 or other paths.

Path to obtain the temporary authorization code:

1. Click the personal avatar in the upper right corner of the console.
2. Select "Personal API Keys".
3. Click "Generate Temporary Authorization Code".

Endpoint List¶

Owl CLI service provides independent Endpoints by site. Please select the corresponding service address based on the node where the workspace is located.

Execution Content¶

The AI tool will automatically perform the following operations based on the installation instructions:

1. Download and install Owl CLI.
2. Write the Owl CLI Endpoint corresponding to the workspace.
3. Use OWL_TEMP_CODE to exchange for an API Key.
4. Write the authentication information to the local Owl configuration.
5. Execute owl sync to synchronize the tool catalog.
6. Install Owl Skill.
7. Verify the availability of the owl command.

After installation is complete, the AI tool can use TrueWatch diagnostic capabilities in conjunction with the local owl command and Owl Skill.

Security Notes¶

Auto-installation does not require providing the API Key in plaintext to the AI tool. The AI tool will use OWL_TEMP_CODE to exchange for an API Key and write the authentication information to the local Owl configuration. The API Key plaintext should not be displayed in replies, logs, or command outputs during the installation process.

OWL_TEMP_CODE is a short-term valid temporary authorization credential, used only for exchanging the API Key during the installation phase. This credential cannot directly call interfaces, but should still be treated as sensitive information while valid. Do not publicly paste it, write it to long-term logs, commit it to code repositories, or share it in documents.

After auto-installation is complete, the resources Owl can access and the operations it can perform are still determined by the exchanged API Key and follow the permission configuration in the TrueWatch workspace.

Common Handling¶

AI Tool Cannot Execute Commands¶

If the AI tool indicates it cannot execute terminal commands, re-execute the installation instructions in an AI tool that has terminal execution permission, or switch to Manual Installation of Owl.

Temporary Authorization Code Invalid, Expired, or Unauthorized¶

If prompted that the authorization code is invalid, expired, or unauthorized, regenerate OWL_TEMP_CODE in the TrueWatch console and execute the installation instructions again.

Endpoint Unreachable¶

If prompted that the Endpoint is unreachable, confirm the following:

• The current environment can access the external network or the Owl CLI Endpoint within the enterprise network.
• The node where the workspace belongs matches the OWL_REGISTRY_ENDPOINT.
• OWL_REGISTRY_ENDPOINT is not concatenated with /api/v1 or other paths.

Cannot Recognize owl Command After Installation¶

If the owl command cannot be recognized after installation, reopen the terminal, or have the AI tool refresh the current terminal environment variables and verify again.

You can execute the following commands to check:

owl --help
owl config show

Tool Catalog Synchronization Failed¶

If owl sync returns authentication, permission, or network errors, confirm:

• Whether OWL_TEMP_CODE has successfully exchanged for an API Key.
• Whether the current API Key has the necessary permissions to synchronize the tool catalog.
• Whether the current environment can access the Owl CLI Endpoint.

For more issues, please refer to Troubleshooting.