CLI Commands¶

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

Command-line Completion¶

Bash¶

Supports Bash 3.2 and Bash 4/5, for Linux, macOS, Windows Git Bash, and WSL. Use the Linux version of OWL in WSL; in Git Bash, use the Windows version owl.exe, which can be invoked as owl or owl.exe.

First install and load bash-completion compatible with your Bash version. Bash 3.2 uses a compatible 1.x version; Bash 4/5 uses the corresponding 2.x version. Enable OWL completion in the current terminal:

eval "$(owl completion bash)"

For permanent enablement, place the same line in ~/.bashrc after the code that loads bash-completion. If your login terminal only reads ~/.bash_profile, make sure it loads ~/.bashrc. Configure this only once; do not append it repeatedly.

eval is used here to load the script generated by OWL, avoiding the issue where source <(...) silently fails to load in some macOS Bash 3.2 environments. You can also save the script to a file as described below and then source it.

The installation script still writes the generated completion script to ~/.local/share/bash-completion/completions/owl. If your current bash-completion automatically loads this directory, you do not need to configure the startup command above. After updating OWL, the existing static completion file needs to be regenerated:

mkdir -p ~/.local/share/bash-completion/completions
owl completion bash > ~/.local/share/bash-completion/completions/owl
source ~/.local/share/bash-completion/completions/owl

PowerShell¶

Windows PowerShell 5.1 and PowerShell 7 use dedicated completion scripts that share the same local tool candidate logic. Enable completion in the current terminal:

owl completion powershell | Out-String | Invoke-Expression

For permanent enablement, add this line to $PROFILE. Existing Windows installation scripts already generate Completions\owl.ps1 and load it in the $PROFILE used at installation time; users who have already configured this do not need to add it again. Different PowerShell versions or hosts may use different profiles, so enable it in the terminal you actually use.

CMD is not supported for command completion.

Completion Content and Cache¶

First synchronize tool definitions with a normal command:

owl sync

In the following examples, <Tab> indicates pressing the Tab key:

owl exec owl.met<Tab>                   → owl.metric.list
owl exec owl.metric.list --mo<Tab>      → --mode
owl exec owl.metric.list mo<Tab>        → mode=
owl exec owl.metric.list --mode s<Tab>  → source
owl exec owl.metric.list --mode=s<Tab>  → --mode=source
owl exec owl.metric.list mode=s<Tab>    → mode=source

• Pressing Tab directly after a tool name lists --parameter-name by default; entering a plain name prefix lists parameter-name=.
• exec, validate, and the corresponding tool/tools entry points are supported; show supports tool name completion, --category supports category completion, and --format supports format completion.
• Parameter values come from string, numeric, or boolean enums in the schema. Boolean parameters suggest true/false. Free text, arrays, objects, and JSON content after -p/--params are not completed.
• Tool parameters that have already been entered are not suggested again. Real-time business data such as workspaces, metric sources, and fields is not queried.
• Tab only reads the local cache selected by the current configuration. It does not access the network, execute tools, read standard input, write configuration, or migrate old caches. OWL_DIR and --conf before the command can select the configuration and cache.
• Profile aliases support owl switch <Tab>, owl profile rename/remove <Tab>, owl --profile <Tab>, and options before tool names such as owl exec --profile=<Tab>. New aliases created and new names for rename are entered by the user without file prompts; profile add --from retains configuration file completion.
• Tool candidates follow the configuration and cache isolation of the current Profile: --profile, OWL_PROFILE, and the switched default Profile all take effect. owl exec --profile <name> <tool-name> is also supported; --profile after the tool name is still a tool parameter.
• When the cache is empty or the configuration cannot be read, base commands and fixed options can still be completed. Tool definition completion becomes available after a successful owl sync. No need to reload the completion script after synchronization.

If Bash reports _get_comp_words_by_ref: command not found, bash-completion has not been loaded. If only tool name or parameter candidates are missing, first confirm that owl list and owl show <tool-name> can read tool definitions under the current configuration, then run owl sync to update the cache.

