CLI Quick Start¶

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

Prerequisites¶

Before you begin, ensure:

1. You have completed either 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 an access token (OWL_TOKEN or OWL_API_KEY), corresponding 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 Owl CLI, you must set them again.

The access token can also be set via OWL_API_KEY. If both OWL_API_KEY and OWL_TOKEN are present, Owl CLI prioritizes OWL_API_KEY.

Method 2: Writing to Local Configuration File¶

owl init
owl login

Execution 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 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 use their values first.

Step 2: Synchronize Tool Catalog¶

Before first use of Owl CLI, you need to synchronize the tool catalog:

owl sync

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

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

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 parameter descriptions for a specific tool:

owl show owl.data.query

Step 4: Execute a Tool¶

Execute 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

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

owl exec owl.data.show_dql_namespace --format 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 --format 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 --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 data can display tools under the data category.
• owl exec owl.data.show_dql_namespace can return the DQL namespaces supported by the current workspace.

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