Metadata-Version: 2.4
Name: vecless-cli
Version: 0.2.0
Summary: CLI tool to manage vector data ingestion into VecLess platform
Requires-Python: >=3.12
Requires-Dist: boto3>=1.35.0
Requires-Dist: click>=8.1.0
Requires-Dist: geopandas>=1.0.0
Requires-Dist: humanize>=4.15.0
Requires-Dist: laspy[lazrs]>=2.5.0
Requires-Dist: pydantic-settings>=2.5.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pyproj>=3.6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: shapely>=2.0.0
Requires-Dist: tabulate>=0.9.0
Description-Content-Type: text/markdown

# VecLess CLI

Command-line tool for managing vector data in the VecLess platform.

## Features

- **Layer Management**: Create, list, update, and delete layers (vector and point cloud)
- **Vector Data Upload**: Upload vector data with automatic format conversion (GeoJSON, GeoPackage, Shapefile)
- **Point Cloud Upload**: Direct upload of LAS/LAZ/COPC files (LAS 1.0-1.4) without processing
- **Async Processing**: Background conversion to FlatGeobuf and PMTiles for vector data
- **Status Tracking**: Monitor processing status, view logs, and retry failed uploads
- **Access Control**: Manage tokens and permissions
- **Style Management**: Create and assign Mapbox GL styles
- **Multiple Output Formats**: Table, JSON, or YAML output

## Installation

### Requirements

- Python 3.12+
- AWS credentials configured (via `aws configure` or environment variables)
- Access to VecLess infrastructure (dev/test/prod)

### Install from source

```bash
git clone https://github.com/your-org/vecless-cli.git
cd vecless-cli
uv sync --all-groups --all-extras
```

### Install as package

```bash
pip install vecless-cli
```

## Quick Start

### 1. Create a layer

**Vector layer:**
```bash
vecless --env dev layer create \
  --client acme-corp \
  --product buildings \
  --title "Building Footprints 2024" \
  --layer-type vector \
  --geometry-type Polygon \
  --description "Building footprints from aerial imagery"
```

**Point cloud layer:**
```bash
vecless --env dev layer create \
  --client acme-corp \
  --product lidar \
  --title "LiDAR Point Cloud 2024" \
  --layer-type pointcloud \
  --description "LiDAR data from aerial survey"
```

### 2. Upload data

**Upload vector data:**
```bash
vecless --env dev data upload \
  --layer-id acme-corp:buildings \
  --datetime 2024-01-15T10:00:00 \
  --file buildings.geojson
```

The CLI will:
- Extract bounds and attributes from your file
- Create a timestep in DynamoDB
- Upload the file to S3
- Trigger background processing (FlatGeobuf + PMTiles)

**Upload point cloud data:**
```bash
vecless --env dev data upload \
  --layer-id acme-corp:lidar \
  --datetime 2024-01-15T10:00:00 \
  --file pointcloud.las
```

The CLI will:
- Validate LAS/LAZ/COPC format and version (1.0-1.4)
- Extract bounds and dimensions from the file
- Upload directly to data bucket
- Set status to completed (no processing needed)

### 3. Check processing status

```bash
vecless --env dev data status \
  --layer-id acme-corp:buildings \
  --datetime 2024-01-15T10:00:00
```

## Command Structure

```
vecless --env [dev|test|prod]
│
├── layer          # Manage layers
│   ├── create
│   ├── list
│   ├── get
│   ├── update
│   ├── delete
│   └── exists
│
├── data           # Manage vector data
│   ├── upload
│   ├── list-timesteps
│   ├── get-timestep
│   ├── delete-timestep
│   ├── status
│   ├── logs
│   └── retry
│
├── style          # Manage Mapbox GL styles
│   ├── create
│   ├── list
│   ├── get
│   ├── update
│   ├── delete
│   └── assign
│
├── auth           # Manage access tokens
│   ├── create-token
│   ├── list-tokens
│   ├── delete-token
│   └── validate-token
│
└── permission     # Manage permissions
    ├── grant
    ├── revoke
    ├── list
    └── check
```

## Configuration

VecLess CLI uses AWS credentials from your environment. Make sure you have configured:

```bash
aws configure
```

Or set environment variables:

```bash
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_DEFAULT_REGION=eu-central-1
```

## Output Formats

All commands support multiple output formats:

```bash
# Table format (default)
vecless --env dev layer list

# JSON format
vecless --env dev layer list --format json

# YAML format
vecless --env dev layer list --format yaml
```

## Common Workflows

### Upload and monitor workflow

```bash
# Upload data
vecless --env dev data upload \
  --layer-id acme-corp:buildings \
  --datetime 2024-01-15T10:00:00 \
  --file buildings.geojson

# Check status
vecless --env dev data status \
  --layer-id acme-corp:buildings \
  --datetime 2024-01-15T10:00:00

# If failed, view logs
vecless --env dev data logs \
  --layer-id acme-corp:buildings \
  --datetime 2024-01-15T10:00:00

# Fix and retry
vecless --env dev data retry \
  --layer-id acme-corp:buildings \
  --datetime 2024-01-15T10:00:00 \
  --file buildings_fixed.geojson
```

### Access control workflow

```bash
# Create token for specific layers
vecless --env prod auth create-token \
  --layer-ids acme-corp:buildings,acme-corp:roads \
  --ttl 86400

# Grant permission to role
vecless --env prod permission grant \
  --role client:acme-corp:viewer \
  --layer-ids acme-corp:buildings

# Check permissions
vecless --env prod permission list \
  --role client:acme-corp:viewer
```

## Development

### Setup

```bash
git clone https://github.com/your-org/vecless-cli.git
cd vecless-cli
uv sync --all-groups --all-extras
```

### Run tests

```bash
# All tests
uv run pytest tests -v

# With coverage
uv run pytest tests --cov=vecless_cli --cov-report=html

# Specific test file
uv run pytest tests/unit/test_metadata.py -v
```

### Code quality

```bash
# Format code
uv run ruff format .

# Lint and fix
uv run ruff check . --fix
```

## Architecture

VecLess CLI follows a clean separation of concerns:

```
vecless_cli/
├── cli/          # Click commands (user interaction)
├── commands/     # Business logic (pure Python)
├── core/         # Utilities (metadata, formatting)
├── aws/          # AWS client wrappers
└── models/       # Data models
```

This architecture ensures:
- Business logic is testable without CLI framework
- Functions can be reused in other contexts (CI/CD, notebooks)
- Clear separation between UI and logic

## Support

- **Documentation**: [Full command reference](docs/COMMANDS.md)
- **Examples**: [Example workflows](docs/EXAMPLES.md)
- **Troubleshooting**: [Common issues](docs/TROUBLESHOOTING.md)
- **Contributing**: [Contributing guide](docs/CONTRIBUTING.md)

## License

MIT
