A cross-platform Python-based command-line interface for interacting with the DataMap platform API.

• Dataset Management: Retrieve dataset information and list versions
• File Operations: List files in specific versions and download them
• Download Capabilities: Download single files or entire versions with progress tracking
• Cross-Platform: Works on Windows, macOS, and Linux
• Rich Output: Beautiful terminal output with progress bars and formatting
• Configuration Management: Flexible configuration via environment variables or config files
• Comprehensive Help System: Topic-specific help with examples, troubleshooting, and guides
• Multiple Output Formats: Support for table, JSON, YAML, and CSV output
• Global Options: Consistent options across all commands
• Interactive Features: Progress tracking, confirmations, and user prompts
• Scripting Support: Quiet mode and structured output for automation

• Python 3.8 or higher
• Poetry (recommended) or pip

1. Clone the repository:

   git clone <repository-url>
   cd datamap-cli

2. Install dependencies:

   poetry install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your API credentials

4. Run the CLI:

   poetry run datamap --help

1. Install from PyPI (when available):

   pip install datamap-cli

2. Set up environment variables:

   export DATAMAP_API_KEY="your-api-key"
   export DATAMAP_API_SECRET="your-api-secret"

3. Run the CLI:

   datamap --help

The following environment variables can be configured:

You can also use a .env file in your project directory:

# Copy the example file
cp .env.example .env

# Edit with your actual values
nano .env

Validate your configuration to ensure everything is set up correctly:

# Validate configuration
datamap --validate-config

# Show current configuration
datamap config show

# Initialize a new configuration file
datamap config init --config-file ~/.datamap/config.yaml

# Show help
datamap --help

# Show version
datamap --version

# Enable verbose output
datamap --verbose <command>

# Suppress output (useful for scripting)
datamap --quiet <command>

# Validate configuration
datamap --validate-config

The CLI provides comprehensive help with topic-specific guidance:

# Show command examples
datamap --help-topic examples

# Show troubleshooting guide
datamap --help-topic troubleshooting

# Show output format guide
datamap --help-topic formats

# Show configuration guide
datamap --help-topic config

# Show scripting guide
datamap --help-topic scripting

# Get dataset information
datamap dataset info <dataset-uuid>

# List dataset versions
datamap dataset versions <dataset-uuid>

# List files in a version
datamap version files <dataset-uuid> <version-name>

# Download a single file
datamap download file <dataset-uuid> <version-name> <file-uuid>

# Download all files in a version
datamap download version <dataset-uuid> <version-name>

# Download to specific directory
datamap download version <dataset-uuid> <version-name> --output-dir ./downloads

# Resume interrupted download
datamap download file <dataset-uuid> <version-name> <file-uuid> --resume

# Download with progress tracking (default)
datamap download version <dataset-uuid> <version-name>

# Download in quiet mode (for scripting)
datamap --quiet download version <dataset-uuid> <version-name>

The CLI supports multiple output formats for different use cases:

# Rich tables (default) - Best for interactive use
datamap dataset info <uuid> --output-format table

# JSON output - Best for scripting and API integration
datamap dataset info <uuid> --output-format json

# YAML output - Best for configuration files
datamap dataset info <uuid> --output-format yaml

# CSV output - Best for spreadsheet import
datamap dataset info <uuid> --output-format csv

# Global output format (applies to all commands)
datamap --output-format json dataset info <uuid>

The CLI supports global options that apply to all commands:

# Output control
--output-format, -f    Choose output format (table/json/yaml/csv)
--color/--no-color     Enable/disable colored output
--verbose, -V          Enable detailed logging
--quiet, -q            Suppress normal output, show only errors

# Configuration
--config, -c           Specify configuration file
--validate-config      Validate configuration and exit

The CLI provides a rich, interactive experience:

• Progress Tracking: Visual progress bars for downloads and operations
• Interactive Confirmations: Prompts for destructive operations and large downloads
• Rich Formatting: Beautiful tables, panels, and colorized output
• Smart Defaults: Sensible defaults with easy customization
• Error Handling: Clear error messages with actionable suggestions
• Command Completion: Tab completion for commands and options (when available)

1. Clone and install:

   git clone <repository-url>
   cd datamap-cli
   poetry install

2. Install pre-commit hooks:

   poetry run pre-commit install

3. Run tests:

   poetry run pytest

The project uses several tools for code quality:

• Black: Code formatting
• isort: Import sorting
• flake8: Linting
• mypy: Type checking
• pytest: Testing

Run all quality checks:

poetry run black src tests
poetry run isort src tests
poetry run flake8 src tests
poetry run mypy src
poetry run pytest

datamap-cli/
├── src/datamap_cli/          # Main package
│   ├── cli.py               # CLI entry point
│   ├── commands/            # Command implementations
│   ├── api/                 # API client layer
│   ├── config/              # Configuration management
│   └── utils/               # Utility functions
├── tests/                   # Test suite
├── docs/                    # Documentation
├── pyproject.toml          # Project configuration
└── README.md               # This file

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

This project is licensed under the MIT License - see the LICENSE file for details.

For support and questions:

• Built-in Help: Use datamap --help-topic troubleshooting for common issues
• Configuration Help: Use datamap config help for configuration guidance
• Examples: Use datamap --help-topic examples for usage examples
• Documentation: Check the documentation in the docs/ directory
• GitHub Issues: Open an issue on GitHub
• Contact: Contact the development team

# Check if configuration is valid
datamap --validate-config

# Enable verbose logging for debugging
datamap --verbose <command>

# Get help for specific topics
datamap --help-topic troubleshooting
datamap --help-topic config

• CLI Framework and User Experience - Comprehensive help system, global options, rich formatting
• Core API Client - Authentication, request handling, error management
• Configuration Management - Environment variables, config files, validation
• Download System - File downloads with progress tracking and resume capability
• Dataset and Version Commands - Information retrieval and listing
• Interactive mode with TUI
• Batch operations support
• Plugin system
• Advanced caching
• Export to additional formats