Skip to main content

​
First steps

After installing DZDK, you’re ready to start exploring the Dzaleka Digital Heritage resources.
1

Check API health

Verify that DZDK can connect to the API:
dzdk health
This command checks all API endpoints and displays their status, response times, and any errors.
2

View your configuration

See your current DZDK settings:
dzdk show-config
This displays:
  • API URL
  • Request timeout
  • Configuration file location
  • Last modified timestamp
3

List available services

Browse services in the Dzaleka camp:
dzdk services list
This shows the first page of services (12 per page) with details like title, category, contact information, and status.

​
Common workflows

​
Browsing services

List all services with pagination: 
# View first page
dzdk services list

# Navigate to page 2
dzdk services list --page 2
Search for specific services: 
# Search by keyword
dzdk services list --search "health"

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

# Filter by status
dzdk services list --status active
Combine filters for refined results: 
dzdk services list --search "clinic" --category "medical" --status active
Get detailed information about a specific service: 
dzdk services get --id <service_id_or_slug>
Service details include contact information, operating hours, location, social media links, and more.

​
Working with events

List upcoming events: 
dzdk events list
Search and filter events: 
# Search for workshops
dzdk events list --search "workshop"

# Filter by category
dzdk events list --category "education"

# Sort by date (descending)
dzdk events list --sort-by date --sort-order desc
View event details: 
dzdk events get --id <event_id_or_slug>
Event details include:
  • Title and description
  • Date and time (start and end)
  • Location and organizer
  • Registration information
  • Contact details
  • Tags and categories

​
Managing photos

List photos from the archive: 
dzdk photos list
Upload a new photo: 
dzdk photos upload --file path/to/photo.jpg --title "Market Day" --description "Weekly market at Dzaleka"

dzdk photos upload --file photo.jpg --title "My Photo"
View photo metadata: 
dzdk photos metadata --id <photo_id>
Edit photo information: 
dzdk photos edit \
  --id <photo_id> \
  --title "New Title" \
  --description "Updated description" \
  --tags "community,event,culture" \
  --location "Dzaleka Camp" \
  --date "2024-03-20"

​
Creating photo albums

Create a new album: 
dzdk photos album create \
  --name "Cultural Events" \
  --description "Photos from cultural celebrations" \
  --tags "culture,events,community"
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

​
Accessing resources

List available resources: 
dzdk resources list
Search for specific resources: 
# Search by keyword
dzdk resources list --search "report"

# Filter by category
dzdk resources list --category "research"
Get resource details: 
dzdk resources get --id <resource_id_or_slug>
Download a resource: 
dzdk resources fetch --id <resource_id> --output report.pdf

​
Interactive shell

For a more interactive experience, use the DZDK shell: 
dzdk shell
The shell provides:
  • Command history (persistent across sessions)
  • Tab completion for commands
  • Auto-suggestions based on history
  • Rich output formatting
Example shell session: 
(dzdk) services list --search "health"
(dzdk) events list --page 2
(dzdk) photos upload --file photo.jpg --title "My Photo"
(dzdk) help services
(dzdk) clear
(dzdk) exit
Shell history is stored at ~/.config/dzdk/history and persists across sessions.
Search across all resource types: 
# Search everything
dzdk search --query "education"

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

# Limit results
dzdk search --query "event" --limit 20
The search command returns results from:
  • Services
  • Events
  • Photos
  • Resources
  • Population data

​
Batch operations

Download multiple items at once: 
# 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,photo3" \
  --output-dir photos
Upload multiple photos from a directory: 
dzdk batch upload --type photos --directory ./my_photos
Photo files must be under 10MB in size. Supported formats include JPEG, PNG, and other common image formats.

​
Export and reporting

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

# Export population data
dzdk export csv --type population --output population.csv
Generate detailed markdown reports: 
# Generate services report
dzdk export report --type services --output services_report.md

# Generate population report
dzdk export report --type population --output population_report.md
Reports include:
  • Comprehensive summaries
  • Detailed item information
  • Formatted tables and statistics
  • Timestamps and metadata

​
Pagination

All list commands support pagination (12 items per page): 
# View specific page
dzdk services list --page 2

# Navigate with filters
dzdk events list --search "workshop" --page 3

# Combine with sorting
dzdk photos list --sort-by date --sort-order desc --page 1
After each list command, you’ll see navigation help: 
╭─────────────────────────────────────────╮
│ Navigation Help                         │
├─────────────────────────────────────────┤
│ Navigation Commands:                    │
│ • To view next page: dzdk services list --page 2
│ • To view previous page: dzdk services list --page 1
│ • To view specific page: dzdk services list --page <number>
│                                         │
│ Showing services 1-12 of 45            │
╰─────────────────────────────────────────╯

​
Getting help

Get help for any command: 
# General help
dzdk --help

# Command-specific help
dzdk services --help
dzdk services list --help
dzdk photos upload --help
Show the welcome screen: 
dzdk
This displays:
  • All available commands
  • Usage examples
  • Quick reference guide

​
Common options

Most list commands support these options:
  • --search <query> - Search by keyword
  • --category <category> - Filter by category
  • --status <status> - Filter by status (active/inactive/unknown)
  • --sort-by <field> - Sort by field (title/category/status)
  • --sort-order <order> - Sort order (asc/desc)
  • --page <number> - Page number for pagination
Example combining all options: 
dzdk services list \
  --search "medical" \
  --category "health" \
  --status active \
  --sort-by title \
  --sort-order asc \
  --page 1

​
Next steps

Configuration

Customize DZDK settings and behavior

Command Reference

Explore all available commands in detail

​
Tips and tricks

Use aliases: Create shell aliases for frequently used commands:
# Add to your ~/.bashrc or ~/.zshrc
alias dzl="dzdk services list"
alias dze="dzdk events list"
alias dzp="dzdk photos list"
Pipe output: Combine DZDK with other command-line tools:
# Export and process with other tools
dzdk export csv --type services --output - | grep "medical"
Environment variables: Override config directory location:
export DZDK_CONFIG_DIR="/path/to/custom/config"
dzdk show-config