Skip to main content

CLI Reference

This page provides a comprehensive reference for all Wvlet CLI commands.

note

The wv command is a shortcut available in the REPL environment. For all other contexts, use the full wvlet command.

Global Options​

These options can be used with any command:

wvlet [global options] <command> [command options]
OptionDescription
-h, --helpDisplay help message
--versionDisplay version
--debugEnable debug logging
-l <level>Set log level (ERROR, WARN, INFO, DEBUG, TRACE)
-L <pattern>=<level>Set log level for specific class patterns
--profile <name>Use a specific connection profile
-w <path>Set working directory

Commands​

wvlet compile​

Compile Wvlet queries to SQL.

wvlet compile [options] [query]

Options:

OptionDescription
-f, --file <path>Compile queries from a file
-t, --target <type>Target database type (duckdb, trino)
--catalog <name>Use specific catalog
--schema <name>Use specific schema
--strictFail compilation on typing errors

Examples:

# Compile inline query
wvlet compile "from users select * limit 10"

# Compile from file
wvlet compile -f queries/analysis.wv

# Compile for specific target
wvlet compile -f query.wv --target trino

wvlet catalog import​

Import database table schemas as Wvlet type definitions, and engine functions as Wvlet function definitions, for offline query validation. See Importing Database Catalogs.

wvlet catalog import [options]

Options:

OptionDescription
--profile <name>Profile to connect with
--catalog <name>Catalog to import (default: profile catalog)
--schema <name>Import only the specified schema
--path <folder>Output folder (default: catalog)
--no-functionsSkip importing engine functions

Examples:

# Import all schemas of the profile's catalog
wvlet catalog import --profile production

# Import a single schema
wvlet catalog import --profile production --schema sales

wvlet run​

Run Wvlet queries and display results.

wvlet run [options] [query]

Options:

OptionDescription
-f, --file <path>Run queries from a file
-t, --target <type>Target database type
--catalog <name>Use specific catalog
--schema <name>Use specific schema
--format <type>Output format (table, json, csv, tsv)
--limit <n>Limit result rows

Examples:

# Run inline query
wvlet run "from users select count(*)"

# Run from file
wvlet run -f queries/report.wv

# Run with specific format
wvlet run -f query.wv --format json

# Run with row limit
wvlet run "from large_table select *" --limit 1000

wvlet ui​

Start the Wvlet Web UI server.

wvlet ui [options]

Options:

OptionDescription
-p, --port <port>Server port (default: 8080)
--host <host>Server host (default: localhost)
--no-browserDon't open browser automatically

Examples:

# Start UI on default port
wvlet ui

# Start on custom port
wvlet ui --port 9000

# Start without opening browser
wvlet ui --no-browser

Configuration​

Profile Configuration​

Create profiles in ~/.wvlet/profiles.json (parsed as JSONC: comments and trailing commas are allowed, and ${ENV_VAR} references are expanded from the environment). A profile describes a working environment with one or more named connectors; the connector marked "default": true (or the first one) is the engine queries run on:

{
  "profiles": [
    {
      "name": "local",
      "connectors": [
        { "name": "duckdb", "type": "duckdb", "catalog": "memory", "schema": "main" }
      ]
    },
    {
      "name": "production",
      "connectors": [
        {
          "name": "trino",
          "type": "trino",
          "default": true,
          "host": "trino.example.com:8080",
          "catalog": "production",
          "schema": "analytics",
          "user": "myuser",
          "password": "${TRINO_PASSWORD}"
        },
        { "name": "local", "type": "duckdb", "catalog": "memory", "schema": "main" }
      ]
    }
  ]
}

Use profiles with --profile option:

wvlet run -f query.wv --profile production

Environment Variables​

VariableDescription
WVLET_HOMEWvlet home directory (default: ~/.wvlet)
WVLET_LOG_LEVELDefault log level
WVLET_DB_TYPEDefault database type

Command Shortcuts​

The wv command is a shortcut for the Wvlet REPL:

# Start REPL
wv

# Run REPL command
wv "from users select count(*)"

# Access other wvlet commands through wv
wv compile -f query.wv

Examples​

Typical Development Workflow​

# 1. Write and test queries
wvlet compile -f query.wv

# 2. Run queries against database
wvlet run -f query.wv

# 3. Start UI for interactive development
wvlet ui

CI/CD Pipeline Example​

#!/bin/bash
# ci-validate-queries.sh

# Validate query syntax
find queries -name "*.wv" | while read file; do
  echo "Validating: $file"
  wvlet compile -f "$file"
done

Batch Processing Example​

# Process multiple queries
for query in daily/*.wv; do
  output="${query%.wv}.sql"
  wvlet compile -f "$query" > "$output"
  echo "Generated: $output"
done

# Run all reports
for report in reports/*.wv; do
  name=$(basename "$report" .wv)
  wvlet run -f "$report" --format csv > "output/${name}.csv"
done

See Also​