Lightdash AI CLI (@lightdash-tools/cli)

Command-line interface for interacting with the Lightdash API.

Installation

You can run the CLI directly without installation using npx:

npx @lightdash-tools/cli --help

Or install it globally:

npm install -g @lightdash-tools/cli

Usage

Environment Variables

The CLI requires the following environment variables (consistent with @lightdash-tools/client):

• LIGHTDASH_URL - Lightdash server base URL (e.g., https://app.lightdash.cloud)
• LIGHTDASH_API_KEY - Personal access token (PAT)
• LIGHTDASH_PROXY_AUTHORIZATION - Optional proxy authorization header
• LIGHTDASH_TOOLS_SAFETY_MODE - Optional safety mode (read-only, write-idempotent, write-destructive)
• LIGHTDASH_TOOLS_ALLOWED_PROJECTS - Optional comma-separated project UUIDs (restrict operations to these projects; empty = all allowed)
• LIGHTDASH_TOOLS_DRY_RUN - Set to 1, true, or yes to simulate mutating operations without executing

Prefer env vars from the parent process. Avoid plaintext .env when AI agents have file access. If using .env, use dotenvx for encrypted secrets. See docs/secrets-and-credentials.md.

Example:

export LIGHTDASH_URL=https://app.lightdash.cloud
export LIGHTDASH_API_KEY=your-token-here

Commands

The CLI provides subcommands grouped by domain. All commands output JSON by default. If you are using npx, replace lightdash-ai with npx @lightdash-tools/cli.

Organization

# Get current organization details
lightdash-ai organization get

# Manage organization roles (v2)
lightdash-ai organization roles list
lightdash-ai organization roles get <roleUuid>
lightdash-ai organization roles assign <userUuid> --role <roleUuid>

Projects

# List all projects
lightdash-ai projects list

# Get specific project details
lightdash-ai projects get <projectUuid>

# Project validation
lightdash-ai projects validate run <projectUuid>
lightdash-ai projects validate results <projectUuid>

# Manage project role assignments (v2)
lightdash-ai projects roles list <projectUuid>
lightdash-ai projects roles assign --project <projectUuid> --user <userUuid> --role <roleUuid>

# Manage project access (v1)
lightdash-ai projects access list <projectUuid>

Content (Charts, Dashboards, Spaces)

# List charts in a project
lightdash-ai projects charts list <projectUuid>

# List dashboards in a project
lightdash-ai projects dashboards list <projectUuid>

# List spaces in a project
lightdash-ai projects spaces list <projectUuid>

# Search project content (v2)
lightdash-ai content search "query"

Charts as Code

# Get charts in code representation
lightdash-ai projects charts code list <projectUuid> --ids <slugs...>

# Upsert a chart from its code representation
lightdash-ai projects charts code upsert <projectUuid> <slug> --file <chart.json>

Explores (Project-level)

lightdash-ai projects explores list <projectUuid>
lightdash-ai projects explores get <projectUuid> <exploreId>

Users & Groups

# Organization members
lightdash-ai users list
lightdash-ai users get <userUuid>

# Groups
lightdash-ai groups list
lightdash-ai groups get <groupUuid>
lightdash-ai groups create "Group Name"

Metrics & Schedulers

# Metrics catalog
lightdash-ai metrics list <projectUuid>
lightdash-ai metrics get <projectUuid> <tableName> <metricName>

# Scheduled deliveries
lightdash-ai schedulers list <projectUuid>
lightdash-ai schedulers get <schedulerUuid>

Tags

lightdash-ai tags list <projectUuid>
lightdash-ai tags get <projectUuid> <tagUuid>

Query

# Compile a metric query
lightdash-ai query compile <projectUuid> <exploreId> --file <query.json>

AI Agents

# List AI agents
lightdash-ai ai-agents list

# List agent threads (admin)
lightdash-ai ai-agents threads --page 1 --page-size 10

Schema Introspection (Agent-Friendly)

# List all introspectable resources
lightdash-ai schema list

# Get schema for a resource (path, method, params)
lightdash-ai schema get charts.list
lightdash-ai schema get ai-agents.settings.update

Global Options

• --safety-mode <mode> - Override safety mode (read-only, write-idempotent, write-destructive)
• --projects <uuids> - Comma-separated list of allowed project UUIDs
• --dry-run - Simulate mutating operations without executing (same as LIGHTDASH_TOOLS_DRY_RUN=1)

Help

Get help for any command:

lightdash-ai --help
lightdash-ai projects --help
lightdash-ai projects charts --help
lightdash-ai projects charts code --help

Output Format

All commands output JSON by default, formatted with 2-space indentation.

Safety Modes

The CLI implements a hierarchical safety model to prevent accidental destructive operations. This is the same model used by the Lightdash MCP server.

Configuration

You can control the safety mode via the LIGHTDASH_TOOLS_SAFETY_MODE environment variable or the global --safety-mode flag.

• read-only (default): Only allows non-modifying operations (e.g., list, get).
• write-idempotent: Allows read operations and non-destructive writes (e.g., upsert, validate run).
• write-destructive: Allows all operations, including deletions.

Enforcement

The CLI uses Dynamic Enforcement: all commands remain visible in help, but if you attempt to execute a command that is forbidden in the current mode, the CLI will exit with an error message.

Example:

# This will work
lightdash-ai --safety-mode read-only users list

# This will fail if delete was implemented
lightdash-ai --safety-mode read-only users delete <uuid>

When a command is blocked, you will see an error like: Error: This command is disabled in read-only mode. To enable it, use --safety-mode or set LIGHTDASH_TOOLS_SAFETY_MODE.

Input Validation

The CLI validates all resource IDs (project UUIDs, slugs) before executing. Invalid inputs are rejected:

• Control characters (ASCII < 0x20)
• Query/fragment chars (?, #, %)
• Path traversal (..)

This guards against adversarial or hallucinated inputs when used by AI agents. See docs/agent-context/CONTEXT.md for agent-specific guidance.

Error Handling

The CLI provides helpful error messages for:

• Missing environment variables
• API errors
• Missing command arguments

Development

If you are developing the CLI itself:

1. Install dependencies: pnpm install
2. Build: pnpm build
3. Run tests: pnpm test
4. Run locally: node dist/index.js

License

Apache-2.0