OWL CLI Tool Inventory¶

This document describes the business tool capabilities currently available for direct execution through OWL CLI, including tool scope, permission types, CLI usage conventions, tool overview, and tool descriptions organized by category.

The visibility and execution results of tools depend on the permissions of the API Key corresponding to the current OWL_TOKEN. If the API Key does not have the necessary resource or operation permissions, the corresponding tool may fail or return empty results.

Tool Scope¶

The tools exposed by OWL CLI are continuously updated with the platform's capabilities. The actual visible tools are determined by the tool directory returned by owl list after running owl sync locally.

This document covers the following business categories:

Permission Types¶

CLI Usage Conventions¶

Sampling Field in Data Result Files¶

When the tool output type is data, the CLI optionally includes a sample field in the execution result while writing the data file:

• sample: A numerical value (float), indicating the sampling ratio of this query (for example, 0.0077 means approximately 0.77% sampling). This field appears only when the backend returns sampling information or the sampling ratio can be parsed from the data file content; if no sampling information is available, this field is omitted.
• When sample is present, it means the results are estimated based on sampled data. When interpreting aggregations such as counts or sums, you need to adjust based on the sampling ratio before assessing the magnitude.

Common CLI command examples:

owl sync
owl list
owl list -c data
owl show owl.data.query
owl exec owl.metric.list --mode source
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

Tool Overview¶

Catalog¶

Used for entity type discovery, entity queries, entity detail retrieval, and topology relationship queries in the unified resource catalog.

Dashboard¶

Used for dashboard creation, replacement, and detail retrieval.

Data¶

For authorized cross-workspace DQL queries, discover targets with owl.workspace.data_authorized.list when needed, then pass workspace_uuids and target_region. Each query targets one site; omitting scope parameters queries the current workspace. See cross-workspace queries for CLI/MCP examples and pagination.

Used for complete data queries and query assistance, covering logs, metrics, RUM, APM, Network, Profile, Billing, and data forwarded to object storage.

limit for owl.data.simple_query_file is an optional integer, range 1 to 10000; when omitted, the backend uses a default value. Values outside this range will be rejected before the request is executed.

Data Forwarding Asynchronous Queries¶

owl.data_forwarding.rule.list, owl.data_forwarding.query.create, and owl.data_forwarding.query.get are used to discover queryable rules and query data that has been written to object storage via rules. These three tools are single atomic calls; the CLI does not automatically select rules, poll tasks, or continue querying the next batch of data. rule.list and query.create directly return text results; query.get has an outputType of data, and each status query writes a new local data file.

Complete a query in the following order:

1. If the user does not have an exact rule name or it is not confirmed whether the rule is queryable, first call owl.data_forwarding.rule.list. Keep queryable_only=true for the query scenario, and select a rule_name from results with queryable=true; do not pass rule_uuid to create.
2. Call owl.data_forwarding.query.create, passing the selected rule_name, query time range, and filter conditions as-is, and obtain the task_id.
3. Use that task_id to call owl.data_forwarding.query.get. The file object in its execution result does not contain the data file ID: run owl data list -f json, find the corresponding entry, save files[].id as-is, then run owl data show <file-id>. Do not derive or guess the ID from the path.
4. Check task_status in the file. If the value is created or running, the task is not yet complete; even if items is empty, it should not be treated as the final result. Continue to call get with the same task_id later, then repeat the data file list step to view the latest status.
5. Stop polling when task_status is completed or failed. When completed, read the redacted items; when failed, troubleshoot based on the returned failure information.
6. When completed and next_token is not empty, call create again to query the next batch. You must keep the original rule_name, start_time, end_time, search, and page_size, and pass next_token as the token parameter. The new create will return a new task_id.

Discover queryable rules:

owl exec owl.data_forwarding.rule.list -p '{
  "queryable_only": true,
  "page_index": 1,
  "page_size": 20
}'

Create the first batch query task:

owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20
}'

Query task status and results:

owl exec owl.data_forwarding.query.get -p '{"task_id":"task_xxx"}'
owl data list -f json
owl data show <saved-file-id>

Query the next batch, reusing the original query parameters and passing next_token:

owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20,
  "token": "next_xxx"
}'

Parameters and Limitations:

