Owl User Guide¶

This document is intended for users who have already completed the installation of Owl. It explains the initial configuration, synchronization process, common commands, and daily usage.

owl is a unified tool entry point for users and Agents. Users use Owl to synchronize the tool catalog from the TrueWatch Center, view tool descriptions locally, and execute platform capabilities such as Metrics, Logs, Events, Monitoring, Dashboards, and Incidents using unified commands.

Prerequisites¶

Before starting, please ensure the following conditions are met:

owl is installed on this machine.
You have obtained the TrueWatch Center Owl CLI Endpoint for the workspace's site.
You have obtained the access token OWL_TOKEN: a service access token used to identify the caller's identity, corresponding to DF-API-KEY.
The current terminal can access the Owl CLI Endpoint.

When using Owl, the client side only needs to configure the following two core pieces of information:

OWL_REGISTRY_ENDPOINT
OWL_TOKEN: a service access token used to identify the caller's identity, corresponding to DF-API-KEY.

OWL_REGISTRY_ENDPOINT must be the TrueWatch Center Owl CLI Endpoint for the workspace's site. Do not manually append /api/v1.

Correct example:

https://owl-api.guance.com

Incorrect example:

https://owl-api.guance.com/api/v1

Standard Process for First-Time Use¶

For first-time use, please follow the steps below in order.

Step 1: Configure Owl CLI Endpoint and Token¶

Method 1: Environment Variables¶

PowerShell:

$env:OWL_REGISTRY_ENDPOINT = "https://owl-api.guance.com"
$env:OWL_TOKEN = "your-token"

bash / zsh:

export OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com"
export OWL_TOKEN="your-token"

Method 2: Interactive Write to Configuration File¶

owl init
owl login

Execution notes:

owl init is used to write the Owl CLI Endpoint.
owl login is used to write the access token.

Environment variables have higher priority than the configuration file. If environment variables are already set in the current terminal, their values will be used directly during runtime.

Step 2: Synchronize the Tool Catalog¶

owl sync

This step synchronizes the currently available categories and tools from the TrueWatch Center to the local cache. owl sync must be executed first before you can view tools and execute tools.

To synchronize only a specific category, execute:

owl sync -c metric

Step 3: View Categories and Tools¶

owl category list
owl list

View tools under a specific category:

owl list -c metric

View detailed description and parameter definitions for a specific tool:

owl show owl.metric.list

Step 4: Execute a Tool¶

owl exec owl.metric.list --mode source

This command executes the owl.metric.list tool in the metric category and returns information about currently available metric sources.

Getting Started Example¶

The following example shows the complete process from configuration to execution:

export OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com"
export OWL_TOKEN="your-token"

owl sync
owl category list
owl list -c metric
owl show owl.metric.list
owl exec owl.metric.list --mode source

If you need to view json output, execute:

owl list -f json
owl show owl.metric.list -f json
owl exec owl.metric.list --mode source --format json

Common Commands¶

Configuration and Authentication¶

owl init
owl login
owl config show
owl config set registry.endpoint "https://owl-api.guance.com"

Notes:

owl init: Write Owl CLI Endpoint.
owl login: Write access token.
owl config show: View current configuration.
owl config set: Modify a specified configuration item.

Category and Tool Catalog¶

owl category list
owl category show metric
owl list
owl list -c metric
owl show owl.metric.list

Notes:

owl category list: View all categories.
owl category show <categoryID>: View category details and tools under the category.
owl list: View all tools.
owl list -c <categoryID>: View tools under a specific category.
owl show <tool-name>: View tool details and parameter definitions.

Tool Execution¶

owl exec supports four ways to pass parameters.

Method 1: `--key value`¶

owl exec owl.metric.list --mode source

Method 2: `key=value`¶

owl exec owl.metric.list mode=source

Method 3: `-p` to pass JSON¶

owl exec owl.metric.list -p '{"mode":"source"}'

Method 4: Read JSON from standard input¶

echo '{"mode":"source"}' | owl exec owl.metric.list --stdin

Execution rules:

