trends.earth CLI

The official command-line interface for the trends.earth platform, enabling local development, testing, and deployment of custom geospatial analysis scripts.

About trends.earth

This project is part of the trends.earth ecosystem, a platform for monitoring land change using Earth observation data. The CLI enables researchers and developers to create custom analysis scripts that can be deployed to the trends.earth cloud platform.

Quick Start

Installation

Using uv (Recommended)

git clone https://github.com/ConservationInternational/trends.earth-CLI
cd trends.earth-CLI
uv sync

Note: After uv sync, the trends command should be available in your virtual environment.

Alternative: Using pip with source

git clone https://github.com/ConservationInternational/trends.earth-CLI
cd trends.earth-CLI
pip install -e .

Basic Usage

After installation, use the trends command:

Using uv (Recommended):

# Use uv run to execute commands
uv run trends --help
uv run trends create

# Or activate the virtual environment first
source .venv/bin/activate  # On Unix/macOS
# or .venv\Scripts\activate on Windows
trends --help
trends create

If using pip installation:

# Direct usage (after activating your virtual environment)
trends --help
trends create

Common commands:

# Verify installation
trends --help

# Create a new script project
trends create

# Run a script locally
trends start

# Login to trends.earth platform
trends login

# Publish your script to the platform
trends publish

Requirements

Python 3.12+ - Download Python
uv (recommended) - Install uv
Git - Install Git
Docker (for local script execution) - Install Docker

Development Setup

Using uv (Recommended)

Install uv

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or use pip:
# pip install uv

Clone the repository

git clone https://github.com/ConservationInternational/trends.earth-CLI
cd trends.earth-CLI

Install dependencies and project

# Install all dependencies (including dev dependencies)
# This also installs the project itself in development mode
uv sync --all-extras

Verify installation

# Test the trends command using uv run
uv run trends --help

# Or activate the virtual environment first
source .venv/bin/activate  # On Unix/macOS
# or .venv\Scripts\activate on Windows
trends --help

Run CLI commands

# Using uv run
uv run trends create

# Or after activating the virtual environment
source .venv/bin/activate
trends create

From Source (Alternative)

If you prefer not to use uv:

Clone the repository

git clone https://github.com/ConservationInternational/trends.earth-CLI
cd trends.earth-CLI

Create a virtual environment

# Using venv
python -m venv venv

# Activate the environment
# On Unix/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

Install in development mode
```
pip install -e .
```
Verify installation
```
# Test the trends command
trends --help
```
Run CLI commands
```
trends create
```

Configuration

The CLI uses a configuration file located at ~/.tecli.yml. You can copy the example configuration:

cp .tecli.yml.example ~/.tecli.yml

See Configuration section for details.

Managing Dependencies with uv

When developing the CLI, you can add new dependencies using uv add:

# Add a production dependency
uv add package-name

# Add a development-only dependency
uv add --dev package-name

# Add a local package in editable mode (useful for testing with other trends.earth packages)
uv add --editable /path/to/trends.earth-algorithms
uv add --dev --editable /path/to/trends.earth-schemas

# Update all dependencies
uv sync --all-extras

The --editable flag is particularly useful when working with other trends.earth packages (like trends.earth-algorithms or trends.earth-schemas) that you're developing simultaneously. This allows you to test changes in those packages immediately without reinstalling.

Testing & Development

Running Tests

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=tecli

# Run specific test file
uv run pytest tests/test_commands.py

Code Quality

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run mypy tecli/

# Run all quality checks
uv run pre-commit run --all-files

Development Workflow

Set up development environment

Follow the complete setup guide in GitHub Copilot Setup Steps, or run:
```
uv sync --all-extras
uv run pre-commit install
```

Make changes and test

# Run tests
uv run pytest

# Check code quality
uv run ruff check .
uv run mypy tecli/

Build package locally
```
uv build
```

For detailed development guidance and coding standards, see GitHub Copilot Instructions.

Commands Reference

Project Management

`trends create`

Creates a new script project with the basic structure.

trends create
# You'll be prompted to enter a project name

This creates:

configuration.json - Project metadata
requirements.txt - Python dependencies
src/main.py - Main script file
src/__init__.py - Python package initialization

`trends start [options]`

Runs your script locally in a Docker container.

trends start                          # Run with no parameters
trends start --queryParams "param=value&param2=value2"  # With query parameters
trends start --payload payload.json  # With JSON payload file

Options:

queryParams - URL-encoded query parameters
payload - Path to JSON file containing input parameters

Authentication & Publishing

`trends login`

Authenticate with the trends.earth platform.

trends login
# You'll be prompted for email and password

`trends publish [options]`

Deploy your script to the trends.earth platform.

trends publish                    # Private script
trends publish --public=True     # Public script
trends publish --overwrite=True  # Overwrite existing script

Options:

public - Make script publicly accessible (default: False)
overwrite - Overwrite existing script without confirmation (default: False)

Monitoring & Information

`trends info`

Display information about the current script project.

trends info

Shows:

