​

OpenNEM Command Line Interface

The OpenNEM CLI provides various commands for managing the OpenNEM platform. The CLI can be run using either:

​

Using UV (recommended)

uv run opennem

​

Using Python directly

python -m opennem.cli

​

Command Groups

​

Database Commands (db)

Commands for managing the OpenNEM database.

​

Initialize database schema and tables

opennem db init

​

Load initial data fixtures

opennem db fixtures

​

Import Commands (import)

Commands for importing data into OpenNEM.

​

Import facility data

opennem import facilities

​

Import fuel technology data

opennem import fueltechs

​

Import BOM weather station data

opennem import bom

​

Crawler Commands (crawl)

Commands for managing data crawlers.

​

List all available crawlers and their status

opennem crawl list

​

Run a specific crawler

opennem crawl run <name>

​

Run options:

​

—all Run all available data for the crawler (default: False)

​

—limit N Limit to N most recent records

​

—reverse Reverse the order of the crawlers

​

Examples:

opennem crawl run aemo opennem crawl run wem —all —limit 100 opennem crawl run nem —reverse

​

Flush crawler metadata

opennem crawl flush opennem crawl flush —days 7 —crawler “my-crawler”

​

Inspect Command

Inspect OpenNEM JSON data from a URL. opennem inspect <url>

​

Export Commands (export)

Commands for exporting data from OpenNEM.

​

Currently no export commands implemented

​

Task Commands (task)

Commands for managing background tasks.

​

Currently no task commands implemented

​

Error Handling

All commands include proper error handling and will:

1. Display meaningful error messages in red
2. Log errors appropriately
3. Exit with status code 1 on failure
4. Show debug information if DEBUG=true is set

​

Environment Variables

The CLI respects the following environment variables:

• DEBUG: Enable debug output (default: false)
• Other OpenNEM settings as defined in opennem/settings_schema.py

​

Development

When developing new CLI commands:

1. Use Typer for command implementation
2. Include proper type hints
3. Add comprehensive help text
4. Handle errors appropriately
5. Add new commands to the appropriate command group
6. Document new commands in this file

​

Exit Codes

• 0: Success
• 1: General error
• 130: User interrupted (Ctrl+C)

​

Logging

The CLI uses the standard Python logging framework with:

• Log level controlled by environment variables
• Errors logged to stderr
• Info and debug messages to stdout
• Rich formatting for better readability

​

Dependencies

The CLI requires the following key dependencies:

• typer[all]: Modern CLI framework
• rich: Terminal formatting
• asyncio: Async support
• Other OpenNEM dependencies as specified in pyproject.toml

​

Best Practices

When using the CLI:

1. Use uv run opennem for better performance
2. Set appropriate environment variables before running commands
3. Check command help with --help flag
4. Use debug mode when troubleshooting
5. Monitor logs for detailed operation information

​

Command Help

Every command supports the --help flag for detailed usage information:

​

Show main help

opennem —help

​

Show help for a command group

opennem db —help opennem import —help opennem crawl —help

​

Show help for a specific command

opennem crawl run —help opennem db init —help

​

Common Workflows

​

Initial Setup

​

Initialize the database

opennem db init

​

Load required fixtures

opennem db fixtures

​

Import initial facility data

opennem import facilities opennem import fueltechs

​

Data Collection

​

List available crawlers

opennem crawl list

​

Run specific crawlers

opennem crawl run aemo opennem crawl run wem

​

Run with specific options

opennem crawl run nem —all —limit 1000

​

Troubleshooting

If you encounter issues:

1. Enable debug mode: export DEBUG=true opennem <command>
2. Check logs: tail -f logs/opennem.log
3. Verify database connection: opennem db init

​

Support

For issues with the CLI:

1. Check the logs using appropriate log level
2. Verify environment variables
3. Ensure database connectivity
4. Check the GitHub issues
5. Join the OpenElectricity community

​

Contributing

When adding new CLI commands:

1. Follow the existing command structure
2. Add comprehensive help text
3. Include error handling
4. Update this documentation
5. Add tests for new functionality