• rule.list defaults to queryable_only=true, returning only queryable rules. When set to false, it also returns rules that do not support queries; you should determine the reason via queryable and unsupported_reason and cannot continue to call create to query these rules.
• rule.list supports fuzzy search for rule names via search, and can also filter by data_type or store_type; pagination range is page_index >= 1, page_size 1 to 100.
• rule_name must use the exact value returned by rule.list and cannot be replaced with rule_uuid. Data type and object storage configuration are determined by the backend based on the rule.
• start_time and end_time are 13-digit millisecond timestamps, and end_time must be greater than start_time.
• The maximum query duration is determined by the workspace configuration, defaulting to 24 hours; query_time_limit_hours in the create response is the currently effective limit.
• search.conditions[].logic only supports match and notMatch; multiple conditions are combined via search.operator using and or or.
• page_size range is 1 to 1000, default 20.
• query.get does not directly print the complete results to the CLI; its returned file information does not contain the ID. Run owl data list -f json, save the files[].id of the corresponding entry as-is, then use owl data show <file-id> to view the task status and redacted results.
• DF-API-KEY is automatically injected by the CLI and should not be passed as a tool parameter. Free Plan workspaces do not support this query.
• Supports S3, OSS, OBS, GCS, and TOS standard storage; does not support Kafka, platform built-in storage, cold storage, or archive data.

Cross-Workspace Trace Query within the Same Organization¶

Query the current workspace directly. For other workspaces in the same organization, discover candidates with owl.account.workspace.same_org.list (CLI: owl workspace same-org list) only when target UUIDs are unknown. Pass returned workspace_uuid values to owl.data.same_org.trace.query; workspace_id is only for list pagination.

• trace_id is a required parameter; the server will forcefully add this condition, so do not repeat it in where_clause.
• workspace_uuids is an optional string array; use the workspace_uuid from the list results; workspace_id is only used for list pagination and cannot be used for queries.
• When workspace_uuids is omitted or an empty array, only the workspace to which the current API Key belongs is queried.
• When the cross-workspace query feature within the same organization is disabled, only the current workspace can be queried; passing UUIDs of other workspaces will return a parameter error.
• where_clause only passes additional DQL condition fragments, without outer curly braces.
• start_time and end_time use 13-digit millisecond timestamps; you can also narrow the query scope via source and limit.
• The returned content retains the original DQL query result structure. Do not fall back to owl.data.query or owl.data.simple_query_file for cross-workspace Trace queries.

owl workspace same-org list
owl exec owl.data.same_org.trace.query -p '{"trace_id":"TRACE-XXXX","workspace_uuids":["wksp_xxx"]}'

Errors¶

Used for querying the error center issue list, as well as adding, querying, and updating comments.

Event¶

Used for querying the event center list and retrieving event details.

• owl.event.list must provide start_time and end_time; status optional values are fatal, critical, error, warning, and nodata; limit defaults to 20, maximum 100; returned items may include the event dimension tag field df_dimension_tags.
• timeRange for owl.event.get is an optional two-element array [start, end], both elements are 13-digit millisecond timestamps, and end must be greater than start. The parameter name is timeRange, do not change it to time_range.

Incident¶

owl.incident.get accepts an incident UUID (incident_*) and returns details with related_event_refs. The default and maximum page size are both 100. Follow page_info.has_more and next_page_index, then call owl.event.get using event references, not the incident UUID. The available reference count can differ from the incident-reported event count; report any missing evidence.

Infrastructure¶

Used for querying the infrastructure object list and details, covering resource objects such as hosts, containers, and processes.

LLM¶

Used for querying the LLM observability application list.

Workspace¶

Authorized cross-workspace data discovery and current workspace members.

The new workspace category contains owl.workspace.data_authorized.list and owl.workspace.member.list. The old member category is removed. owl.member.list remains a callable alias with the same parameters and permission checks, but is not listed as a separate tool.

Monitor¶

Used for querying the monitor list, retrieving details, creating or updating monitors, and receiving external events.

Notes and Runbooks¶

Used for managing regular notes and Runbooks visible to the current API Key account. Regular notes are suitable for recording conclusions and reference information, while Runbooks are suitable for storing reusable operational procedures.