If you just built from source, first use command -v owl to confirm that the current terminal invokes the new version. make build only produces build/owl and does not overwrite an existing installation; loading the completion script does not replace the executable either. From the repository root, run export PATH="$PWD/build:$PATH" and hash -r, then run the enable command. You can use complete -p owl to check whether Bash has registered completion.

Configuration and Authentication¶

The OWL CLI uses the following common configuration:

Common commands:

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

You can save multiple independent configurations and select them by alias:

owl profile add customer-a
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl switch customer-a
owl --profile customer-b exec owl.data.show_dql_namespace
owl profile current -f json

Adding a new profile does not switch to it automatically. Once a Profile takes effect, the entire set of Endpoint and Key comes from its file and is not overridden by legacy identity environment variables. For complete commands, isolation rules, rename, and removal behavior, see Using Multiple Profiles.

The CLI's --conf <path> is deprecated and hidden from help. During the compatibility period, it still reads and writes the specified file and retains environment variable overrides; passing it together with --profile produces an error. It is recommended to import with profile add <alias> --from <path> and then use --profile. The Registry's --config remains available.

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

owl config set registry.insecure_skip_verify true
# or apply it only to the current process
export OWL_REGISTRY_INSECURE_SKIP_VERIFY=true

This setting defaults to false. When enabled, OWL cannot verify the Registry's identity and may be vulnerable to man-in-the-middle attacks; it should not be used in production.

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

When setting an access token, the key names api-key and token are equivalent; writing to either one updates 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:

• Only one page is returned by default. If more results are available, the text output shows More results available. Fetch the next page with --before-id <id>, where <id> is the next page cursor returned by the server.
• With --all, the CLI automatically follows the server-returned cursor to fetch the next page until there are no more results. If the cursor can no longer advance, it stops to avoid an infinite loop against an abnormal 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

OWL_REGISTRY_ENDPOINT, OWL_API_KEY, and OWL_TOKEN take precedence over configuration files only in legacy configuration mode without a selected Profile, or when using the deprecated --conf; OWL_API_KEY takes precedence over OWL_TOKEN. Once a Profile is selected, the entire Endpoint/Key set comes from that Profile.

Categories and the Tool Directory¶

Before viewing categories and tools, it is recommended to run a sync 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 shown in owl list. Before execution, you can view parameter definitions with 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 --start_time 1792548000000 --end_time 1792551600000

The parameter name and value can also be joined with an equals sign, for example owl exec owl.metric.list --mode=source --start_time=1792548000000 --end_time=1792551600000.

Using key=value¶

owl exec owl.metric.list mode=source start_time=1792548000000 end_time=1792551600000

Using -p to Pass JSON¶

owl exec owl.metric.list -p '{"mode":"source","start_time":1792548000000,"end_time":1792551600000}'

Reading JSON from Standard Input¶

echo '{"mode":"source","start_time":1792548000000,"end_time":1792551600000}' | owl exec owl.metric.list --stdin

Execution Rules¶

When executing a tool, note that:

• 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
• The visibility of returned results depends on the permissions of the API Key corresponding to OWL_TOKEN
• For DQL query response field definitions, see Response Fields.

Example: Query Metric Sources¶

owl show owl.metric.list
owl exec owl.metric.list --mode source --start_time 1792548000000 --end_time 1792551600000

Example: Query Event Lists¶

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 with 1.2.0, you can use owl validate to validate a tool invocation before actual 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. It does not execute the target tool:

owl validate owl.metric.list --mode source --start_time 1792548000000 --end_time 1792551600000
owl validate owl.data.query -p '{"dql_namespace":"L","query_text":"L::re(`.*`):(count(*))","query_mode":"dql","start_time":1792548000000,"end_time":1792551600000}' -f json

The JSON result includes:

