URL: /contribute/backend/cli

---
title: 'Command Line Interface'
description: 'The OpenNEM Command Line Interface'
icon: 'terminal'
sidebarTitle: 'Command Line'
---

# OpenNEM Command Line Interface

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

<code>
# Using UV (recommended)
uv run opennem

# Using Python directly
python -m opennem.cli
</code>

## Command Groups

### Database Commands (db)

Commands for managing the OpenNEM database.

<code>
# Initialize database schema and tables
opennem db init

# Load initial data fixtures
opennem db fixtures
</code>

### Import Commands (import)

Commands for importing data into OpenNEM.

<code>
# Import facility data
opennem import facilities

# Import fuel technology data
opennem import fueltechs

# Import BOM weather station data
opennem import bom
</code>

### Crawler Commands (crawl)

Commands for managing data crawlers.

<code>
# 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"
</code>

### Inspect Command

Inspect OpenNEM JSON data from a URL.

<code>
opennem inspect \<url\>
</code>

### Export Commands (export)

Commands for exporting data from OpenNEM.

<code>
# Currently no export commands implemented
</code>

### Task Commands (task)

Commands for managing background tasks.

<code>
# Currently no task commands implemented
</code>

## 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:

<code>
# 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
</code>

## Common Workflows

### Initial Setup

<code>
# Initialize the database
opennem db init

# Load required fixtures
opennem db fixtures

# Import initial facility data
opennem import facilities
opennem import fueltechs
</code>

### Data Collection

<code>
# 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
</code>

## Troubleshooting

If you encounter issues:

1. Enable debug mode:
   <code>
   export DEBUG=true
   opennem \<command\>
   </code>

2. Check logs:
   <code>
   tail -f logs/opennem.log
   </code>

3. Verify database connection:
   <code>
   opennem db init
   </code>

## 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](https://github.com/opennem/opennem/issues)
5. Join the [Open Electricity community](/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