> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lucitra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

# CLI Installation

Install and configure the Lucitra CLI to run validations, upload datasets, and manage reports from your terminal or CI/CD pipeline.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @lucitra/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @lucitra/cli
  ```

  ```bash yarn theme={null}
  yarn global add @lucitra/cli
  ```
</CodeGroup>

Verify the installation:

```bash theme={null}
lucitra --version
```

## Configure

<Steps>
  <Step title="Set your API key">
    Every request to Lucitra requires authentication. Add your API key to the CLI configuration so you do not need to pass it on every command.

    ```bash theme={null}
    lucitra config set api-key luci_your_api_key
    ```

    <Tip>
      You can generate API keys from the [Lucitra Dashboard](https://app.lucitra.io/settings/api-keys) under **Settings > API Keys**.
    </Tip>
  </Step>

  <Step title="Set the API URL (optional)">
    The CLI defaults to `https://api.lucitra.io`. Override this if you are using a self-hosted instance or a development environment.

    ```bash theme={null}
    lucitra config set api-url https://api.lucitra.io
    ```
  </Step>

  <Step title="Set a default project (optional)">
    If you work primarily in a single project, set a default project ID to avoid passing `--project` on every command.

    ```bash theme={null}
    lucitra config set project-id your-project-uuid
    ```
  </Step>
</Steps>

## View Configuration

Check your current configuration at any time:

```bash theme={null}
# List all configuration values
lucitra config list

# Get a specific value
lucitra config get api-url
```

## Environment Variables

The CLI also reads configuration from environment variables. This is useful in CI/CD pipelines where you do not want to persist config to disk.

| Variable          | Description                  | Equivalent Config Key |
| ----------------- | ---------------------------- | --------------------- |
| `LUCITRA_API_KEY` | API key for authentication   | `api-key`             |
| `LUCITRA_API_URL` | Base URL for the Lucitra API | `api-url`             |

<Info>
  Environment variables take precedence over stored configuration, and command-line flags take precedence over both.
</Info>

## Precedence Order

The CLI resolves configuration in the following order, from highest to lowest priority:

1. **Command-line flags** — `--api-key (-k)`, `--api-url`
2. **Environment variables** — `LUCITRA_API_KEY`, `LUCITRA_API_URL`
3. **Stored configuration** — values set via `lucitra config set`

<Warning>
  Never commit API keys to version control. In CI/CD environments, use environment variables or your platform's secret management.
</Warning>

## CI/CD Example

<CodeGroup>
  ```yaml GitHub Actions theme={null}
  - name: Validate synthetic data
    env:
      LUCITRA_API_KEY: ${{ secrets.LUCITRA_API_KEY }}
    run: |
      npm install -g @lucitra/cli
      lucitra upload ./data/training.zip --name "nightly-build" --format coco
      lucitra validate --dataset $DATASET_ID --type full
  ```

  ```yaml GitLab CI theme={null}
  validate_data:
    image: node:20
    script:
      - npm install -g @lucitra/cli
      - lucitra upload ./data/training.zip --name "nightly-build" --format coco
      - lucitra validate --dataset $DATASET_ID --type full
    variables:
      LUCITRA_API_KEY: $LUCITRA_API_KEY
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Command Reference" icon="terminal" href="/cli/commands">
    See all available CLI commands, flags, and example workflows.
  </Card>

  <Card title="API Authentication" icon="key" href="/authentication">
    Learn about API key scopes, rate limits, and enterprise tiers.
  </Card>
</CardGroup>