CLI Commands¶

This document introduces commonly used commands for 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 common configurations:

Common commands:

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

The workspace command can also be written as the alias workspaces.

When setting the access token, the two key names api-key and token are equivalent; writing either one will update the same access token; workspace-level tokens follow the same equivalence rule.

owl workspace same-org list¶

List workspaces that are in the same organization (same-org) as the current account. Supported flags:

Pagination rules:

• By default, only one page is returned. If there are more results, the text output will prompt More results available. Fetch the next page with --before-id <id>, where <id> is the next page cursor returned by the server.
• When --all is added, the CLI will automatically loop to fetch the next page according to the cursor returned by the server, until there are no more results; it will stop if the cursor cannot advance further, avoiding infinite loops for abnormal servers.

Examples:

owl workspace same-org list
owl workspace same-org list --page-size 50
owl workspace same-org list --before-id 12345
owl workspace same-org list --uuid wksp_xxx --uuid wksp_yyy
owl workspace same-org list --all

Environment variables have higher priority than local configuration files. If OWL_REGISTRY_ENDPOINT, OWL_API_KEY, or OWL_TOKEN are already set in the current terminal, Owl CLI will prioritize using the values from the environment variables; when both OWL_API_KEY and OWL_TOKEN exist, OWL_API_KEY takes precedence.

Categories and Tool Catalog¶

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

owl sync

Category and tool viewing commands:

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

Tool Execution¶

Use owl exec to execute tools.

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 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 Files and Priority¶

Default configuration file paths:

Configuration file example:

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:

1. Environment variables
2. config.yaml

Cache and Synchronization¶

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

The following scenarios require re-executing owl sync:

• After 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:

Data Result Files¶

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

Common data file commands:

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 specified categories:

owl schema -c metric

The output of owl schema includes:

• owl_exec: Uniformly execute 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