Automatically Installing OWL¶

This document is intended for users who need to use OWL in AI tools. It describes how to complete the OWL CLI installation, authentication configuration, tool catalog synchronization, and OWL Skill installation through the automatic installation method.

OWL Skill is a companion capability for AI tools. It helps AI tools recognize the local owl command, understand the OWL tool catalog, and more reliably invoke diagnostic capabilities such as logs, metrics, events, and traces. After installing the OWL CLI, the automatic installation flow installs OWL Skill according to the mechanism of the current agent.

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

If you need to review installation commands step by step or perform an offline installation, use Manually Installing OWL. If the current environment cannot access the OWL CLI Endpoint, resolve the network access issue first; the installation method does not change the network requirements for invocation.

Supported Agents¶

Codex, Claude Code, Cursor, Trae, GitHub Copilot (VS Code), and Windsurf can all use the unified process on this page. Operate in an agent mode that has terminal execution permissions. Other agents that can execute terminal commands can also use the same process without switching to a specific product.

The OWL CLI should be installed in the environment where the agent actually executes commands. For a local agent, install it on the local machine. For remote development, container, or cloud agents, install it in the corresponding environment and ensure that environment can access the OWL CLI Endpoint. A successful local installation does not mean the remote environment can find owl.

Before installation, you can confirm your choice in the Access Method Guide. If the current tool cannot execute terminal commands but supports remote MCP, you can use MCP Access instead.

Use Cases¶

This method is suitable for the following scenarios:

• The AI tool has terminal command execution permissions.
• The current environment can access the OWL CLI Endpoint and installation resource addresses.
• The current environment allows writing OWL configuration to the local user directory.
• The user can provide the OWL CLI Endpoint corresponding to the Workspace and a temporary authorization code.

It is not suitable for the following scenarios:

• The current tool is a pure chat tool and cannot execute terminal commands.
• The current environment is on a restricted or offline network.
• The current environment does not allow the AI tool to write local configuration.
• Every command during installation must be manually reviewed before execution.

Step 1: Install the CLI and the Companion Skill¶

The following process applies to all agents mentioned above. Send the installation instructions to the current agent's chat window and confirm the necessary command execution permissions as prompted. The automatic installation includes the companion Skill installation steps, so there is no need to install it separately again after confirming the installation succeeds. Before copying, complete the following replacements:

• Replace <OWL_REGISTRY_ENDPOINT> with the OWL CLI Endpoint corresponding to the site of your Workspace.
• 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.

Installation parameters:
OWL_REGISTRY_ENDPOINT="<OWL_REGISTRY_ENDPOINT>"
OWL_TEMP_CODE="<YOUR_TEMP_CODE>"

The official Skill documentation provides two versions: skill.md (Chinese) and skill.en.md (English). Choose the version according to the language environment of the AI tool.

Step 2: Verify the Installation and Complete the First Invocation¶

After the installation, send the following in the same agent conversation:

Check whether the owl command and the owl-diagnostics Skill are available. First view the tool description of owl.metric.list, then use the OWL CLI to list the metric sources available in the current Workspace. If a result file is returned, read the file and check the business results. Only perform read operations. Do not modify any configuration or resources.

Check the following results:

• The agent can execute owl --help; the companion Skill is installed and the agent can read its task description; if prompted to refresh or start a new session, follow the requirements of the current agent.
• owl sync completed successfully; you can view the synchronized tool catalog.
• The agent actually executed the OWL CLI tool call; if a result file was returned, its contents were read, no business errors were found, and the response was based on the returned data.

Do not judge a query as successful based only on the command's exit code being 0; you must also check the business status and error information in the returned content (such as success, error). If the query succeeds but returns an empty list, check the data and permissions of the current Workspace. For troubleshooting, see CLI and Skill Issues in Agents.

If the Skill installation fails, or the current agent has no native Skill mechanism, the CLI can still be used independently. Following the prompts in the installation instructions, import the companion guide through the current agent's Skill or custom instructions entry, and then separately confirm whether it can be read.

Users who have already manually installed the CLI can directly follow Installing the Companion Skill to complete the remaining steps without reinstalling the CLI.

Parameter Descriptions¶

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

To obtain a temporary authorization code:

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

Endpoint List¶

The OWL CLI service provides a dedicated Endpoint for each site. Select the corresponding service address based on the site where the Workspace is located.

Actions Performed¶

The AI tool will automatically perform the following actions according to the installation instructions:

1. Download and install the OWL CLI
2. Write the OWL CLI Endpoint corresponding to the Workspace
3. Use OWL_TEMP_CODE to redeem an API Key
4. Write the authentication information to the local OWL configuration
5. Run owl sync to synchronize the tool catalog
6. Install OWL Skill
7. Verify that the owl command is available

After both the CLI and the Skill are installed successfully, the AI tool can use the diagnostic capabilities of TrueWatch by combining the owl command and OWL Skill in its runtime environment.

Security Notes¶

The automatic installation does not require providing the API Key plaintext to the AI tool. The AI tool uses OWL_TEMP_CODE to redeem an API Key and writes the authentication information to the local OWL configuration. During the installation, the API Key plaintext must not be displayed in replies, logs, or command output.

OWL_TEMP_CODE is a temporary authorization credential valid for a short period. Use it as soon as possible after generation; it expires immediately after successfully redeeming an API Key and is used only for installation-stage authorization. This credential cannot be used to directly call APIs, but it should still be handled as sensitive information while valid. Do not paste it publicly, write it into long-term logs, commit it to code repositories, or share it in shared documents.

After the automatic installation is completed, the resources OWL can access and the operations it can perform are still determined by the redeemed API Key and follow the permission configuration in the TrueWatch Workspace.

Common Issues¶

The AI Tool Cannot Execute Commands¶

If the AI tool reports that it cannot execute terminal commands, run the installation instructions again in an AI tool with terminal execution permissions, or switch to Manually Installing OWL.

The Temporary Authorization Code Is Invalid, Expired, or Unauthorized¶

If the authorization code is reported as invalid, expired, or unauthorized, regenerate OWL_TEMP_CODE in the TrueWatch console and run the installation instructions again.

The Endpoint Cannot Be Accessed¶

If the Endpoint is reported as inaccessible, verify the following:

• The current environment can access the OWL CLI Endpoint over the public internet or the enterprise network.
• The site where the Workspace is located matches OWL_REGISTRY_ENDPOINT.
• /api/v1 or other paths are not appended to OWL_REGISTRY_ENDPOINT.

The owl Command Is Not Recognized After Installation¶

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

You can run the following commands to check:

owl --help
owl config show

Tool Catalog Synchronization Fails¶

If owl sync returns an authentication, permission, or network error, verify the following:

• Whether OWL_TEMP_CODE has been successfully redeemed for an API Key.
• Whether the current API Key has the permissions required to synchronize the tool catalog.
• Whether the current environment can access the OWL CLI Endpoint.

For more issues, refer to Troubleshooting.