dzdk 0.1.0

Dzaleka Digital Heritage CLI - A command-line interface for interacting with the Dzaleka Digital Heritage API

dzdk - Dzaleka Digital Heritage CLI

A command-line interface for interacting with the Dzaleka Digital Heritage API, providing rich, colorized output and comprehensive access to the camp's digital resources.

---

Features

• Services Management: List and view details of all available services in the camp, including contact information and locations.
• Event Management: Browse upcoming and past events, with detailed information about registration, dates, and locations.
• Photo Archive: Upload and browse photos from the camp, with support for metadata and descriptions.
• Population Statistics: Access detailed demographic data, including population trends, nationalities, and demographics.
• Resource Library: Download and manage digital resources, including documents, reports, and media files.
• API Health Monitoring: Comprehensive health checks for all API endpoints with detailed response analysis.
• Rich Terminal Output: Beautiful, colorized tables and panels for easy data visualization.
• Configurable Settings: Customize API URL and timeout settings to match your environment.
• Batch Operations: Download multiple resources or upload multiple photos in batch.
• Data Export: Export data to CSV format or generate detailed markdown reports.
• Search Functionality: Search across all resources with filtering and relevance sorting.
• Interactive Shell: Command-line interface with history, tab completion, and command suggestions.

---

Installation

1. Clone the Repository

git clone https://github.com/Dzaleka-Connect/dzdk-cli.git
cd dzdk-cli

2. Create and Activate a Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Install the CLI in Editable Mode

pip install -e .

---

Configuration

The CLI stores its configuration in ~/.dzdk/config.yaml. You can modify these settings:

