Lightdash CLI

Lightdash CLI tool

How to install

npm i -g @lightdash/cli

Usage

Usage: lightdash [options] [command]

Options:
  -h, --help      display help for command

Commands:
  version         output the version number
  [dbt_command]   runs dbt
  help [command]  display help for command

eg: ligthdash test Runs dbt test

AI agents as code

AI-agent project configuration can be downloaded into lightdash/ai-agents/<slug>.yml and applied to another project:

lightdash download --include-agents
lightdash upload

Use --agents <slugs...> on either command to select specific agents. The files manage the agent name, description, image URL, instructions, semantic tags, data/content/user-context flags, self-improvement flag, model config, and evaluation suites. Evaluation suites are upserted by title; suites omitted from YAML remain unchanged, and evaluation run history is never downloaded. The YAML version identifies the as-code schema, while agentVersion preserves the AI agent runtime version. Access lists, Slack integrations, MCP servers, documents, conversations, and other runtime state stay managed in the target environment.

Data apps as code

Create a new data app locally from the same starter used by Lightdash's data app builder:

lightdash apps create "Revenue explorer"

This requires npm. Before writing anything, the command first warns that it will download packages and run shadcn locally, then asks whether to show and approve the exact direct dependencies and shadcn components. It creates lightdash/apps/revenue-explorer/ with runnable source, the Lightdash data app and local-development agent skills, and a point-in-time snapshot of the selected project's semantic layer. Use --project, --slug, --description, or --path to override the defaults; use --assume-yes to approve installation in a non-interactive environment.

Build and upload it with:

cd lightdash/apps/revenue-explorer
lightdash apps validate --live --build
lightdash upload --apps revenue-explorer

lightdash apps validate [paths...] checks app source, manifests, dependencies, external-connection aliases, and semantic references. It uses the downloaded semantic-layer snapshot by default; --live fetches the project's current explores, and --format json provides CI output. Add --build to run the same bare Vite production build as Lightdash Cloud against the CLI's vendored template. Standard apps need npm install to have populated node_modules; custom dependencies are restored with pnpm install using --frozen-lockfile --ignore-scripts first. Build failures include the Vite output and make validation exit non-zero.

The local build is a pre-flight check; Lightdash rebuilds the source when it is uploaded. Existing apps can still be checked out with lightdash download --apps <slug>.

Development

First build the package

pnpm cli-build

Then run the cli commands with node and pointing to the dist/index.js file

Examples from lightdash root folder

Lightdash login

node ./packages/cli/dist/index.js login http://localhost:3000

Lightdash compile

node ./packages/cli/dist/index.js deploy --project-dir ./examples/full-jaffle-shop-demo/dbt --profiles-dir ./examples/full-jaffle-shop-demo/profiles --use-batched-deploy

Lightdash generate

node ./packages/cli/dist/index.js generate --project-dir ./examples/full-jaffle-shop-demo/dbt --profiles-dir ./examples/full-jaffle-shop-demo/profiles

Lightdash preview

node ./packages/cli/dist/index.js preview --project-dir ./examples/full-jaffle-shop-demo/dbt --profiles-dir ./examples/full-jaffle-shop-demo/profiles

Lightdash run

node ./packages/cli/dist/index.js dbt run --project-dir ./examples/full-jaffle-shop-demo/dbt --profiles-dir ./examples/full-jaffle-shop-demo/profiles -s

Testing different dbt versions

If you want to test different dbt versions, you can replace the string dbt in the "execa" calls in the package with dbt${YOUR_VERSION}, eg: dbt1.8.

Automation, CI & Agentic Usage

The CLI supports non-interactive usage for CI/CD pipelines and agentic LLM coding tools (Claude Code, Cursor, Windsurf, etc.).

The --non-interactive flag is designed for environments where interactive prompts would block execution, such as automated pipelines or when an AI coding agent is running CLI commands on your behalf.

Global Options

