Skip to content

CLI Quick Start

This document is for users who are using OWL CLI for the first time. It introduces how to configure OWL CLI, sync the tool directory, and execute a tool call.

Prerequisites

Before starting, please confirm:

  1. Completed Manual Installation of OWL or Automatic Installation of OWL
  2. Obtained the OWL CLI Endpoint corresponding to the site of your workspace. Refer to Endpoint List
  3. Obtained the access token OWL_TOKEN or OWL_API_KEY, corresponding to DF-API-KEY
  4. The 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 only needs 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 in the current terminal session. After closing the terminal, you need to set them again to continue using.

The access token can also be set via OWL_API_KEY. When both OWL_API_KEY and OWL_TOKEN exist, OWL CLI uses OWL_API_KEY as the priority.

Method 2: Writing to 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

Local configuration is written to the OWL CLI configuration directory, and subsequent sessions in new terminals can also use it.

Environment variables take precedence over the configuration file. If environment variables are already set in the current terminal, OWL CLI will use the values from the environment variables first.

Step 2: Sync Tool Directory

Before using OWL CLI for the first time, you need to sync the tool directory:

owl sync

owl sync will sync the metadata of currently available categories and tools from TrueWatch to the local cache. After syncing, you can view and execute tools.

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

owl sync -c data

Step 3: View Tools

View all tool categories:

owl category list

View tools under a specific category:

owl list -c data

View the parameter description of a specific tool:

owl show owl.data.query

Step 4: 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, you can specify 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 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 exec owl.data.show_dql_namespace -f json

Success Criteria

After completing the quick start, the following results should be achieved:

  • owl sync completes successfully without authentication or network errors
  • owl category list shows tool categories
  • owl list -c data shows tools under the data category
  • owl exec owl.data.show_dql_namespace returns the DQL namespaces supported by the current workspace

If you encounter authentication failures, tool not found, empty results, or other issues, please refer to Troubleshooting.