Skip to content

CLI Quick Start

This document is intended for first-time users of the OWL CLI. It explains how to complete OWL CLI configuration, sync the tool catalog, and execute a tool call.

Prerequisites

Before you begin, confirm the following:

  1. Have completed Manual OWL Installation or Automatic OWL Installation
  2. Have obtained the OWL CLI Endpoint corresponding to the site of your Workspace. See the Endpoint List
  3. Have obtained the access token OWL_TOKEN or OWL_API_KEY, which corresponds to DF-API-KEY
  4. Your current terminal can access the OWL CLI Endpoint

Step 1: Configure Endpoint and Access Token

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

For OWL_REGISTRY_ENDPOINT, enter only the Endpoint base 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 apply to the current terminal session. After you close the terminal, you must set them again to continue using the CLI.

This identity override applies to the legacy configuration mode where no Profile is selected, or to the standalone use of the deprecated --conf. If you have previously run owl switch, or have 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, the OWL CLI gives precedence to 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 back 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, and you can also use --from to copy an existing YAML. Adding a profile only saves the configuration and does not change the current selection; switch saves the default selection for subsequent commands. Each named Profile uses separate configuration, cache, and query file directories.

You can temporarily select another configuration for a single command 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 > the persisted selection. For complete usage, see Using Multiple Profiles.

Step 2: Sync the Tool Catalog

Before your first use of the OWL CLI, you need to sync the tool catalog:

owl sync

owl sync syncs the currently available categories and tool metadata from TrueWatch to the local cache. Only after the sync completes can you view and execute tools.

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

owl sync -c data

Step 3: View Tools

View all tool categories:

owl category list

View the tools in a category:

owl list -c data

View a tool's parameter descriptions:

owl show owl.data.query

Step 4: Validate Before Execution

Validate the tool call without issuing 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 be able to achieve the following results:

  • owl sync completes normally without authentication or network errors
  • owl category list shows the tool categories
  • owl list -c data shows the tools in 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.