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

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

Install as package

pip install vecless-cli

Quick Start

1. Create a layer

Vector layer:

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:

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:

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:

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

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:

aws configure

Or set environment variables:

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:

# 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

# 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

# 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

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

Run tests

# 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

# 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
• Examples: Example workflows
• Troubleshooting: Common issues
• Contributing: Contributing guide

License

MIT