CLI Commands¶

This document introduces common OWL CLI commands, including configuration and authentication, tool directory synchronization, tool discovery, preflight validation, execution, cache management, data file management, and capability negotiation 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 aliased as workspaces.

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

owl workspace same-org list¶

List workspaces in the same organization 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 server-returned cursor until there are no more results; if the cursor cannot continue to advance, it will stop to avoid infinite loops with a faulty server.

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 take precedence over the local configuration file. If OWL_REGISTRY_ENDPOINT, OWL_API_KEY or OWL_TOKEN are already set in the current terminal, OWL CLI will use the values from the environment variables first; if 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 perform 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 tools.

owl exec <tool_name> [parameters]

The tool name must match the name shown in owl list. Before execution, you can view parameter definitions using owl show <tool_name>.

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 tools, please note:

• The tool name must match the name shown 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 returned results are visible depends on the permission 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

Preflight Validation and Capability Negotiation¶

Starting with 1.2.0, use owl validate to check a tool call before execution. It accepts the same four parameter forms as owl exec, but only validates tool availability, the parameter schema, and tool-specific syntax. It never executes the selected 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 includes:

• valid: Whether the call passed validation.
• tool: The validated tool name.
• request_executed: Always false, confirming that the selected tool was not executed.
• issues: Structured problems such as an unknown tool, missing parameters, type errors, unknown parameters, or DQL syntax errors.

An invalid result (valid: false) is still printed with a zero process exit status. Agents must request JSON, parse it, and run owl exec only when valid is true. A non-zero exit status means validation did not complete and must not be treated as approval to execute.

For owl.data.query, DQL mode calls the Registry DQL validator, while PromQL mode skips DQL validation. Starting with 1.2.1, owl.data.simple_query and owl.data.simple_query_file also validate the DQL generated from their simplified parameters. A failure returns generated_dql / dql.builderError; correct select_clause, where_clause, or group_by_clause before retrying.

owl exec applies the same parameter-schema checks before sending the request. Agent runtimes can determine whether the installed CLI supports preflight validation by running:

owl capabilities -f json

The current response version is owl.capabilities/v1, and the preflight capability is tool.validate/v1. owl tool validate, owl tools validate, owl tool capabilities, and owl tools capabilities are equivalent namespace aliases.

Configuration File 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: 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 high to low:

1. Environment variables
2. config.yaml

Cache and Synchronization¶

owl sync syncs the categories and tool metadata from Guance to the local cache directory.

The following scenarios require re-executing owl sync:

• After the first installation
• The platform has released new tools
• The platform has updated the parameters or descriptions of existing tools
• Need to refresh the local cache content

Common sync and cache commands:

Version Update Notices¶

When an update channel was configured by the installer, owl exec checks for a newer release at most once every 24 hours. If one is available, JSON results include an additional notice field; existing fields such as success, output, and file remain unchanged. A failed update check never blocks tool execution.

Upgrade through the configured channel with:

owl update

To disable automatic checks, set update.check: false in the configuration file. Installations without an update channel do not perform the check or emit a notice.

Data Result Files¶

When the output type defined by the tool is data, OWL CLI automatically saves the result file to the local data/ directory and records the file index and structure information. Starting with 1.2.1, new files use 22-character URL-safe random IDs, making them easier for agents to reference and reducing long-file-name risks. The stable queryKey and existing index format remain unchanged.

The JSON result from owl exec contains file.path, absolutePath, format, and size, but not the data-file id. Do not derive or guess an ID from a path. To obtain the authoritative ID, run owl data list -f json, identify the matching entry, capture its files[].id, and pass that exact value unchanged to owl data show or owl data rm.

Common data file commands:

Schema Output for Agent¶

If you need to connect OWL CLI to 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 connecting to an Agent, it is recommended to run owl sync first to ensure the local Schema is consistent with the current tool directory on the platform.

If the target client supports MCP, prefer using the remote MCP Server connection method 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