Configuration overview DZDK stores its configuration in a YAML file located at:
Linux/macOS : ~/.config/dzdk/config.yamlWindows : %USERPROFILE%\.config\dzdk\config.yaml
The configuration file is automatically created with default values on first run.
Default configuration When DZDK is first installed, it creates a configuration file with these defaults:
api_url : https://services.dzaleka.com/api timeout : 30
Configuration options API URL The base URL for the Dzaleka Digital Heritage API.
Key : api_urlType : StringDefault : https://services.dzaleka.com/apiExample : https://services.dzaleka.com/api
The API URL is automatically formatted to ensure it starts with https:// and ends with /api.
Request timeout Maximum time (in seconds) to wait for API responses before timing out.
Key : timeoutType : IntegerDefault : 30Range : 1-300 secondsExample : 30
Setting a very low timeout (< 5 seconds) may cause requests to fail on slower connections.
Viewing configuration Show current settings Display your current DZDK configuration:
This command displays:
╭─────────────────────────────────────────╮ │ Current Configuration │ │ Your CLI settings │ ╰─────────────────────────────────────────╯ ╭─────────────────────────────────────────╮ │ Configuration Details │ ├─────────────────────────────────────────┤ │ API Settings │ │ URL: https://services.dzaleka.com/api │ │ Timeout: 30 seconds │ │ │ │ Configuration File │ │ Location: /home/user/.config/dzdk/config.yaml │ Last Modified: 2024-03-20 14:30:15 │ ╰─────────────────────────────────────────╯
You can also use dzdk show_config (with underscore) as an alias.
Updating configuration Interactive mode Use interactive mode for a guided configuration experience:
dzdk config --interactive
This will:
Show your current configuration
Prompt you for the API URL (with current value as default)
Prompt you for the timeout (with current value as default)
Save the updated configuration
Display a confirmation message
Example session:
╭─────────────────────────────────────────╮ │ Interactive Configuration │ │ Configure your CLI settings │ ╰─────────────────────────────────────────╯ ╭─────────────────────────────────────────╮ │ Current Configuration │ ├─────────────────────────────────────────┤ │ API URL: https://services.dzaleka.com/api │ Timeout: 30 seconds │ ╰─────────────────────────────────────────╯ Enter API URL [https://services.dzaleka.com/api]: https://api.example.com Enter timeout in seconds [30]: 60 ╭─────────────────────────────────────────╮ │ Configuration Updated │ ├─────────────────────────────────────────┤ │ Configuration has been updated successfully! │ │ │ New Settings: │ │ API URL: https://api.example.com/api │ │ Timeout: 60 seconds │ ╰─────────────────────────────────────────╯
Command-line options Update specific settings using command-line flags:
Set API URL
Set timeout
Set both
dzdk config --url "https://services.dzaleka.com/api"
When setting the API URL via command line, DZDK automatically ensures it ends with /api.
Manual editing You can also edit the configuration file directly:
Locate the config file
# Linux/macOS nano ~/.config/dzdk/config.yaml # Windows notepad %USERPROFILE% \. config \d zdk \c onfig.yaml
Edit the values
api_url : https://services.dzaleka.com/api timeout : 30
Environment variables Custom config directory Override the default configuration directory location:
export DZDK_CONFIG_DIR = "/path/to/custom/config"
Example:
# Set custom directory export DZDK_CONFIG_DIR = " $HOME /my-dzdk-config" # DZDK will now use this directory dzdk show-config
The config file will be created at $DZDK_CONFIG_DIR/config.yaml.
Persistent environment variable Make the environment variable permanent:
Linux/macOS (bash)
Linux/macOS (zsh)
Windows (PowerShell)
# Add to ~/.bashrc or ~/.bash_profile echo 'export DZDK_CONFIG_DIR="$HOME/my-dzdk-config"' >> ~/.bashrc source ~/.bashrc
Configuration file structure The configuration file uses YAML format. Here’s the complete structure:
# API Configuration api_url : https://services.dzaleka.com/api # Base API URL timeout : 30 # Request timeout in seconds
DZDK automatically normalizes the API URL:
Ensures it starts with https:// (adds if missing)
Ensures it ends with /api (appends if missing)
Removes trailing slashes before adding /api
Examples of automatic formatting:
Input Normalized Output services.dzaleka.comhttps://services.dzaleka.com/apihttps://services.dzaleka.comhttps://services.dzaleka.com/apihttps://services.dzaleka.com/https://services.dzaleka.com/apihttps://services.dzaleka.com/apihttps://services.dzaleka.com/apihttps://services.dzaleka.com/api/https://services.dzaleka.com/api
Configuration validation DZDK automatically validates configuration values:
API URL validation
Must be a valid URL format
Automatically adds https:// if protocol is missing
Automatically adds /api suffix if missing
Timeout validation
Must be a positive integer
Recommended range: 5-300 seconds
Default is 30 seconds if invalid value provided
Testing configuration After updating your configuration, verify it works:
# Check API connectivity dzdk health
This command will:
Use your configured API URL
Apply your configured timeout
Test all API endpoints
Display response times and status
Successful output:
╭─────────────────────────────────────────╮ │ API Health Check │ │ Monitoring all endpoints │ ╰─────────────────────────────────────────╯ ┌────────────┬────────┬───────────────┬─────────┐ │ Endpoint │ Status │ Response Time │ Details │ ├────────────┼────────┼───────────────┼─────────┤ │ services │ ✓ │ 0.23s │ OK │ │ events │ ✓ │ 0.18s │ OK │ │ photos │ ✓ │ 0.21s │ OK │ │ population │ ✓ │ 0.19s │ OK │ │ resources │ ✓ │ 0.24s │ OK │ └────────────┴────────┴───────────────┴─────────┘ ✓ All endpoints are healthy
Troubleshooting Configuration file not found If the configuration file doesn’t exist:
# Run any DZDK command to auto-create it dzdk show-config
DZDK will automatically create the configuration directory and file with default values.
Invalid configuration values If you manually edit the config file and introduce errors:
# Reset to defaults rm ~/.config/dzdk/config.yaml # Linux/macOS dzdk show-config # Recreates with defaults
Connection failures If the health check fails after configuration:
Verify API URL
Ensure the API URL is correct.
Test connectivity
curl https://services.dzaleka.com/api/health
Verify you can reach the API directly.
Increase timeout
Try a longer timeout for slow connections.
Check network
Ensure you have internet connectivity and the API server is running.
Permission errors If you get permission errors accessing the config file:
# Fix permissions (Linux/macOS) chmod 600 ~/.config/dzdk/config.yaml # Or recreate the config directory rm -rf ~/.config/dzdk dzdk show-config
Advanced configuration Multiple environments Manage different configurations for different environments:
# Production config export DZDK_CONFIG_DIR = " $HOME /.config/dzdk-prod" dzdk config --url "https://services.dzaleka.com/api" # Development config export DZDK_CONFIG_DIR = " $HOME /.config/dzdk-dev" dzdk config --url "http://localhost:8000/api" # Switch between them as needed export DZDK_CONFIG_DIR = " $HOME /.config/dzdk-prod" dzdk health
Shell aliases Create aliases for different environments:
# Add to your shell configuration file alias dzdk-prod = 'DZDK_CONFIG_DIR="$HOME/.config/dzdk-prod" dzdk' alias dzdk-dev = 'DZDK_CONFIG_DIR="$HOME/.config/dzdk-dev" dzdk' # Usage dzdk-prod health dzdk-dev health
Backup and restore Backup your configuration:
# Backup cp ~/.config/dzdk/config.yaml ~/dzdk-config-backup.yaml # Restore cp ~/dzdk-config-backup.yaml ~/.config/dzdk/config.yaml
Configuration best practices Keep timeouts reasonable : Set timeout between 10-60 seconds. Too short causes failures, too long causes hanging.
Use environment variables for CI/CD : In automated environments, use DZDK_CONFIG_DIR to avoid conflicts.
Version control : If managing multiple configurations, keep them in version control but exclude sensitive data.
Security : The configuration file doesn’t currently store credentials, but if extended in the future, ensure proper file permissions (600 on Unix systems).
Next steps
Quick start Start using DZDK with common workflows
Command Reference Explore all available commands