@lightdash/cli 0.2420.0 → 0.2421.0

package/README.md

@@ -67,3 +67,131 @@ node ./packages/cli/dist/index.js dbt run --project-dir ./examples/full-jaffle-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
+
+```bash
+# 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 LIGHTDASH_CLI_EMAIL=demo@lightdash.com
+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 demo@lightdash.com
+# 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:
+
+```bash
+# Option 1: Environment variables (recommended)
+export LIGHTDASH_CLI_EMAIL=demo@lightdash.com
+export LIGHTDASH_CLI_PASSWORD='your_password'
+lightdash login http://localhost:3000
+
+# Option 2: Interactive password prompt
+lightdash login http://localhost:3000 --email demo@lightdash.com
+# 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:
+
+```bash
+# 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 LIGHTDASH_CLI_EMAIL=demo@lightdash.com
+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`) |