• valid: whether the invocation passed validation;
• tool: the validated tool name;
• request_executed: always false, confirming that the target tool was not executed;
• issues: a structured list of issues, which may include unknown tools, missing parameters, type errors, unknown parameters, or DQL syntax problems.

When validation fails (valid: false), the command process still exits with status code 0. The Agent must request JSON and parse the result; only run owl exec when valid is true. A non-zero status code means validation did not complete and must not be treated as permission to execute.

For owl.data.query, DQL mode invokes the Registry's DQL validation capability; PromQL mode does not enter the DQL validator. Starting with 1.2.1, owl.data.simple_query and owl.data.simple_query_file also validate the DQL generated from simplified parameters; on failure, generated_dql / dql.builderError is returned, and you should fix select_clause, where_clause, or group_by_clause and retry.

owl exec also performs the same parameter schema validation before the actual request. When the Agent runtime needs to determine whether the current CLI supports preflight checks, run:

owl capabilities -f json

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

Time Validation and Execution Results in v1.6.0¶

v1.6.0 checks that timestamps are 13-digit integer milliseconds and that the end is later than the start. Supply both values when a tool requires a pair. Use each tool's schema for required fields and maximum time spans. The maximum span for owl.data.query is 7 days.

DQL in owl.data.query can omit an inline time window and use start_time / end_time. An inline absolute window must match the external window. Relative windows are rejected. PromQL range selectors specify lookback periods, not query windows, and do not enter DQL validation. The Registry requires an available dqlcheck. It does not execute a DQL query if validation is unavailable. The requested window does not establish the backend's effective window or the time range covered by results.

owl validate continues to report preflight results through valid. A result of valid: false does not change its exit-code rules. A failed parameter preflight in owl exec -f json returns JSON and a non-zero exit code. Correct the arguments in issues before execution.

owl sync returns failure if any category download fails. It keeps the failed category's previous cache and local version. An initial automatic sync failure blocks execution. An automatic sync failure after cache expiry continues to warn and use the existing cache.

Configuration File and Precedence¶

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

When Profile selection is not used, or when the deprecated --conf is used alone, the configuration precedence from highest to lowest is:

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

The Profile selection precedence is --profile > OWL_PROFILE > persisted selection. Once a Profile takes effect, environment overrides for Endpoint/authentication information are ignored; the old root configuration is treated directly as default.

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

Cache and Synchronization¶

owl sync synchronizes the category and tool metadata in TrueWatch to the local cache directory.

You need to run owl sync again in the following scenarios:

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

Common synchronization and cache commands:

Version Update Notification¶

After the update channel is configured with the installer, owl exec checks for new versions at most once every 24 hours. When a new version is found, the JSON result includes an additional notice field, while the existing success, output, and file fields remain unchanged; a failed check does not block tool execution.

You can upgrade according to the current update channel by running:

owl update

To disable automatic checks, set update.check: false in the configuration file. Installations without a configured update channel do not perform checks and do not output notifications.

Data Result Files¶

When the output type of a tool definition is data, the 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 it easier for Agents to reference them and reducing the risk of long file names; the stable queryKey and existing index format remain unchanged.

In the JSON result of owl exec, file only contains path, absolutePath, format, and size; it does not contain the data file id. Do not infer 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 that value as-is to owl data show or owl data rm.

Common data file commands:

Agent-facing Schema Output¶

To integrate the OWL CLI with a custom Agent, export the function-calling Schema:

owl schema

To export only a specified category:

owl schema -c metric

The output of owl schema includes:

• owl_exec: executes any OWL tool uniformly
• owl_list_categories: lists categories
• owl_list_tools: lists tools
• The currently synchronized tool definitions

Before integrating with an Agent, it is recommended to run owl sync first to ensure the local Schema matches the platform's current tool directory.

If the target client supports MCP, prefer connecting via the remote MCP Server described in MCP Server Quick Start.

Help Commands¶

View OWL CLI help:

owl --help

View help for a specified command:

owl help exec
owl help sync
owl help data