• page_index for owl.nbook_note.list defaults to 1, page_size defaults to 20, maximum 100.
• type for owl.nbook_note.list optional values are normal and runbook; when omitted, both types are returned.
• owl.nbook_note.get is the only tool that returns the Markdown body content, but does not return path, etag, or version; list, add, and modify only return basic information such as title, type, and tags, and also do not return content, path, ETag, or version information; delete returns a minimal result of the delete operation.
• owl.nbook_note.add requires title and content; type optional values are normal and runbook, when omitted, a regular note is created. This tool does not accept path; created_source is always set to ai by the server, and the creator account is taken from the current API Key.
• owl.nbook_note.modify must provide at least one of title, content, tags, or tag_kv in addition to note_uuid; when content is omitted, the original body is retained.
• Content type cannot be changed after creation; get, modify, and delete do not accept type. To change the type, recreate it with the target type.
• Getting, modifying, and deleting all use the note_uuid returned by the list. Do not pass fields managed by the backend such as path, etag, if_match, version, creator, or created_source.
• tagkv_query is a TagKV expression string used by the list tool; tag_kv is a key-value object used by the create and modify tools; do not confuse them.

Pipeline¶

Used for querying the Pipeline list and validating samples.

mdsearch¶

Used for searching the unified document library, reading single documents, and browsing the catalog, supporting queries in Chinese, English, and mixed languages.

CLI Usage Paths¶

Data Query Problems¶

Applicable to problems such as "querying metrics, logs, RUM, APM, Network, Profile, Billing data".

1. First, execute owl.data.show_dql_namespace to confirm the target namespace;

2. Call discovery tools by data domain:

   • Metrics: owl.metric.list
   • RUM: owl.rum.list
   • APM: owl.apm.list
   • Network: owl.network.list
   • Profile: owl.profile.list
   • Logging: owl.logging.list
   • Billing: owl.billing.list
   • Log indices: owl.log_index.list
   • Field catalog: owl.field_schema.get

3. When DQL syntax needs to be confirmed, first call owl.data.search_dql_docs to look up documentation;

4. After writing a complete DQL, first call owl.data.check_dql for local validation;
5. Finally, call owl.data.query to execute the formal query.

Profiling Analysis Problems¶

Applicable to problems such as "already have a profile_id, want to view the summary or parse detailed stack information".

1. First, locate the target profile_id in the Profiling data domain via owl.data.query;
2. Call owl.profiling.get_summary to get summary information;
3. Reuse the language, type, profile_start, profile_end from the summary result, then call owl.profiling.parse to parse the detailed content.

Incident Troubleshooting Problems¶

Applicable to problems such as "querying incidents, tracking the handling process, adding comments".

1. If the incident UUID is known, call owl.incident.get; otherwise find it with owl.incident.list first.
2. Read all pages of related event references, then call owl.event.get for event content.
3. Use owl.incident_comment.list for comments and owl.incident_operation.list for operation records.
4. Call owl.incident_comment.add when a progress update is needed.

Dashboard Management Problems¶

Applicable to problems such as "creating a dashboard, replacing dashboard content, viewing existing dashboard configuration".

1. When creating a new dashboard, call owl.dashboard.create;
2. When replacing an existing dashboard, call owl.dashboard.replace;
3. When needing to view the current configuration, call owl.dashboard.get.

Note and Runbook Management Problems¶

Applicable to problems such as "searching, reading, creating, modifying, or deleting regular notes and Runbooks".

1. First, call owl.nbook_note.list to search for content and get the note_uuid; to narrow the scope, filter by type=normal or type=runbook;
2. When needing to read the Markdown body, call owl.nbook_note.get;
3. When creating a note, call owl.nbook_note.add, using type to create normal or runbook; when updating, call owl.nbook_note.modify; the type of an existing note cannot be changed;
4. When deleting, call owl.nbook_note.delete; before performing write operations, confirm the target note or Runbook and its impact scope.

Monitor Management Problems¶

Applicable to problems such as "viewing monitors, creating monitors, updating monitors, sending test events".

1. First, call owl.monitor.list to browse the target monitors;
2. When needing details, call owl.monitor.get;
3. When creating or updating, call owl.monitor.upsert;
4. When needing to send an external event to verify the receiving chain, call owl.monitor.receive.