| Flag | Description | |------|-------------| | --non-interactive | Disable all interactive prompts. Commands auto-select defaults where possible. Designed for CI/CD and agentic coding tools. |

Command-Specific Options

| Command | Flag | Description | |---------|------|-------------| | login | --token <token> | Authenticate with personal access token (bypasses OAuth) | | login | --email <email> | Login with email and password | | login | --project <uuid> | Select a specific project by UUID after login | | deploy | -y, --assume-yes | Answer yes to all confirmation prompts | | generate | -y, --assume-yes | Answer yes to prompts | | dbt run | -y, --assume-yes | Answer yes to prompts | | rename | -y, --assume-yes | Answer yes to prompts |

Environment Variables

| Variable | Description | |----------|-------------| | CI=true | Equivalent to --non-interactive | | LIGHTDASH_API_KEY | API token for authentication (can be used instead of --token) |

Example Automation Scripts

# Login with token (auto-selects first project in non-interactive mode)
lightdash login https://app.lightdash.cloud \
  --token $LIGHTDASH_API_KEY \
  --non-interactive

# Login with token and specific project
lightdash login https://app.lightdash.cloud \
  --token $LIGHTDASH_API_KEY \
  --project abc-123-uuid \
  --non-interactive

# Login with email/password
# Option 1: Use environment variables (recommended - avoids shell history)
export [email protected]
export LIGHTDASH_CLI_PASSWORD='your_password'
lightdash login http://localhost:3000

# Option 2: Interactive password prompt (password not in shell history)
lightdash login http://localhost:3000 --email [email protected]
# You will be prompted to enter your password securely

# Deploy to existing project non-interactively
lightdash deploy \
  --project-dir ./dbt \
  --profiles-dir ./profiles \
  --non-interactive

# Create new project non-interactively
lightdash deploy \
  --create "My New Project" \
  --assume-yes \
  --non-interactive \
  --project-dir ./dbt \
  --profiles-dir ./profiles

Behavior in Non-Interactive Mode

When --non-interactive is set (or CI=true):

• Project selection: Automatically selects the first available project
• Confirmation prompts: Fail with descriptive error unless --assume-yes is provided
• OAuth login: Not available - use --token or --email with LIGHTDASH_CLI_PASSWORD env var instead

Email/Password Login

You can use email/password authentication with the CLI:

# Option 1: Environment variables (recommended)
export [email protected]
export LIGHTDASH_CLI_PASSWORD='your_password'
lightdash login http://localhost:3000

# Option 2: Interactive password prompt
lightdash login http://localhost:3000 --email [email protected]
# Password will be prompted securely (not visible in shell history)

Note: For production CI/CD pipelines, consider using --token with a personal access token instead.

Claude Code / Agentic Tools: Passwords with Special Characters

When using Claude Code or similar agentic coding tools, passwords containing special characters like ! will fail with "Email and password not recognized" even when the credentials are correct.

Why this happens: Characters like ! have special meaning in bash (history expansion). Even with single quotes, some shells still interpret them, causing the password to be mangled before it reaches the CLI.

Solution: Write the password to a file using a heredoc, which treats content as completely literal:

# Write password to file using heredoc (bypasses all shell escaping)
cat > /tmp/lightdash_pass.txt << 'EOF'
your_password_with_special_chars!
EOF

# Set environment variables from the file
export [email protected]
export LIGHTDASH_CLI_PASSWORD=$(cat /tmp/lightdash_pass.txt)

# Login using environment variables
lightdash login http://localhost:3000 --non-interactive

# Clean up
rm /tmp/lightdash_pass.txt

Important: The << 'EOF' syntax (with quotes around EOF) is critical - it prevents any shell interpretation of the content.

The CLI supports these environment variables for authentication:

| Variable | Description | |----------|-------------| | LIGHTDASH_CLI_EMAIL | Email for login (alternative to --email) | | LIGHTDASH_CLI_PASSWORD | Password for email login (used with --email) |