CLI Commands¶

This document introduces the common commands of OWL CLI, including configuration and authentication, tool directory synchronization, tool viewing and execution, cache management, data file management, and Schema output for Agent.

Configuration and Authentication¶

OWL CLI uses the following common configurations:

Configuration Item	Description
`OWL_REGISTRY_ENDPOINT`	The OWL CLI Endpoint corresponding to the site of the workspace
`OWL_TOKEN`	Service access token, used to identify the caller, corresponding to DF-API-KEY
`OWL_API_KEY`	Alias environment variable for the service access token, equivalent to `OWL_TOKEN`
`OWL_DIR`	Override the default configuration/cache/data root directory, default `$HOME/.owl`, supports `~` expansion

Common commands:

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

Command	Description
`owl init`	Write OWL CLI Endpoint
`owl login`	Write access token
`owl config show`	View current configuration
`owl config set <configuration_item> <value>`	Modify the specified configuration item
`owl workspace list`	Get the list of available workspaces under the current account, output the name and `workspace_uuid` of each workspace
`owl workspace use <workspace_uuid>`	Switch to the specified workspace, automatically fetch the access key from the cloud and write it to the local configuration; subsequent `owl sync`, `owl exec` and other commands will use this workspace identity
`owl workspace current`	Show the current workspace context
`owl workspace key get <workspace_uuid\\|workspace_name>`	Get the access key of the specified workspace (masked by default, add `--show-secret` to output the original key)
`owl workspace profile list`	List local workspace profiles
`owl workspace profile current`	Show the current local workspace profile
`owl workspace profile use <profile_name>`	Switch the current local workspace profile
`owl workspace same-org list`	List workspaces in the same organization (see details below)

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:

Flag	Description
`--page-size <n>`	Number of items per page, value 1-100, default 20; an error will be reported if out of range
`--before-id <id>`	Pagination cursor, only returns workspaces with id less than this value; the cursor value is returned by the server and cannot be inferred by array index
`--uuid <uuid>`	Filter by `workspace_uuid`, can be passed multiple times
`--all`	Follow the server-returned cursor to automatically paginate and return all pages

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

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

Configuration File and Priority¶

Default configuration file paths:

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

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:

Environment variables
config.yaml

Cache and Synchronization¶

owl sync syncs the categories and tool metadata from TrueWatch 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:

Command	Description
`owl sync`	Sync all categories and tools
`owl sync -c <category_id>`	Sync only the specified category
`owl cache status`	View cache status
`owl cache clear`	Clear all cache
`owl cache clear -c <category_id>`	Clear the cache of the specified category

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.

Common data file commands:

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

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