Skip to content

CLI Quick Start

This document is intended for first-time users of Owl CLI. It explains how to configure Owl CLI, synchronize the tool catalog, and perform a tool execution.

Prerequisites

Before you begin, please confirm:

  1. You have completed Manual Installation of Owl or Automatic Installation of Owl
  2. You have obtained the Owl CLI Endpoint corresponding to the site of your workspace. Refer to the Endpoint List
  3. You have obtained the access token OWL_TOKEN, which corresponds to DF-API-KEY
  4. Your current terminal can access the Owl CLI Endpoint

Step 1: Configure Endpoint and Access Token

Owl CLI supports setting the Endpoint and access token via environment variables or a local configuration file.

OWL_REGISTRY_ENDPOINT should only contain the root address of the Endpoint. Do not manually append /api/v1 or other paths.

Method 1: Using Environment Variables

export OWL_REGISTRY_ENDPOINT="your-owl-endpoint"
export OWL_TOKEN="your-token"

$env:OWL_REGISTRY_ENDPOINT = "your-owl-endpoint"
$env:OWL_TOKEN = "your-token"

Environment variables are only effective for the current terminal session. If you close the terminal and need to continue using them, you must set them again.

Method 2: Writing to a Local Configuration File

owl init
owl login

Execution Notes:

  • owl init is used to write the Owl CLI Endpoint
  • owl login is used to write the access token

The local configuration is written to the Owl CLI configuration directory and can be used in subsequent new terminal sessions.

Environment variables have higher priority than the configuration file. If environment variables are already set in the current terminal, Owl CLI will prioritize using the values from the environment variables.

Step 2: Synchronize the Tool Catalog

Before using Owl CLI for the first time, you need to synchronize the tool catalog:

owl sync

owl sync synchronizes the currently available categories and tool metadata from TrueWatch to the local cache. After synchronization is complete, you can view and execute tools.

If you only need to synchronize a specific category, you can use -c to specify the category:

owl sync -c metric

Step 3: View Tools

View all tool categories:

owl category list

View tools under a specific category:

owl list -c metric

View the parameter description for a specific tool:

owl show owl.metric.list

Step 4: Execute a Tool

Execute the following command to query the accessible metric sources in the current workspace:

owl exec owl.metric.list --mode source

If machine-readable output is needed, you can specify JSON format:

owl exec owl.metric.list --mode source --format json

Complete Example

export OWL_REGISTRY_ENDPOINT="your-owl-endpoint"
export OWL_TOKEN="your-token"

owl sync
owl category list
owl list -c metric
owl show owl.metric.list
owl exec owl.metric.list --mode source --format json

$env:OWL_REGISTRY_ENDPOINT = "your-owl-endpoint"
$env:OWL_TOKEN = "your-token"

owl sync
owl category list
owl list -c metric
owl show owl.metric.list
owl exec owl.metric.list --mode source --format json

Success Criteria

After completing the quick start, you should achieve the following results:

  • owl sync can complete normally without returning authentication or network errors
  • owl category list can display tool categories
  • owl list -c metric can display tools under the metric category
  • owl exec owl.metric.list --mode source can return the currently accessible metric sources

If you encounter issues such as authentication failure, tool not found, or empty results, please refer to Troubleshooting.