Skip to content

CLI Quick Start

This document is intended for first-time OWL CLI users. It describes how to configure OWL CLI, sync the tool directory, and execute a tool call.

If you want to use OWL CLI directly in agent conversations such as Codex, Claude Code, Cursor, Trae, GitHub Copilot (VS Code), or Windsurf, first install the CLI and its associated Skills using the unified automatic installation process, then complete the first-call verification. This page describes the manual command workflow; the configuration and sync steps already completed by automatic installation do not need to be repeated.

Prerequisites

Before you begin, confirm the following:

  1. You have completed manual OWL installation or automatic OWL installation
  2. You have obtained the OWL CLI Endpoint corresponding to the site where your Workspace is located. See the Endpoint list
  3. You have obtained the 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 the Endpoint and Access Token

OWL CLI supports setting the Endpoint and access token via environment variables, a local configuration file, or a separate Profile. For first-time use, choose one of the first two methods; use a Profile when you need to store multiple accounts or environments.

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

Method 1: Use 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 only take effect in the current terminal session. If you need to continue using them after closing the terminal, set them again.

This identity override applies to the legacy configuration mode without a selected Profile, or when the deprecated --conf is used alone. If you have previously run owl switch, or set --profile / OWL_PROFILE, OWL uses the Endpoint/Key of the selected Profile. You can use owl profile current to view the current source.

The access token can also be set via OWL_API_KEY; when both OWL_API_KEY and OWL_TOKEN are present, OWL CLI uses OWL_API_KEY.

Method 2: Write to a Local Configuration File

owl init
owl login

Notes:

  • owl init writes the OWL CLI Endpoint
  • owl login writes the access token

When no Profile is selected, the local configuration is written to ${OWL_DIR}/config.yaml, which defaults to ~/.owl/config.yaml. After a Profile is selected, init and login write to the selected configuration.

Identity environment variables take precedence over the configuration file only in legacy configuration mode or when --conf is used alone.

Method 3: Save a Separate Profile

owl profile add customer-a
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl switch customer-a
owl profile current

profile add interactively prompts for the Endpoint and Key. You can also use --from to copy an existing YAML. Adding a Profile only saves its configuration and does not change the current selection; switch saves the default selection for subsequent commands. Each named Profile uses its own configuration, cache, and query file directories.

A single command can temporarily select another configuration without changing the default:

owl --profile customer-b sync
owl --profile customer-b exec owl.data.show_dql_namespace -f json

The selection priority is --profile > OWL_PROFILE > persisted selection. For complete usage, see Using Multiple Profiles.

Step 2: Sync the Tool Directory

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

owl sync

owl sync syncs the metadata of categories and tools currently available in Guance to the local cache. After the sync completes, you can view and execute tools.

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

owl sync -c data

Step 3: View Tools

View all tool categories:

owl category list

View tools in a category:

owl list -c data

View the parameter description of a tool:

owl show owl.data.query

Step 4: Validate Before Execution

Validate a tool call without sending an actual query:

owl validate owl.data.show_dql_namespace -f json

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

Step 5: Execute Tools

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 results:

  • owl sync completes normally without returning authentication or network errors
  • owl category list shows the tool categories
  • owl list -c data shows the 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 issues such as authentication failures, missing tools, or empty results, see Troubleshooting.

Feedback

Is this page helpful?