The tool name must match the name displayed in owl list.
All required parameters must be provided.
Parameter names must match the tool definition.
Parameter types must match the tool definition.

For example, the event query tool requires time range parameters:

owl show owl.event.list
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

Local Directory Structure¶

Owl's default directories are as follows.

Executable File¶

Windows: %LOCALAPPDATA%\Programs\owl\owl.exe
Linux / macOS: $HOME/.local/bin/owl, falls back to /usr/local/bin/owl if not writable.

Configuration Directory¶

Windows: %USERPROFILE%\.owl
Linux / macOS: $HOME/.owl

Main Contents in the Configuration Directory¶

config.yaml: Client configuration.
cache/: Synchronized category and tool cache.
data/: Result files for data-type tools.
logs/: Log directory.

Configuration File and Priority¶

Default configuration file path:

Windows: %USERPROFILE%\.owl\config.yaml
Linux / macOS: $HOME/.owl/config.yaml

Example configuration file:

registry:
  endpoint: https://owl-api.guance.com
  sync_interval: 3600

auth:
  token: ""

cache:
  directory: ~/.owl/cache
  ttl: 86400

data:
  directory: ~/.owl/data
  max_age_days: 30

sync:
  parallel: true
  concurrency: 5
  incremental: true

execution:
  default_timeout: 30000
  max_output_size: 10485760

logging:
  level: info
  file: ~/.owl/logs/owl.log

Configuration priority:

Environment variables
config.yaml

Therefore, when both environment variables and the configuration file exist, the values from the environment variables are used at runtime.

Cache and Synchronization¶

owl sync synchronizes category and tool metadata from the TrueWatch Center to the local cache directory. owl category list, owl list, owl show read from the local cache. Therefore, you need to re-execute owl sync in the following scenarios:

After the initial installation is complete.
When the platform releases new tools.
When the platform updates parameters or descriptions of existing tools.
When you need to refresh the local cache content.

Check cache status:

owl cache status

Clear cache:

owl cache clear
owl cache clear -c metric

8. Data Result Files¶

When a tool's defined output type is data, Owl automatically saves the result file to the local data/ directory and records file index and structure information.

List data files:

owl data list

View details of a data file:

owl data show <file-id>

Delete a data file:

owl data rm <file-id>

Clean up historical files:

owl data clean --days 30

View data file statistics:

owl data stats

Schema Output for Agent Integration¶

If you need to integrate Owl into a large language model Agent, you can directly export the function call Schema:

owl schema

Export only a single category:

owl schema -c metric

The output of owl schema includes:

owl_exec: Unified execution of any Owl tool.
owl_list_categories: List categories.
owl_list_tools: List tools.
Currently synchronized tool definitions.

Before integrating with an Agent, execute owl sync once to ensure the local Schema is consistent with the platform's current tool catalog.

10. Common Issue Handling¶

Prompt `tool not found`¶

Cause: The tool is not in the local cache. Solution:

owl sync
owl list

Confirm the tool name and re-execute.

Prompt `category not found`¶

Cause: The category name does not exist or has not been synchronized. Solution:

owl sync
owl category list

Prompt `missing required parameter`¶

Cause: Missing required parameters. Solution:

owl show <tool-name>

Fill in the required parameters according to the tool definition and re-execute.

Prompt `unknown parameter`¶

Cause: Parameter name does not match the tool definition. Solution: Use owl show <tool-name> to verify the parameter name.

Prompt authentication failure or unable to access Owl CLI Endpoint¶

Check the following:

Is OWL_REGISTRY_ENDPOINT the Owl CLI Endpoint for the current site?
Is OWL_TOKEN valid?
Can the current terminal access the Owl CLI Endpoint?

Empty results or results not as expected¶

Check in the following order:

Use owl show <tool-name> to verify parameter definitions.
Use owl list -c <categoryID> to confirm you are executing the correct tool.
Use owl sync to refresh the local cache.

Help Commands¶

View global help:

owl --help

View help for a specific command:

owl help exec
owl help sync
owl help data