CLI Commands¶

This document introduces the commonly used commands of the Owl CLI, including configuration and authentication, tool catalog synchronization, tool viewing and execution, cache management, data file management, and Schema output for Agents.

Configuration and Authentication¶

Owl CLI uses the following two core configurations:

Configuration Item	Description
`OWL_REGISTRY_ENDPOINT`	The Owl CLI Endpoint corresponding to the site where the workspace belongs
`OWL_TOKEN`	Service access token, used to identify the caller's identity, corresponding to DF-API-KEY

Common commands:

owl init
owl login
owl config show
owl config set registry.endpoint "your-owl-endpoint"

Command	Description
`owl init`	Write the Owl CLI Endpoint
`owl login`	Write the access token
`owl config show`	View current configuration
`owl config set <configuration item> <value>`	Modify the specified configuration item

Environment variables have higher priority than the local configuration file. If OWL_REGISTRY_ENDPOINT or OWL_TOKEN is already set in the current terminal, Owl CLI will prioritize using the values from the environment variables.

Categories and Tool Catalog¶

Before viewing categories and tools, it is recommended to perform a synchronization first:

owl sync

Commands for viewing categories and tools:

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

Command	Description
`owl category list`	View all categories
`owl category show <category ID>`	View category details and tools under the category
`owl list`	View all tools
`owl list -c <category ID>`	View tools under a specific category
`owl show <tool name>`	View tool details and parameter definitions

Tool Execution¶

Use owl exec to execute a tool.

owl exec <tool name> [parameters]

The tool name must match the name displayed in owl list. Before execution, you can use owl show <tool name> to view the parameter definitions.

Parameter Passing Methods¶

owl exec supports the following four parameter passing methods.

Using `--key value`¶

owl exec owl.metric.list --mode source

Using `key=value`¶

owl exec owl.metric.list mode=source

Using `-p` to pass JSON¶

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

Reading JSON from standard input¶

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

Execution Rules¶

When executing tools, please note:

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
Whether the return result is visible depends on the permissions of the API Key corresponding to OWL_TOKEN

Example: Querying Metric Sources¶

owl show owl.metric.list
owl exec owl.metric.list --mode source

Example: Querying Event List¶

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

Configuration File and Priority¶

Default configuration file paths:

Operating System	Configuration File Path
Windows	`%USERPROFILE%\.owl\config.yaml`
Linux / macOS	`$HOME/.owl/config.yaml`

Example configuration file:

registry:
  endpoint: your-owl-endpoint
  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 from high to low is as follows:

Environment variables
config.yaml

Cache and Synchronization¶

owl sync will synchronize the category and tool metadata from TrueWatch to the local cache directory.

The following scenarios require re-executing owl sync:

After the initial installation is complete
When the platform releases new tools
When the platform updates parameters or descriptions of existing tools
When local cache content needs to be refreshed

Common synchronization and cache commands:

Command	Description
`owl sync`	Synchronize all categories and tools
`owl sync -c <category ID>`	Synchronize only the specified category
`owl cache status`	View cache status
`owl cache clear`	Clear all cache
`owl cache clear -c <category ID>`	Clear cache for the specified category

Data Result Files¶

When the output type defined for a tool is data, Owl CLI will automatically save the result file to the local data/ directory and record the file index and structure information.

Common data file commands:

Command	Description
`owl data list`	View the list of data files
`owl data show <file-id>`	View details of the specified data file
`owl data rm <file-id>`	Delete the specified data file
`owl data clean --days <number of days>`	Clean up historical files older than the specified number of days
`owl data stats`	View data file statistics

Schema Output for Agents¶

If you need to integrate Owl CLI into a custom Agent, you can export the function call Schema:

owl schema

Export only the specified 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, it is recommended to execute owl sync once to ensure the local Schema is consistent with the platform's current tool catalog.

If the target client supports MCP, prioritize using the remote MCP Server integration method described in MCP Server Quick Start.

Help Commands¶

View Owl CLI help:

owl --help

View help for a specific command:

owl help exec
owl help sync
owl help data