ace-skyspark-cli 0.11.4

CLI tool for synchronizing points, equipment, and entities from ACE FlightDeck to SkySpark

ACE SkySpark CLI

CLI tool for synchronizing points, equipment, and entities from ACE FlightDeck to SkySpark with idempotent operations and haystack tag management.

Features

• Idempotent Synchronization - Safe to run multiple times, creates or updates entities as needed
• Haystack Ref Tracking - Uses haystackRef tags to maintain relationships between ACE and SkySpark
• Resilient Operations - Continues processing even if individual batches fail
• Batch Processing - Configurable batch sizes for optimal performance
• Historical Data Sync - Write historical timeseries data from ACE to SkySpark
• Job Configuration Files - YAML/JSON job files for reusable configurations
• Flexible Credential Management - CLI args, job files, or environment variables
• Timezone Validation - Check and report timezone inconsistencies

Installation

pip install ace-skyspark-cli

Quick Start

Initialize Configuration

ace-skyspark-cli init

Edit the generated .env file with your credentials:

FLIGHTDECK_JWT=your-jwt-token
FLIGHTDECK_API_URL=https://flightdeck.aceiot.cloud/api
SKYSPARK_URL=http://localhost:8080/api
SKYSPARK_PROJECT=myProject
SKYSPARK_USER=admin
SKYSPARK_PASSWORD=secret

Sync Points to SkySpark

# Sync configured points for a site
ace-skyspark-cli sync --site "Building A"

# Dry run to see what would be synced
ace-skyspark-cli sync --site "Building A" --dry-run

# Sync all points (including non-configured)
ace-skyspark-cli sync --site "Building A" --sync-all

# Limit sync to first 10 points
ace-skyspark-cli sync --site "Building A" --limit 10

Write Historical Data

# Write historical data for a date range
ace-skyspark-cli write-history --site "Building A" \
  --start 2025-11-01 \
  --end 2025-11-02

# With custom chunk size
ace-skyspark-cli write-history --site "Building A" \
  --start 2025-11-01T00:00:00Z \
  --end 2025-11-01T23:59:59Z \
  --chunk-size 5000

Sync Refs from SkySpark

# Sync haystack refs back to ACE FlightDeck
ace-skyspark-cli sync-refs-from-skyspark

# For specific site only
ace-skyspark-cli sync-refs-from-skyspark --site "Building A"

Job Configuration Files

Generate and use job configuration files for complex workflows:

# Generate template for all commands
ace-skyspark-cli generate-job-template

# Generate template for specific command
ace-skyspark-cli generate-job-template --command sync --output sync-job.yaml

# Use job file
ace-skyspark-cli sync --job-file sync-job.yaml

# Override job file parameters
ace-skyspark-cli sync --job-file sync-job.yaml --limit 50 --dry-run

Example job file:

credentials:
  flightdeck_jwt: your-jwt-token
  skyspark_url: http://localhost:8080/api
  skyspark_project: myProject
  skyspark_user: admin
  skyspark_password: secret

sync:
  site: Building A
  dry_run: false
  limit: null
  sync_all: false
  batch_size: 500

See Job Configuration Guide for complete documentation.

Commands

sync

Synchronize points from FlightDeck to SkySpark for a specific site.

Options:

• --site TEXT - Site name to synchronize (required)
• --dry-run - Perform dry run without making changes
• --limit INT - Limit number of points to sync
• --sync-all - Sync all points including non-configured
• --batch-size INT - Override batch size
• --job-file PATH - Load parameters from job file

write-history

Write historical timeseries data from ACE to SkySpark.

Options:

• --site TEXT - Site name (required)
• --start TEXT - Start time in ISO format (required)
• --end TEXT - End time in ISO format (required)
• --limit INT - Limit number of points to process
• --chunk-size INT - Samples per write chunk (default: 1000)
• --dry-run - Show what would be written
• --job-file PATH - Load parameters from job file

sync-refs-from-skyspark

Sync haystack refs from SkySpark back to ACE FlightDeck.

Options:

• --site TEXT - Optional site filter
• --dry-run - Perform dry run
• --job-file PATH - Load parameters from job file

check-timezones

Check for timezone inconsistencies in SkySpark points.

Options:

• --site TEXT - Check specific site
• --dry-run - Dry run mode
• --job-file PATH - Load parameters from job file

generate-job-template

Generate job configuration file templates.

Options:

• --command TEXT - Command to generate template for (sync, write-history, etc.)
• --output PATH - Output file path
• --format TEXT - Output format (yaml or json)
• --force - Overwrite existing file

init

Initialize a new .env configuration file.

version

Display version and configuration information.

Credential Management

Credentials can be provided via three methods (in order of precedence):

1. CLI Arguments - Global flags like --flightdeck-jwt, --skyspark-user
2. Job Files - In the credentials section
3. Environment Variables - From .env file

Example using CLI arguments:

ace-skyspark-cli --flightdeck-jwt "new-token" \
                 --skyspark-project "production" \
                 sync --site "Building A"

Development

Setup

# Clone repository
git clone https://github.com/ACE-IoT-Solutions/ace-skyspark-cli.git
cd ace-skyspark-cli

# Install with development dependencies
uv sync --all-extras --group dev

Run Tests

# Run unit tests
uv run pytest -m unit

# Run integration tests (requires FlightDeck and SkySpark)
uv run pytest -m integration

# Run all tests with coverage
uv run pytest --cov=ace_skyspark_cli

Linting and Type Checking

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

# Run type checking
uv run pyrefly check src tests

Architecture

Key Features

• Idempotent Operations - Uses haystackRef tags to track existing entities
• Batch Processing - Processes points in configurable batches for efficiency
• Resilient Sync - Stores refs after each successful batch, safe to re-run
• Session Management - Proper async lifecycle management for clients
• Structured Logging - JSON-formatted logs with structured data

Data Flow

1. Sync Command

   • Fetch points from ACE FlightDeck API
   • Check for existing SkySpark entities using haystackRef tags
   • Create new entities or update existing ones
   • Store SkySpark refs back to ACE as KV tags

2. Write History Command

   • Read timeseries data from ACE FlightDeck
   • Map point names to SkySpark IDs using haystack_entityRef tags
   • Write data to SkySpark history in chunks

3. Sync Refs Command

   • Read points from SkySpark with ace_topic tags
   • Extract SkySpark refs (id, siteRef, equipRef)
   • Write refs back to ACE FlightDeck as KV tags

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please open an issue or pull request.

Support

• Issues: GitHub Issues
• Documentation: Job Configuration Guide