Skip to content

CLI Quick Start

This document is intended for users who are using the OWL CLI for the first time. It describes how to complete OWL CLI configuration, synchronize the tool catalog, and execute a tool call.

Prerequisites

Before you begin, ensure:

  1. You have completed Manual OWL Installation or Automatic OWL Installation
  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 or OWL_API_KEY, which corresponds to DF-API-KEY
  4. The current terminal can reach 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 any other path.

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 in the current terminal session. After closing the terminal, you need to set them again to continue using the CLI.

The access token can also be set via OWL_API_KEY. When both OWL_API_KEY and OWL_TOKEN are present, the OWL CLI will use OWL_API_KEY.

Method 2: Writing to a Local Configuration File

owl init
owl login

Explanation:

  • 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, so it can be used in subsequent terminal sessions.

Environment variables take precedence over the configuration file. If environment variables are set in the current terminal, the OWL CLI will use 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 will synchronize the metadata of categories and tools currently available in TrueWatch to the local cache. After synchronization, you can view and execute tools.

To synchronize only a specific category, use the -c flag:

owl sync -c data

Step 3: View Tools

List all tool categories:

owl category list

List tools under a specific category:

owl list -c data

View the parameters of a specific tool:

owl show owl.data.query

Step 4: Validate Before Execution

Validate a tool invocation without making an actual query:

owl validate owl.data.show_dql_namespace -f json

The valid field in the result should be true, and request_executed should be false. If the current CLI does not support validate, upgrade to version 1.2.0 or later.

Step 5: Execute a Tool

Run the following command to view the DQL namespaces supported by the current workspace (this is the first step before using owl.data.query):

owl exec owl.data.show_dql_namespace

For machine-readable output, specify the JSON format:

owl exec owl.data.show_dql_namespace -f json

Complete Example

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

owl sync
owl category list
owl list -c data
owl show owl.data.query
owl validate owl.data.show_dql_namespace -f json
owl exec owl.data.show_dql_namespace -f json

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

owl sync
owl category list
owl list -c data
owl show owl.data.query
owl validate owl.data.show_dql_namespace -f json
owl exec owl.data.show_dql_namespace -f json

Success Criteria

After completing the Quick Start, you should achieve the following:

  • owl sync completes successfully without authentication or network errors
  • owl category list displays tool categories
  • owl list -c data shows tools under the data category
  • owl validate owl.data.show_dql_namespace -f json returns valid: true and request_executed: false
  • owl exec owl.data.show_dql_namespace returns the DQL namespaces supported by the current workspace

If you encounter authentication failures, missing tools, empty results, or other issues, please refer to Troubleshooting.