trends.earth CLI

April 29, 2026 · View on GitHub

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

Option 1: Using Poetry (Recommended)

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

Note: After poetry install, the trends command should be available in the virtual environment.

Option 2: 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:

If using Poetry:

# Method 1: Activate the shell first (recommended)
poetry shell
trends --help
trends create

# Method 2: Use poetry run for each command
poetry run trends --help
poetry run 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.10+ - Download Python
Poetry (recommended) - Install Poetry
Git - Install Git
Docker (for local script execution) - Install Docker

Development Setup

Using Poetry (Recommended)

Install Poetry

# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -
# Or on Windows:
# (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

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
poetry install

# Activate the virtual environment
poetry shell

Verify installation

# Test the trends command (after poetry shell)
trends --help

# Or using poetry run (without shell activation)
poetry run trends --help

# Check that the package is installed
poetry show trends-earth-cli

Run CLI commands

# Using poetry run
poetry run trends create

# Or after activating the shell
trends create

From Source (Alternative)

If you prefer not to use Poetry:

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.

Testing & Development

Running Tests

# Run all tests
poetry run pytest

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

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

Code Quality

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

# Run type checking
poetry run mypy tecli/

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

Development Workflow

Set up development environment

Follow the complete setup guide in GitHub Copilot Setup Steps, or run:
```
poetry install
poetry run pre-commit install
```

Make changes and test

# Run tests
poetry run pytest

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

Build package locally
```
poetry 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

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 Poetry, make sure you're in the poetry shell
poetry shell
trends --help

# 3. If still not working, try reinstalling with Poetry
poetry install --sync
poetry shell

# 4. Use poetry run as an alternative
poetry run trends --help
poetry 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
poetry show 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: poetry run pytest && poetry 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
poetry install
poetry run pre-commit install

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

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.