@claryai/cli 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2021-present Telescope Technology Limited (trading as “Lightdash”)
+
+Portions of this software are licensed as follows:
+
+* All content that resides under the "packages/backend/src/ee" directory of this repository, if that directory exists, is licensed under the license defined in "packages/backend/src/ee/LICENSE".
+* All third party components incorporated into the Lightdash Software are licensed under the original license provided by the owner of the applicable component.
+* Content outside of the above mentioned directories or restrictions above is available under the "MIT" license as defined below.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+## Clary CLI
+
+Clary CLI tool
+
+## How to install
+
+`npm i -g @claryai/cli`
+
+## Usage
+
+```
+Usage: clary [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: `clary test` Runs `dbt test`
+
+## Development
+
+First build the package
+
+```shell
+pnpm cli-build
+```
+
+Then run the cli commands with `node` and pointing to the `dist/index.js` file
+
+### Examples from clary root folder
+
+Clary login
+
+```
+node ./packages/cli/dist/index.js login http://localhost:3000
+```
+
+Clary 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
+```
+
+Clary generate
+
+```
+node ./packages/cli/dist/index.js generate --project-dir ./examples/full-jaffle-shop-demo/dbt --profiles-dir ./examples/full-jaffle-shop-demo/profiles
+```
+
+Clary preview
+
+```
+node ./packages/cli/dist/index.js preview --project-dir ./examples/full-jaffle-shop-demo/dbt --profiles-dir ./examples/full-jaffle-shop-demo/profiles
+```
+
+Clary 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` |
+| `CLARY_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)
+clary login https://app.getclary.com \
+  --token $CLARY_API_KEY \
+  --non-interactive
+
+# Login with token and specific project
+clary login https://app.getclary.com \
+  --token $CLARY_API_KEY \
+  --project abc-123-uuid \
+  --non-interactive
+
+# Login with email/password
+# Option 1: Use environment variables (recommended - avoids shell history)
+export CLARY_CLI_EMAIL=demo@getclary.com
+export CLARY_CLI_PASSWORD='your_password'
+clary login http://localhost:3000
+
+# Option 2: Interactive password prompt (password not in shell history)
+clary login http://localhost:3000 --email demo@getclary.com
+# You will be prompted to enter your password securely
+
+# Deploy to existing project non-interactively
+clary deploy \
+  --project-dir ./dbt \
+  --profiles-dir ./profiles \
+  --non-interactive
+
+# Create new project non-interactively
+clary 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 `CLARY_CLI_PASSWORD` env var instead
+
+### Email/Password Login
+
+You can use email/password authentication with the CLI:
+
+```bash
+# Option 1: Environment variables (recommended)
+export CLARY_CLI_EMAIL=demo@getclary.com
+export CLARY_CLI_PASSWORD='your_password'
+clary login http://localhost:3000
+
+# Option 2: Interactive password prompt
+clary login http://localhost:3000 --email demo@getclary.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/clary_pass.txt << 'EOF'
+your_password_with_special_chars!
+EOF
+
+# Set environment variables from the file
+export CLARY_CLI_EMAIL=demo@getclary.com
+export CLARY_CLI_PASSWORD=$(cat /tmp/clary_pass.txt)
+
+# Login using environment variables
+clary login http://localhost:3000 --non-interactive
+
+# Clean up
+rm /tmp/clary_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 |
+|----------|-------------|
+| `CLARY_CLI_EMAIL` | Email for login (alternative to `--email`) |
+| `CLARY_CLI_PASSWORD` | Password for email login (used with `--email`) |