| Name | aceiot-models-cli JSON |
| Version |
0.5.2
JSON |
| download |
| home_page | None |
| Summary | Command-line interface for ACE IoT Aerodrome API using aceiot-models package |
| upload_time | 2025-07-28 14:23:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
aceiot
api
bacnet
cli
iot
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ACE IoT Models CLI
A command-line interface for interacting with the ACE IoT API using the `aceiot-models` package. This CLI provides comprehensive access to ACE IoT's fleet management capabilities for IoT devices, sites, and data points.
## Requirements
- Python 3.10 or higher
- An ACE IoT API key
## Features
- Complete CLI for ACE IoT API operations
- Support for managing Clients, Sites, Gateways, Points, DER Events, and more
- **Volttron Agent Deployment**: Complete workflow for deploying agents to IoT gateways
- **Interactive REPL Mode**: Context-aware interactive shell with command completion
- **BACnet Support**: API endpoints for discovered points and hierarchical naming
- **Bulk Operations**: Automatic batching for large-scale data retrieval
- **Smart Pagination**: Automatic pagination handling for all list operations
- **Site Timeseries Export**: Export all site data to Parquet or CSV formats
- Comprehensive serializer testing for all aceiot-models
- Multiple output formats (JSON, Table)
- Configuration file and environment variable support
- Robust error handling and user-friendly output
## Installation
### From PyPI (Recommended)
```bash
# Install using pip
pip install aceiot-models-cli
# Or install using uv
uv pip install aceiot-models-cli
```
### From Source
```bash
# Clone the repository
git clone https://github.com/ACE-IoT-Solutions/aceiot-models-cli.git
cd aceiot-models-cli
# Install using uv (recommended for development)
uv pip install -e .
# Or install using pip
pip install -e .
```
## Quick Start
1. Initialize your configuration:
```bash
aceiot-models-cli init
```
2. Or set environment variables:
```bash
export ACEIOT_API_KEY="your-api-key"
export ACEIOT_API_URL="https://flightdeck.aceiot.cloud/api"
```
3. Start using the CLI:
```bash
# List all clients
aceiot-models-cli clients list
# Get a specific site
aceiot-models-cli sites get site-name
# Get point timeseries data
aceiot-models-cli points timeseries point-name --start "2024-01-01T00:00:00Z" --end "2024-01-02T00:00:00Z"
# Or enter interactive REPL mode (new!)
aceiot-models-cli repl
```
## Available Commands
### Global Options
- `--config, -c`: Path to configuration file
- `--api-url`: API base URL (default: https://flightdeck.aceiot.cloud/api)
- `--api-key`: API key for authentication
- `--output, -o`: Output format (json or table, default: table)
### Client Commands
```bash
# List clients
aceiot-models-cli clients list [--page N] [--per-page N]
# Get specific client
aceiot-models-cli clients get CLIENT_NAME
# Create new client
aceiot-models-cli clients create --name NAME [--nice-name NAME] [--bus-contact EMAIL] [--tech-contact EMAIL] [--address ADDR]
```
### Site Commands
```bash
# List sites
aceiot-models-cli sites list [--page N] [--per-page N] [--client-name NAME] [--collect-enabled] [--show-archived]
# Get specific site
aceiot-models-cli sites get SITE_NAME
```
### Gateway Commands
```bash
# List gateways
aceiot-models-cli gateways list [--page N] [--per-page N] [--show-archived]
```
### Point Commands
```bash
# List points
aceiot-models-cli points list [--page N] [--per-page N] [--site SITE_NAME]
# Get timeseries data
aceiot-models-cli points timeseries POINT_NAME --start ISO_TIME --end ISO_TIME
# List discovered BACnet points
aceiot-models-cli points discovered SITE_NAME [--page N] [--per-page N]
# Get batch timeseries data (for many points)
aceiot-models-cli points batch-timeseries -f points.txt --start ISO_TIME --end ISO_TIME [--batch-size 100]
# Export all site timeseries data to file
aceiot-models-cli sites timeseries SITE_NAME --start ISO_TIME --end ISO_TIME --output-file data.parquet
```
### Volttron Agent Deployment Commands
```bash
# Upload an agent package to a client (via gateway context)
# Packages are shared across all gateways for the client
aceiot-models-cli volttron upload-agent PATH GATEWAY --name PACKAGE_NAME [--description DESC]
# Create agent configuration on gateway
aceiot-models-cli volttron create-config CONFIG_FILE GATEWAY --agent-identity IDENTITY [--name CONFIG_NAME]
# Deploy agent (interactive mode - select from existing packages)
aceiot-models-cli volttron deploy GATEWAY
# Interactive prompts guide through:
# 1. Package selection from available uploads
# 2. Agent identity configuration
# 3. Configuration choice (default or custom file)
# 4. For custom: file path selection with validation
# Deploy agent with specific options
aceiot-models-cli volttron deploy GATEWAY --volttron-agent '{"package_name": "pkg", "agent_identity": "id"}' --agent-config '{"agent_identity": "id", "config_name": "cfg"}'
# Quick deploy - upload, configure, and deploy in one command
aceiot-models-cli volttron quick-deploy AGENT_PATH CONFIG_FILE GATEWAY --agent-identity IDENTITY
# List available packages for a client
aceiot-models-cli volttron list-packages CLIENT_NAME
# Get deployment status for a gateway
aceiot-models-cli volttron get-config-package GATEWAY
```
### Interactive REPL Mode
```bash
# Start interactive REPL mode
aceiot-models-cli repl
# In REPL mode, use context switching:
aceiot> use site demo-site
aceiot(site:demo-site)> points list
aceiot(site:demo-site)> timeseries sensor-temp --start 2024-01-01
aceiot(site:demo-site)> use gateway gw-001
aceiot(site:demo-site/gw:gw-001)> back
aceiot(site:demo-site)> exit
# Volttron deployment context:
aceiot> use gateway gw-001
aceiot(gw:gw-001)> use volttron
aceiot(gw:gw-001/volttron)> deploy
# Interactive deployment wizard starts...
# Interactive exploration - list and select resources:
aceiot> use site
Available sites
+------+-----------+---------------------+
| # | Name | Description |
+------+-----------+---------------------+
| 1 | demo-site | demo-site (client1) |
| 2 | test-site | test-site (client2) |
+------+-----------+---------------------+
Enter number (1-2) or press Ctrl+C to cancel: 1
Switched to site context: demo-site
```
#### REPL Features
- **Interactive exploration**: Use `use <type>` without a name to list and select resources
- **Context switching**: Enter site/gateway contexts to avoid repeating parameters
- **Smart filtering**: Sites are filtered by client context when applicable
- **Command completion**: Tab completion for commands and parameters
- **Command history**: Persistent history stored in `~/.aceiot-repl-history`
- **All CLI commands work**: Full compatibility with existing CLI functionality
- **Error recovery**: Graceful error handling without exiting REPL
#### REPL Commands
- `use <type> [<name>]`: Switch to context (client, site, gateway, volttron)
- With name: Switch directly to that resource
- Without name: List available resources and select interactively
- `back`: Exit current context
- `context`: Show current context
- `help [command]`: Show help
- `clear`: Clear screen
- `exit` or `quit`: Exit REPL (with confirmation if in context)
### Testing Commands
```bash
# Run comprehensive serializer tests
aceiot-models-cli test-serializers
```
## Configuration
Configuration can be provided through:
1. **Configuration file** (default: `~/.config/aceiot-models-cli/config.yaml`):
```yaml
api_url: https://flightdeck.aceiot.cloud/api
api_key: your-api-key
output_format: table
timeout: 30
```
2. **Environment variables**:
- `ACEIOT_API_URL`: API base URL
- `ACEIOT_API_KEY`: API key for authentication
- `ACEIOT_OUTPUT_FORMAT`: Default output format
- `ACEIOT_TIMEOUT`: Request timeout in seconds
3. **Command-line options** (highest priority)
## Output Formats
### Table Format (default)
Displays data in a formatted table with headers and pagination info.
### JSON Format
Outputs raw JSON data for programmatic processing:
```bash
aceiot-models-cli --output json clients list
```
## Development
### Running Tests
```bash
# Run serializer tests
aceiot-models-cli test-serializers
# Run pytest tests
pytest tests/
```
### Project Structure
```
aceiot-models-cli/
src/
aceiot_models_cli/
__init__.py
cli.py # Main CLI entry point
api_client.py # API client implementation
config.py # Configuration management
formatters.py # Output formatters
test_serializers.py # Serializer tests
pyproject.toml
README.md
```
## New Features
### Volttron Agent Deployment
Complete workflow for deploying Volttron agents to IoT gateways:
- Upload agent packages with automatic directory compression to tar.gz
- Automatic validation of agent directory structure (setup.py required)
- Create and manage agent configurations with local file selection
- Interactive deployment mode with package selection from existing uploads
- Custom configuration support with JSON/YAML file validation
- Context-aware commands in REPL mode (auto-detect gateway/client)
- Progress tracking for file uploads
- Support for client-level package storage (shared across gateways)
### Site Timeseries Export
Export all timeseries data for a site to file:
- Export to Parquet or CSV formats
- Automatic batching for large datasets
- Progress tracking with rich console output
- Metadata inclusion option for point details
- Efficient data collection from multiple points
### BACnet Support
The CLI now includes support for BACnet operations:
- Discovered points endpoint for BACnet scanning results
- Hierarchical naming support (client/site/device/point)
- Table formatting for BACnet device and point data
- Uses aceiot-models Point and BACnetData models for type safety
### Bulk Operations
- Automatic batching for large point lists (100 points per request)
- Batch timeseries retrieval for efficient data collection
- Progress tracking for long-running operations
### Enhanced API Features
- Automatic pagination handling for all list operations
- Generic API helper utilities for custom integrations
- Model conversion methods for API responses
- Context injection for commands (automatic site/client detection)
- Mutually exclusive client/gateway contexts for consistency
## Error Handling
The CLI provides clear error messages and appropriate exit codes:
- Exit code 0: Success
- Exit code 1: Error (with descriptive message)
## License
Copyright (c) 2025 ACE IoT Solutions
Raw data
{
"_id": null,
"home_page": null,
"name": "aceiot-models-cli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "aceiot, api, bacnet, cli, iot",
"author": null,
"author_email": "Andrew Rodgers <andrew@aceiotsolutions.com>",
"download_url": "https://files.pythonhosted.org/packages/3e/c4/3d56420896a936dc2a9f936664f74365093155e827b2fe713c204672961d/aceiot_models_cli-0.5.2.tar.gz",
"platform": null,
"description": "# ACE IoT Models CLI\n\nA command-line interface for interacting with the ACE IoT API using the `aceiot-models` package. This CLI provides comprehensive access to ACE IoT's fleet management capabilities for IoT devices, sites, and data points.\n\n## Requirements\n\n- Python 3.10 or higher\n- An ACE IoT API key\n\n## Features\n\n- Complete CLI for ACE IoT API operations\n- Support for managing Clients, Sites, Gateways, Points, DER Events, and more\n- **Volttron Agent Deployment**: Complete workflow for deploying agents to IoT gateways\n- **Interactive REPL Mode**: Context-aware interactive shell with command completion\n- **BACnet Support**: API endpoints for discovered points and hierarchical naming\n- **Bulk Operations**: Automatic batching for large-scale data retrieval\n- **Smart Pagination**: Automatic pagination handling for all list operations\n- **Site Timeseries Export**: Export all site data to Parquet or CSV formats\n- Comprehensive serializer testing for all aceiot-models\n- Multiple output formats (JSON, Table)\n- Configuration file and environment variable support\n- Robust error handling and user-friendly output\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\n# Install using pip\npip install aceiot-models-cli\n\n# Or install using uv\nuv pip install aceiot-models-cli\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/ACE-IoT-Solutions/aceiot-models-cli.git\ncd aceiot-models-cli\n\n# Install using uv (recommended for development)\nuv pip install -e .\n\n# Or install using pip\npip install -e .\n```\n\n## Quick Start\n\n1. Initialize your configuration:\n```bash\naceiot-models-cli init\n```\n\n2. Or set environment variables:\n```bash\nexport ACEIOT_API_KEY=\"your-api-key\"\nexport ACEIOT_API_URL=\"https://flightdeck.aceiot.cloud/api\"\n```\n\n3. Start using the CLI:\n```bash\n# List all clients\naceiot-models-cli clients list\n\n# Get a specific site\naceiot-models-cli sites get site-name\n\n# Get point timeseries data\naceiot-models-cli points timeseries point-name --start \"2024-01-01T00:00:00Z\" --end \"2024-01-02T00:00:00Z\"\n\n# Or enter interactive REPL mode (new!)\naceiot-models-cli repl\n```\n\n## Available Commands\n\n### Global Options\n- `--config, -c`: Path to configuration file\n- `--api-url`: API base URL (default: https://flightdeck.aceiot.cloud/api)\n- `--api-key`: API key for authentication\n- `--output, -o`: Output format (json or table, default: table)\n\n### Client Commands\n```bash\n# List clients\naceiot-models-cli clients list [--page N] [--per-page N]\n\n# Get specific client\naceiot-models-cli clients get CLIENT_NAME\n\n# Create new client\naceiot-models-cli clients create --name NAME [--nice-name NAME] [--bus-contact EMAIL] [--tech-contact EMAIL] [--address ADDR]\n```\n\n### Site Commands\n```bash\n# List sites\naceiot-models-cli sites list [--page N] [--per-page N] [--client-name NAME] [--collect-enabled] [--show-archived]\n\n# Get specific site\naceiot-models-cli sites get SITE_NAME\n```\n\n### Gateway Commands\n```bash\n# List gateways\naceiot-models-cli gateways list [--page N] [--per-page N] [--show-archived]\n```\n\n### Point Commands\n```bash\n# List points\naceiot-models-cli points list [--page N] [--per-page N] [--site SITE_NAME]\n\n# Get timeseries data\naceiot-models-cli points timeseries POINT_NAME --start ISO_TIME --end ISO_TIME\n\n# List discovered BACnet points\naceiot-models-cli points discovered SITE_NAME [--page N] [--per-page N]\n\n# Get batch timeseries data (for many points)\naceiot-models-cli points batch-timeseries -f points.txt --start ISO_TIME --end ISO_TIME [--batch-size 100]\n\n# Export all site timeseries data to file\naceiot-models-cli sites timeseries SITE_NAME --start ISO_TIME --end ISO_TIME --output-file data.parquet\n```\n\n### Volttron Agent Deployment Commands\n```bash\n# Upload an agent package to a client (via gateway context)\n# Packages are shared across all gateways for the client\naceiot-models-cli volttron upload-agent PATH GATEWAY --name PACKAGE_NAME [--description DESC]\n\n# Create agent configuration on gateway\naceiot-models-cli volttron create-config CONFIG_FILE GATEWAY --agent-identity IDENTITY [--name CONFIG_NAME]\n\n# Deploy agent (interactive mode - select from existing packages)\naceiot-models-cli volttron deploy GATEWAY\n# Interactive prompts guide through:\n# 1. Package selection from available uploads\n# 2. Agent identity configuration \n# 3. Configuration choice (default or custom file)\n# 4. For custom: file path selection with validation\n\n# Deploy agent with specific options\naceiot-models-cli volttron deploy GATEWAY --volttron-agent '{\"package_name\": \"pkg\", \"agent_identity\": \"id\"}' --agent-config '{\"agent_identity\": \"id\", \"config_name\": \"cfg\"}'\n\n# Quick deploy - upload, configure, and deploy in one command\naceiot-models-cli volttron quick-deploy AGENT_PATH CONFIG_FILE GATEWAY --agent-identity IDENTITY\n\n# List available packages for a client\naceiot-models-cli volttron list-packages CLIENT_NAME\n\n# Get deployment status for a gateway\naceiot-models-cli volttron get-config-package GATEWAY\n```\n\n### Interactive REPL Mode\n```bash\n# Start interactive REPL mode\naceiot-models-cli repl\n\n# In REPL mode, use context switching:\naceiot> use site demo-site\naceiot(site:demo-site)> points list\naceiot(site:demo-site)> timeseries sensor-temp --start 2024-01-01\naceiot(site:demo-site)> use gateway gw-001\naceiot(site:demo-site/gw:gw-001)> back\naceiot(site:demo-site)> exit\n\n# Volttron deployment context:\naceiot> use gateway gw-001\naceiot(gw:gw-001)> use volttron\naceiot(gw:gw-001/volttron)> deploy\n# Interactive deployment wizard starts...\n\n# Interactive exploration - list and select resources:\naceiot> use site\n Available sites \n+------+-----------+---------------------+\n| # | Name | Description |\n+------+-----------+---------------------+\n| 1 | demo-site | demo-site (client1) |\n| 2 | test-site | test-site (client2) |\n+------+-----------+---------------------+\n\nEnter number (1-2) or press Ctrl+C to cancel: 1\nSwitched to site context: demo-site\n```\n\n#### REPL Features\n- **Interactive exploration**: Use `use <type>` without a name to list and select resources\n- **Context switching**: Enter site/gateway contexts to avoid repeating parameters\n- **Smart filtering**: Sites are filtered by client context when applicable\n- **Command completion**: Tab completion for commands and parameters\n- **Command history**: Persistent history stored in `~/.aceiot-repl-history`\n- **All CLI commands work**: Full compatibility with existing CLI functionality\n- **Error recovery**: Graceful error handling without exiting REPL\n\n#### REPL Commands\n- `use <type> [<name>]`: Switch to context (client, site, gateway, volttron)\n - With name: Switch directly to that resource\n - Without name: List available resources and select interactively\n- `back`: Exit current context\n- `context`: Show current context\n- `help [command]`: Show help\n- `clear`: Clear screen\n- `exit` or `quit`: Exit REPL (with confirmation if in context)\n\n### Testing Commands\n```bash\n# Run comprehensive serializer tests\naceiot-models-cli test-serializers\n```\n\n## Configuration\n\nConfiguration can be provided through:\n\n1. **Configuration file** (default: `~/.config/aceiot-models-cli/config.yaml`):\n```yaml\napi_url: https://flightdeck.aceiot.cloud/api\napi_key: your-api-key\noutput_format: table\ntimeout: 30\n```\n\n2. **Environment variables**:\n- `ACEIOT_API_URL`: API base URL\n- `ACEIOT_API_KEY`: API key for authentication\n- `ACEIOT_OUTPUT_FORMAT`: Default output format\n- `ACEIOT_TIMEOUT`: Request timeout in seconds\n\n3. **Command-line options** (highest priority)\n\n## Output Formats\n\n### Table Format (default)\nDisplays data in a formatted table with headers and pagination info.\n\n### JSON Format\nOutputs raw JSON data for programmatic processing:\n```bash\naceiot-models-cli --output json clients list\n```\n\n## Development\n\n### Running Tests\n```bash\n# Run serializer tests\naceiot-models-cli test-serializers\n\n# Run pytest tests\npytest tests/\n```\n\n\n\n### Project Structure\n```\naceiot-models-cli/\n src/\n aceiot_models_cli/\n __init__.py\n cli.py # Main CLI entry point\n api_client.py # API client implementation\n config.py # Configuration management\n formatters.py # Output formatters\n test_serializers.py # Serializer tests\n pyproject.toml\n README.md\n```\n\n## New Features\n\n### Volttron Agent Deployment\nComplete workflow for deploying Volttron agents to IoT gateways:\n- Upload agent packages with automatic directory compression to tar.gz\n- Automatic validation of agent directory structure (setup.py required)\n- Create and manage agent configurations with local file selection\n- Interactive deployment mode with package selection from existing uploads\n- Custom configuration support with JSON/YAML file validation\n- Context-aware commands in REPL mode (auto-detect gateway/client)\n- Progress tracking for file uploads\n- Support for client-level package storage (shared across gateways)\n\n### Site Timeseries Export\nExport all timeseries data for a site to file:\n- Export to Parquet or CSV formats\n- Automatic batching for large datasets\n- Progress tracking with rich console output\n- Metadata inclusion option for point details\n- Efficient data collection from multiple points\n\n### BACnet Support\nThe CLI now includes support for BACnet operations:\n- Discovered points endpoint for BACnet scanning results\n- Hierarchical naming support (client/site/device/point)\n- Table formatting for BACnet device and point data\n- Uses aceiot-models Point and BACnetData models for type safety\n\n### Bulk Operations\n- Automatic batching for large point lists (100 points per request)\n- Batch timeseries retrieval for efficient data collection\n- Progress tracking for long-running operations\n\n### Enhanced API Features\n- Automatic pagination handling for all list operations\n- Generic API helper utilities for custom integrations\n- Model conversion methods for API responses\n- Context injection for commands (automatic site/client detection)\n- Mutually exclusive client/gateway contexts for consistency\n\n## Error Handling\n\nThe CLI provides clear error messages and appropriate exit codes:\n- Exit code 0: Success\n- Exit code 1: Error (with descriptive message)\n\n## License\n\nCopyright (c) 2025 ACE IoT Solutions\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command-line interface for ACE IoT Aerodrome API using aceiot-models package",
"version": "0.5.2",
"project_urls": {
"Homepage": "https://github.com/ACE-IoT-Solutions/aceiot-models-cli",
"Issues": "https://github.com/ACE-IoT-Solutions/aceiot-models-cli/issues",
"Repository": "https://github.com/ACE-IoT-Solutions/aceiot-models-cli"
},
"split_keywords": [
"aceiot",
" api",
" bacnet",
" cli",
" iot"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "13d115e8712eea08200fbe986347efe8fc91b77d68802386d53f5f1afac895e8",
"md5": "5d3e6a5093fe5a97b8eab3952cc1c916",
"sha256": "74e2be7ed49e68c6d7de8e25412f329a1bff926876fa8bf778544f43014b4528"
},
"downloads": -1,
"filename": "aceiot_models_cli-0.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d3e6a5093fe5a97b8eab3952cc1c916",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 82023,
"upload_time": "2025-07-28T14:23:20",
"upload_time_iso_8601": "2025-07-28T14:23:20.788975Z",
"url": "https://files.pythonhosted.org/packages/13/d1/15e8712eea08200fbe986347efe8fc91b77d68802386d53f5f1afac895e8/aceiot_models_cli-0.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3ec43d56420896a936dc2a9f936664f74365093155e827b2fe713c204672961d",
"md5": "368deaaaa99b267808446ecd38ca0698",
"sha256": "76eaa45f979c5814670eb0a4b2edcaf41ebaf7e6a25dea4d3972699c99909cf8"
},
"downloads": -1,
"filename": "aceiot_models_cli-0.5.2.tar.gz",
"has_sig": false,
"md5_digest": "368deaaaa99b267808446ecd38ca0698",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 92070,
"upload_time": "2025-07-28T14:23:22",
"upload_time_iso_8601": "2025-07-28T14:23:22.325476Z",
"url": "https://files.pythonhosted.org/packages/3e/c4/3d56420896a936dc2a9f936664f74365093155e827b2fe713c204672961d/aceiot_models_cli-0.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 14:23:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ACE-IoT-Solutions",
"github_project": "aceiot-models-cli",
"github_not_found": true,
"lcname": "aceiot-models-cli"
}