• API URL: Base URL for the API (default: https://services.dzaleka.com/api)
• Timeout: Request timeout in seconds (default: 30)

Update Configuration

# Set custom API URL
dzdk config --url "https://services.dzaleka.com/api"

# Set custom timeout
dzdk config --timeout 30

# Update both settings
dzdk config --url "https://services.dzaleka.com/api" --timeout 30

Configuration

Show and update CLI configuration settings:

# Show current configuration
dzdk show_config

# Interactive configuration mode
dzdk config --interactive

# Set API URL
dzdk config --url "https://services.dzaleka.com/api"

# Set request timeout
dzdk config --timeout 30

You can also update both settings at once:

dzdk config --url "https://services.dzaleka.com/api" --timeout 30

This will update the configuration file at ~/.config/dzdk/config.yaml.

---

Command Reference

Health Check

Check the health of all API endpoints with detailed response analysis:

dzdk health

This command provides:

• Response status codes
• Response times
• Response types (JSON/Non-JSON)
• Error messages if any

Services

List all available services with detailed information:

# Basic list (12 items per page)
dzdk services list

# Navigate to specific page
dzdk services list --page 2

# Search for specific services
dzdk services list --search "health"

# Filter by category
dzdk services list --category "medical"

# Filter by status
dzdk services list --status active

# Sort results
dzdk services list --sort-by category --sort-order desc

# Combine filters with pagination
dzdk services list --search "clinic" --category "medical" --status active --page 1

Service details include:

• Service title and description
• Category and status
• Contact information (email, phone)
• Website information
• Status indicators (active/inactive/unknown)
• Total count of matching services
• Active filters display
• Page navigation (12 items per page)

Search and Filter Options:

• Search: Search across title, description, and category
• Category: Filter by specific service category
• Status: Filter by service status (active/inactive/unknown)
• Sort By: Sort results by title, category, or status
• Sort Order: Choose ascending or descending order

Get information about a specific service:

dzdk services get --id <service_id_or_slug>

Service details include:

• Service title and description
• Category and status
• Location details (address, city)
• Contact information (email, phone)
• Operating hours
• Additional metadata

Events

List all events with key information:

# Basic list (12 items per page)
dzdk events list

# Navigate to specific page
dzdk events list --page 2

# Search and filter with pagination
dzdk events list --search "workshop" --category "education" --page 1

# Sort with pagination
dzdk events list --sort-by date --sort-order desc --page 1

Get detailed information about a specific event:

dzdk events get --id <event_id_or_slug>

Event details include:

• Title and description
• Date and time
• Location
• Registration information
• Contact details
• Tags and categories

Photos

List all available photos:

# Basic list (12 items per page)
dzdk photos list

# Navigate to specific page
dzdk photos list --page 2

# Search and filter with pagination
dzdk photos list --search "camp" --category "events" --page 1

# Sort with pagination
dzdk photos list --sort-by date --sort-order desc --page 1

Get information about a specific photo:

dzdk photos get --id <photo_id_or_slug>

Photo details include:

• Title and description
• Date taken
• Photographer information
• Location
• Tags and categories
• Image metadata (size, format)
• Download URL

Upload a photo to the archive:

dzdk photos upload --file path/to/image.jpg --title "Photo Title" --description "Optional description"

Edit photo metadata:

dzdk photos edit --id <photo_id> --title "New Title" --description "New Description" --tags "tag1,tag2" --location "New Location" --date "2024-03-20"

View detailed photo metadata:

dzdk photos metadata --id <photo_id>

Photo Albums

Create a new album:

dzdk photos album create --name "My Album" --description "Album Description" --tags "tag1,tag2"

Add photos to an album:

dzdk photos album add --album-id <album_id> --photo-ids "photo1,photo2,photo3"

List all albums:

dzdk photos album list

Features:

• Album creation and management
• Photo organization
• Tag-based categorization
• Rich metadata display
• Batch photo operations
• Technical metadata viewing
• Location and date tracking

Population

Get comprehensive population statistics:

dzdk population stats

Get specific demographic information:

dzdk population get --category <demographic_category>

Available categories:

• age_groups
• nationalities
• gender
• new_arrivals
• historical_trends

Statistics include:

• Total population
• New arrivals
• Demographics breakdown
• Nationality distribution
• Historical trends

Resources

List all available resources:

# Basic list (12 items per page)
dzdk resources list

# Navigate to specific page
dzdk resources list --page 2

# Search and filter with pagination
dzdk resources list --search "report" --category "research" --page 1

# Sort with pagination
dzdk resources list --sort-by date --sort-order desc --page 1

Get detailed information about a specific resource:

dzdk resources get --id <resource_id_or_slug>

Resource information includes:

• Title and description
• Author and date
• File type and size
• Available languages
• Download URLs
• Version history
• Related resources

Download a resource:

dzdk resources fetch --id <resource_id_or_slug> --output filename.pdf

Search

Search across all resources with filtering and relevance sorting:

# Search across all content types
dzdk search --query "education"

# Search only in services
dzdk search --query "health" --type services

# Search with a custom result limit
dzdk search --query "event" --limit 20

Features:

• Cross-resource search
• Type filtering
• Relevance sorting
• Result limiting
• Rich output formatting

Batch Operations

Download multiple resources or photos in batch:

# Download multiple resources
dzdk batch download --type resources --ids "id1,id2,id3" --output-dir downloads

# Download multiple photos
dzdk batch download --type photos --ids "photo1,photo2" --output-dir photos

Features:

• Parallel downloads
• Progress tracking
• Error handling
• Automatic directory creation

Upload multiple photos from a directory:

# Upload all photos from a directory
dzdk batch upload --type photos --directory ./my_photos

Features:

• Batch processing
• File validation
• Progress tracking
• Error handling

Export

Export data to CSV format:

# Export services to CSV
dzdk export csv --type services --output services.csv

# Export population data to CSV
dzdk export csv --type population --output population.csv

Features:

• Flattened data structure
• Preserved metadata
• Proper CSV formatting

Generate detailed markdown reports:

# Generate a services report
dzdk export report --type services --output services_report.md

# Generate a population report
dzdk export report --type population --output population_report.md

Features:

• Comprehensive summaries
• Detailed item information
• Formatted markdown output
• Timestamps and metadata

Interactive Shell

Start an interactive shell session with command history and tab completion:

dzdk shell

Features:

• Command history persistence
• Tab completion for commands
• Command suggestions based on history
• Rich output formatting
• Built-in help system
• Screen clearing
• Easy command execution

Example shell session:

(dzdk) help
(dzdk) services list
(dzdk) photos upload --file photo.jpg --title "My Photo"
(dzdk) search --query "education"
(dzdk) clear
(dzdk) exit

Shell Commands:

• help [command]: Show help information
• clear: Clear the terminal screen
• exit: Exit the shell
• All regular CLI commands are available

---

Output Formatting

The CLI uses the Rich library to provide beautiful, colorized output:

• Tables: Organized data presentation with color-coded columns
• Panels: Detailed information in bordered boxes
• Progress Bars: Visual feedback for long-running operations
• Status Indicators: Color-coded success/error messages
• Visualizations: Bar charts and graphs for data representation
• Search Results: Formatted panels with type-specific details

---

Development

Adding New Features

1. Follow the existing code structure
2. Add proper error handling
3. Include progress indicators for long operations
4. Add appropriate documentation
5. Update the README with new commands

Testing

1. Run the test suite: pytest
2. Test new features thoroughly
3. Verify error handling
4. Check output formatting

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Update documentation
6. Submit a pull request

---

License

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

---

Contact

For questions or support, please contact:

• Email: [e-mail]
• Website: https://services.dzaleka.com