CLI Commands¶

This document describes the common commands of OWL CLI, including configuration and authentication, tool directory sync, tool viewing, pre-execution validation, tool execution, cache management, data file management, and Agent-facing capability negotiation and Schema output.

Configuration and Authentication¶

OWL CLI uses the following common configuration items:

Common commands:

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

The global --conf <path> parameter can select another existing configuration file for a single command, suitable for switching between different authorizations or Endpoints:

owl --conf ~/.owl/prod.yaml config show
owl --conf ~/.owl/prod.yaml sync
owl --conf ~/.owl/testing.yaml exec owl.metric.list --mode source

Write operations such as init, login, config set, workspace use will write back to the file specified by --conf. If this parameter is not specified, OWL continues to use ${OWL_DIR}/config.yaml; the default path is $HOME/.owl/config.yaml.

If the Registry in the local development environment uses a self-signed certificate, you can explicitly disable certificate verification:

owl config set registry.insecure_skip_verify true
# Or only effective for the current process
export OWL_REGISTRY_INSECURE_SKIP_VERIFY=true

This setting is false by default. After enabling it, OWL cannot verify the identity of the Registry and may be vulnerable to man-in-the-middle attacks, so it should not be used in production environments.

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

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

owl workspace same-org list¶

Lists workspaces 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 cycle to fetch the next page according to the cursor returned by the server until there are no more results; if the cursor cannot advance further, it will stop to avoid infinite loops on abnormal servers.

Example:

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 the local configuration file. If OWL_REGISTRY_ENDPOINT, OWL_API_KEY, or OWL_TOKEN have been set in the current terminal, OWL CLI will use the values from the environment variables first; when both OWL_API_KEY and OWL_TOKEN exist, OWL_API_KEY takes precedence.

Categories and Tool Directory¶

Before viewing categories and tools, it is recommended to run a sync 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

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. You can view parameter definitions using owl show <tool-name> before execution.

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 stdin¶

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

Execution Rules¶

When executing a tool, 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
• Visibility of returned results depends on the permissions of the API Key corresponding to OWL_TOKEN

Example: Query Metric Sources¶

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

Example: Query Event List¶

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

Pre-Execution Validation and Capability Negotiation¶

Starting from version 1.2.0, you can use owl validate to validate a tool call before formal execution. This command accepts the same four parameter forms as owl exec, but only validates whether the tool exists, the parameter schema, and tool-specific syntax, without executing the target tool:

owl validate owl.metric.list --mode source
owl validate owl.data.query -p '{"query_text":"L::re(`.*`):(count(*)) [5m]","query_mode":"dql"}' -f json

The JSON result contains:

• valid: whether the call passed validation;
• tool: the validated tool name;
• request_executed: fixed to false, used to confirm that the target tool was not executed;
• issues: structured list of issues, which can include unknown tool, missing parameters, type errors, unknown parameters, or DQL syntax issues.

When validation fails (valid: false), the command process will still exit with status code 0. The Agent must request JSON and parse the result; only when valid is true can owl exec be run. A non-zero status code indicates that validation was not completed and cannot be considered permission to execute.

The DQL mode of owl.data.query calls the DQL validation capability of the Registry; the PromQL mode does not enter the DQL validator. Starting from version 1.2.1, owl.data.simple_query and owl.data.simple_query_file also validate the DQL generated from simplified parameters; on failure, they return generated_dql / dql.builderError, and you should correct select_clause, where_clause, or group_by_clause and retry.

owl exec also performs the same parameter schema validation before the formal request. When the Agent runtime needs to determine whether the current CLI supports pre-validation, you can run:

owl capabilities -f json

The current capability response version is owl.capabilities/v1, and the pre-validation capability identifier is tool.validate/v1. owl tool validate, owl tools validate, owl tool capabilities, and owl tools capabilities are corresponding namespace aliases.

Configuration File and Priority¶

Default configuration file paths:

Configuration file example:

registry:
  endpoint: your-owl-endpoint
  insecure_skip_verify: false
  request_timeout: 150000
  sync_interval: 3600

auth:
  token: ""

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

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

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 highest to lowest:

1. Environment variables
2. Configuration file specified by --conf (when this parameter is set)
3. ${OWL_DIR}/config.yaml (when --conf is not set)

registry.request_timeout controls the total timeout for a single Registry HTTP request, in milliseconds. The default value 150000 is higher than the 130-second server-side deadline for data query tools, reserving time for response encoding and network transmission; only adjust if you clearly understand the upstream query duration.

Cache and Sync¶

owl sync synchronizes the categories and tool metadata from TrueWatch to the local cache directory.

The following scenarios require re-running owl sync:

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

Common sync and cache commands:

Version Update Notification¶

When the update channel is configured using the installer, owl exec checks for new versions at most every 24 hours. When a new version is found, the JSON result will include a notice field; the original success, output, file and other fields remain unchanged; a failed check will not block tool execution.

You can run the following command to upgrade according to the current update channel:

owl update

To disable automatic checking, set update.check: false in the configuration file. Installations without a configured update channel will not perform the check and will not output any prompt.

Data Result Files¶

When the output type defined by the tool is data, OWL CLI will automatically save the result file to the local data/ directory and record the file index and structure information. Starting from version 1.2.1, new files use a 22-character URL-safe random ID, which facilitates Agent referencing and reduces the risk of long file names; the stable queryKey and existing index format remain unchanged.

The file in the JSON result of owl exec only contains path, absolutePath, format, and size, and does not contain the data file id. Do not deduce or guess the ID from the path. Run owl data list -f json to get the authoritative ID, find the corresponding entry, save its files[].id, and pass this value as-is to owl data show or owl data rm.

Common data file commands:

Agent-Facing Schema Output¶

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
• The currently synchronized tool definitions

Before integrating with the Agent, it is recommended to run owl sync once to ensure the local Schema is consistent with the current tool directory on the platform.

If the target client supports MCP, prefer the remote MCP Server integration method described in MCP Server Quickstart.

Help Commands¶

View OWL CLI help:

owl --help

View help for a specific command:

owl help exec
owl help sync
owl help data