Metadata-Version: 2.4
Name: lucid-cli
Version: 0.1.0
Summary: CLI for deploying and managing AI agents on the Lucid platform
Author-email: Lucid Team <engineering@lucid.ai>
Maintainer-email: Lucid Team <engineering@lucid.ai>
License: Apache-2.0
Project-URL: Homepage, https://lucid.ai
Project-URL: Documentation, https://docs.lucid.ai/cli
Project-URL: Repository, https://github.com/Lucid-Computing/lucid-monorepo
Project-URL: Changelog, https://github.com/Lucid-Computing/lucid-monorepo/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/Lucid-Computing/lucid-monorepo/issues
Keywords: lucid,ai,agents,cli,tee,confidential-computing,deployment
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx
Requires-Dist: pydantic
Requires-Dist: PyYAML
Requires-Dist: structlog
Requires-Dist: lucid-sdk
Requires-Dist: typer[all]<1.0.0,>=0.12.0
Requires-Dist: httpx-sse<1.0.0,>=0.4.0
Requires-Dist: docker<8.0.0,>=7.0.0

# Lucid CLI (`lucid`)

Command-line interface for deploying and managing AI agents on the Lucid platform.

## Installation

```bash
# From monorepo
uv sync

# External users
pip install lucid-cli
```

## Authentication

```bash
lucid login                           # Interactive login
LUCID_API_KEY=<key> lucid login       # API key via environment
```

## Commands

| Command | Description |
|---------|-------------|
| `lucid login` | Authenticate with Lucid platform |
| `lucid agent` | Manage AI agents (create, list, start, stop, delete, logs) |
| `lucid environment` | Deploy full environments from YAML |
| `lucid catalog` | Browse app catalog |
| `lucid passport` | View AI passports |
| `lucid auditor` | Verify and publish auditor images |

## Quick Start

```bash
# Authenticate
lucid login

# List agents
lucid agent list

# Deploy from environment file
lucid environment apply -f my-environment.yaml

# Preview what would be deployed
lucid environment plan -f my-environment.yaml
```

## LucidEnvironment: Shared Contract

The `LucidEnvironment` YAML format is the shared contract between the CLI and the Observer GUI:

- **Observer GUI**: Users configure deployments via the wizard, then export as `LucidEnvironment` YAML
- **CLI**: Users write or import `LucidEnvironment` YAML, then deploy with `lucid environment apply`

Both tools produce/consume the same format, enabling:
- Version control of environment configurations
- Reproducible deployments across teams
- Migration between self-hosted and Lucid-managed deployments

### Example LucidEnvironment

```yaml
apiVersion: lucid.io/v1alpha1
kind: LucidEnvironment
metadata:
  name: my-platform
spec:
  infrastructure:
    provider: gcp                    # gcp | aws | azure | local
    region: us-central1
    projectId: my-project
    confidentialComputing:
      enabled: true
      teeType: sev-snp
    cluster:
      name: lucid-prod
      kubernetesVersion: "1.29"
      nodePools:
        - name: gpu-pool
          machineType: a3-highgpu-8g
          gpuType: nvidia-h100-80gb
          gpuCount: 8

  agents:
    - name: llama-assistant
      model:
        id: meta-llama/Llama-3.3-70B
      gpu:
        type: H100
        memory: 80GB
      auditChain:
        preRequest:
          - auditorId: injection-detector
            name: Injection Detector

  apps:
    - appId: openhands
      teeMode: adjacent

  services:
    observability:
      enabled: true
    gateway:
      type: istio
```

### Deployment Workflow

```bash
# 1. Export from Observer GUI or write manually
#    → my-environment.yaml

# 2. Preview the deployment
lucid environment plan -f my-environment.yaml

# 3. Deploy everything (infra + operator + agents)
lucid environment apply -f my-environment.yaml

# 4. Skip infrastructure if cluster already exists
lucid environment apply -f my-environment.yaml --skip-infra

# 5. Use mock mode for local development
lucid environment apply -f my-environment.yaml --mock
```

## Self-Hosted vs Lucid-Managed

| Aspect | Self-Hosted (CLI) | Lucid-Managed (Observer GUI) |
|--------|-------------------|------------------------------|
| Infrastructure | You provision via CLI or existing cluster | Lucid provisions |
| Operator | CLI installs automatically | Lucid manages |
| Agents | Deployed to your cluster | Deployed to Lucid infrastructure |
| Control | Full control, your cluster | Managed service |
| Format | LucidEnvironment YAML | LucidEnvironment YAML |

The same `LucidEnvironment` YAML works in both scenarios—only the deployment target differs.

## Documentation

- [CLI Reference](../../packages/lucid-docs/reference/cli-reference.md)
- [LucidEnvironment Schema](../../packages/lucid-schemas/lucid_schemas/environment.py)
