dzdk

A terminal client for Dzaleka Online Services: the community directory, news and open-data site for Dzaleka Refugee Camp in Dowa District, Malawi.

dzdk has two parts:

• A full-screen app: type dzdk and it opens, for browsing services, the Dzaleka Encyclopedia, events, jobs, news, resources and photos, with charts of population, needs, funding, activity and weather. Built with Textual and textual-plotext.
• Commands (dzdk services list, dzdk search, dzdk chart, dzdk export csv, and more) for quick lookups, scripts and data exports.

Both read the public, read-only Dzaleka Online Services API. It needs no account or API key.

Install

Requires Python 3.9 or later. To get a dzdk command that works in any terminal, install it as a tool with uv or pipx:

uv tool install dzdk        # or: pipx install dzdk

Then type dzdk to open the app.

Plain pip install dzdk also works inside a virtual environment.

To serve the app in a web browser as well as the terminal, install the serve extra:

pip install "dzdk[serve]"

From a clone of this repository:

git clone https://github.com/Dzaleka-Connect/dzdk-cli.git
cd dzdk-cli
python -m venv venv
source venv/bin/activate         # Windows: venv\Scripts\activate
pip install -e ".[dev]"

The app

dzdk

At a terminal, dzdk on its own opens the full-screen app, the same as dzdk tui. When its output is piped or used in a script, it prints an overview instead. dzdk help always prints the overview.

The app is designed for a window of about 140×42 characters. If yours is smaller, dzdk tui asks the terminal to grow the window (macOS Terminal, iTerm2 and xterm support this) and restores the original size when you quit. The layout also adapts to whatever size it gets, including when you resize the window while it runs:

• Below 110 columns, lists stack above their details, and the dashboard and charts use one column.
• On short windows, the header uses a smaller logo.
• [ and ] make the list pane narrower or wider. The width is saved.
• z zooms the focused pane, or a chart, to fill the window. Press it again to return.

dzdk tui --size 160x48       # grow to a different size
dzdk tui --no-resize         # never touch the window size
dzdk config --window-size off

Insights

The Insights tab draws charts from the API's open data. They are grouped into sub-tabs, and each group loads only when you open it.

The same charts print in an ordinary terminal with dzdk chart (see below).

Keys

The app ships with a dark and a light theme (dzaleka and dzaleka-light) and works with every built-in Textual theme. Change it with Ctrl+P → Change theme. Your choice is saved.

To run the app in a browser, for example on a shared computer:

dzdk serve --port 8000

Commands

Run dzdk help for an overview, or add --help to any command.

# Find things
dzdk search "legal aid"
dzdk search water --type encyclopedia --type resources
dzdk services list --search health
dzdk services list --category education --page 2
dzdk jobs list --status open --sort-by deadline
dzdk services get inua-advocacy
dzdk services open inua-advocacy          # opens the page in your browser

# The encyclopedia
dzdk wiki search water
dzdk wiki get dzaleka-refugee-camp
dzdk wiki list --category People

# Other collections: courses, artists, poets, marketplace and more
dzdk browse
dzdk browse poets

# Charts, printed in the terminal
dzdk chart --list
dzdk chart population-growth
dzdk chart --group Needs

# Live data
dzdk alerts
dzdk weather
dzdk population stats
dzdk stats overview

# Files and exports
dzdk resources fetch --id <id> --output report.pdf
dzdk export csv --type services --output services.csv
dzdk export all --output everything.json

Every list and detail command accepts --json for scripting:

dzdk jobs list --status open --json | jq '.[].title'

The full command reference is in doc.md.

Working offline

API responses are cached in ~/.config/dzdk/cache for five minutes by default. If the network drops, dzdk shows the last cached copy and says so. Items you viewed recently stay available on an unreliable connection.

dzdk config --cache-ttl 3600      # keep responses fresh for an hour
dzdk config --clear-cache
dzdk --no-cache services list     # always fetch fresh data

For AI assistants

Dzaleka Online Services also runs a read-only MCP server. dzdk mcp lists its tools and prints the setup command, for example for Claude Code:

claude mcp add --transport http dzaleka https://services.dzaleka.com/.well-known/mcp

Development

pip install -e ".[dev]"
pytest
uv tool install --editable . --force     # a global `dzdk` that runs your working copy
textual run --dev dzdk.tui.app:DzdkApp   # live CSS reloading while you edit dzdk/tui/dzdk.tcss

The code is split so that the command line and the app share everything except presentation:

On macOS, if your project is inside an iCloud-synced folder such as Documents, name the virtual environment venv rather than .venv. iCloud marks files inside dot-folders as hidden, and Python 3.13 ignores hidden .pth files, so an editable install stops working with ModuleNotFoundError: No module named 'dzdk'.

Tests mock the API with responses and drive the app with Textual's test pilot, so they run without network access.

Data and licence

Content comes from Dzaleka Online Services and is published under CC BY-SA 4.0 unless a page says otherwise. Attribute it to "Dzaleka Online Services" with a link to the source page. Photos and artworks may carry separate rights, so check the credit on each one. Community listings can be unverified; dzdk marks them.

The code is MIT licensed. See LICENSE.

Need urgent help? Go to https://services.dzaleka.com/get-help-now.