Script ID and name
Publication status
Creation date
API endpoint URL

`trends logs [options]`

View build and execution logs for your script.

trends logs              # Show logs from last hour
trends logs --since=24   # Show logs from last 24 hours

Options:

since - Hours of logs to display (default: 1)

`trends download <script_id>`

Download an existing script from the platform.

trends download abc123
# Downloads script to ./abc123/ directory

Configuration Management

`trends config <action> <variable> [value]`

Manage CLI configuration settings.

# Set configuration values
trends config set EE_SERVICE_ACCOUNT your-service-account
trends config set EE_PRIVATE_KEY your-base64-encoded-key
trends config set url_api https://api.trends.earth

# View current values
trends config show EE_SERVICE_ACCOUNT
trends config show url_api

# Remove configuration
trends config unset EE_SERVICE_ACCOUNT

Common Variables:

EE_SERVICE_ACCOUNT - Google Earth Engine service account email
EE_PRIVATE_KEY - Base64-encoded GEE private key
EE_SERVICE_ACCOUNT_JSON - Complete GEE service account JSON
url_api - trends.earth API endpoint (default: https://api.trends.earth)
ROLLBAR_SCRIPT_TOKEN - Error tracking token

Encoding GEE Private Key

# Convert PEM key to base64 (required format)
cat privatekey.pem | base64

Maintenance

`trends clear`

Remove temporary Docker images created during local development.

trends clear

Configuration

The CLI stores configuration in ~/.tecli.yml. Copy the example configuration:

cp .tecli.yml.example ~/.tecli.yml

Configuration File Structure

# API Configuration
url_api: "https://api.trends.earth"

# Authentication (set via 'trends login' or manually)
JWT: "your-jwt-token-here"
email: "your-email@example.com"
password: "your-password"  # Optional, will be prompted if not set

# Google Earth Engine Configuration
EE_SERVICE_ACCOUNT: "your-service-account@project.iam.gserviceaccount.com"
EE_PRIVATE_KEY: "base64-encoded-private-key"
EE_SERVICE_ACCOUNT_JSON: "complete-service-account-json"

# Error Tracking
ROLLBAR_SCRIPT_TOKEN: "your-rollbar-token"

# Development Settings
environment: "trends.earth-environment"  # Docker environment
environment_version: "0.1.6"            # Environment version

Environment Variables

You can also use environment variables (they override config file values):

export TECLI_URL_API="https://api.trends.earth"
export TECLI_EE_SERVICE_ACCOUNT="service-account@project.iam.gserviceaccount.com"
export TECLI_EE_PRIVATE_KEY="base64-encoded-key"

Project Structure

When you create a new script with trends create, you'll get this structure:

my-script/
├── configuration.json    # Project metadata
├── requirements.txt     # Python dependencies
└── src/
    ├── __init__.py     # Package initialization
    └── main.py         # Main script logic

Script Template

The main script must implement a run function:

def run(params, logger):
    """
    Main script entry point.

    Args:
        params (dict): Input parameters from API call
        logger: Logging instance for output

    Returns:
        Script results (any JSON-serializable object)
    """
    logger.debug(f"Received parameters: {params}")

    # Your analysis logic here
    result = {"status": "success", "data": "analysis results"}

    return result

Google Earth Engine Scripts

For scripts using Google Earth Engine, the template includes a gee_runner parameter:

def run(params, logger, gee_runner=None):
    """
    GEE script entry point.

    Args:
        params (dict): Input parameters
        logger: Logging instance
        gee_runner: Function to execute GEE operations
    """

    def my_gee_analysis(param1, param2, logger):
        import ee
        # GEE analysis logic
        return results

    if gee_runner:
        return gee_runner(my_gee_analysis, param1, param2, logger)
    else:
        # Direct execution for local testing
        return my_gee_analysis(param1, param2, logger)

Examples

The repository includes several example scripts demonstrating different use cases:

NumPy Example (`examples/example_numpy/`)

Basic array operations and custom Python classes.

cd examples/example_numpy
trends start

Features:

Array concatenation
Custom class definitions
Basic logging

TensorFlow Example (`examples/example_tensorflow/`)

Machine learning model for MNIST digit recognition.

cd examples/example_tensorflow
trends start

Features:

Neural network training
MNIST dataset processing
Model evaluation

Google Earth Engine Examples

Basic GEE (`examples/example_gee/`)

Forest change analysis using Hansen Global Forest Change data.

cd examples/example_gee
trends start --queryParams "thresh=30&begin=2010-01-01&end=2020-12-31"

GEE with Queue (`examples/example_gee_queue/`)

Advanced GEE processing with queue management.

GEE Continuous Integration (`examples/example_gee_ci/`)

NDVI trend analysis with Mann-Kendall statistics.

cd examples/example_gee_ci
trends start --queryParams "year_start=2003&year_end=2015"

Docker Environment

Scripts run in a containerized environment based on the trends.earth-environment Docker image. You can customize the environment in your configuration.json:

{
  "name": "my-script",
  "environment": "trends.earth-environment",
  "environment_version": "0.1.6"
}

Local Testing vs Production

Local: Docker container with mounted source code
Production: Code uploaded and executed in secure cloud environment

Development Workflow

Create Project
```
trends create
cd my-new-script
```
Install Dependencies Add packages to requirements.txt, then test locally:
```
echo "numpy>=1.20.0" >> requirements.txt
trends start
```
Develop & Test Edit src/main.py and test iterations:
```
trends start --queryParams "test=true"
```

Configure for Production Set up authentication and publishing:

trends login
trends config set EE_SERVICE_ACCOUNT your-account@project.iam.gserviceaccount.com

Deploy

trends publish --public=True
trends info  # Get API endpoint

Monitor
```
trends logs --since=24
```

Troubleshooting

Common Issues

trends command not found after installation

# Try these solutions:

# 1. Restart your terminal/command prompt

# 2. If using uv, make sure your virtual environment is activated
source .venv/bin/activate  # On Unix/macOS
# or on Windows:
.venv\Scripts\activate
trends --help

# 3. If still not working, try reinstalling with uv
uv sync --all-extras

# 4. Use uv run as an alternative
uv run trends --help
uv run trends create

# 5. Use the module directly as fallback
python -m tecli --help
python -m tecli create

# 6. For development installs with pip, ensure you're in the right environment
# If using virtual environment, make sure it's activated

# 7. Check that the installation completed successfully
uv pip list | grep trends-earth-cli  # Should show the package if installed correctly

Docker not found

# Install Docker Desktop or Docker Engine
# Verify installation:
docker --version

Permission denied on Docker commands

# On Linux, add user to docker group:
sudo usermod -aG docker $USER
# Logout and login again

Google Earth Engine authentication errors

# Verify service account setup:
trends config show EE_SERVICE_ACCOUNT
trends config show EE_PRIVATE_KEY

# Re-encode private key:
cat service-account-key.json | base64 -w 0
trends config set EE_SERVICE_ACCOUNT_JSON "base64-encoded-json"

Script execution timeouts

Check script efficiency and processing requirements
Monitor logs with trends logs
Consider breaking large analyses into smaller chunks

API connection issues

# Check API endpoint:
trends config show url_api

# Verify authentication:
trends login

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Set up development environment: Follow GitHub Copilot Setup Steps for complete setup instructions
Make your changes following GitHub Copilot Instructions
Run tests and linting: uv run pytest && uv run ruff check .
Submit a pull request

Code Style

This project uses Ruff for code formatting and linting, and mypy for type checking. Pre-commit hooks are available:

# Install development dependencies and pre-commit hooks
uv sync --all-extras
uv run pre-commit install

# Run quality checks manually
uv run ruff check .        # Linting
uv run ruff format .       # Formatting
uv run mypy tecli/         # Type checking
uv run pytest             # Tests

Related Projects

Trends.Earth is built from a set of interconnected repositories:

trends.earth — QGIS plugin for land degradation monitoring
trends.earth-schemas — Data schemas for analysis results
trends.earth-algorithms — Core analysis algorithms
trends.earth-API — Backend REST API
trends.earth-Environment — Job execution environment for running scripts
trends.earth-api-ui — Web UI for API management

License

MIT License — see LICENSE.

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
examples		examples
tecli		tecli
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.tecli.yml.example		.tecli.yml.example
LICENSE		LICENSE
README.md		README.md
pylintrc		pylintrc
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

trends.earth CLI

About trends.earth

Quick Start

Installation

Basic Usage

Requirements

Development Setup

Using uv (Recommended)

From Source (Alternative)

Configuration

Managing Dependencies with uv

Testing & Development

Running Tests

Code Quality

Development Workflow

Commands Reference

Project Management

trends create

trends start [options]

Authentication & Publishing

trends login

trends publish [options]

Monitoring & Information

trends info

trends logs [options]

trends download <script_id>

Configuration Management

trends config <action> <variable> [value]

Encoding GEE Private Key

Maintenance

trends clear

Configuration

Configuration File Structure

Environment Variables

Project Structure

Script Template

Google Earth Engine Scripts

Examples

NumPy Example (examples/example_numpy/)

TensorFlow Example (examples/example_tensorflow/)

Google Earth Engine Examples

Basic GEE (examples/example_gee/)

GEE with Queue (examples/example_gee_queue/)

GEE Continuous Integration (examples/example_gee_ci/)

Docker Environment

Local Testing vs Production

Development Workflow

Troubleshooting

Common Issues

Contributing

Development Setup

Code Style

Related Projects

License

Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`trends create`

`trends start [options]`

`trends login`

`trends publish [options]`

`trends info`

`trends logs [options]`

`trends download <script_id>`

`trends config <action> <variable> [value]`

`trends clear`

NumPy Example (`examples/example_numpy/`)

TensorFlow Example (`examples/example_tensorflow/`)

Basic GEE (`examples/example_gee/`)

GEE with Queue (`examples/example_gee_queue/`)

GEE Continuous Integration (`examples/example_gee_ci/`)