hawkbit-cli

Cross-platform (Linux/Windows) Python CLI for Eclipse hawkBit Management API.

References

• Eclipse hawkBit project: https://github.com/eclipse-hawkbit/hawkbit
• Eclipse hawkBit documentation: https://hawkbit.eclipse.dev/#/
• hawkbitgui (GUI inspiration/reference): https://github.com/sbabic/hawkbitgui

What this scaffold includes

• Typed CLI built with typer
• Management API client (targets, distributionsets, softwaremodules, rollouts)
• Optional local profile config (~/.config/hawkbit/config.json on Linux)
• Test suite with pytest + httpx.MockTransport
• Linting with ruff
• GitHub Actions CI workflow

Quick start

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows PowerShell

pip install -e .[dev]
hawkbit --help

Profile (optional)

hawkbit config set \
  --profile default \
  --management-url https://hawkbit.example.com \
  --username admin \
  --password admin \
  --no-verify-ssl

hawkbit config show --profile default -o table
hawkbit config path -o table
hawkbit config list -o table
hawkbit config use my-profile
hawkbit config current

After this, hawkbit targets list automatically uses the active profile (config use ...), or default if no active profile is set.

Commands

hawkbit targets list --profile default
hawkbit targets get <target-id> --profile default -o table
hawkbit targets delete-inactive --days 30 --dry-run --profile default -o table
hawkbit targets delete-inactive --by-inactive-flag --execute --profile default -o table
hawkbit target-filters list --profile default -o table
hawkbit target-filters create --name prod-filter --query 'name==prod-*'
hawkbit distributions list --profile default
hawkbit modules list --profile default
hawkbit modules delete <module-id> --profile default
hawkbit rollouts list --profile default
hawkbit rollouts create --name rollout-a --distribution-set-id 33 --target-filter-query 'name==prod-*'
hawkbit deployment get <target-id> --profile default -o table
hawkbit deployment history <target-id> --profile default -o table
hawkbit deployment progress <target-id> <action-id> --profile default -o table
hawkbit deployment assign <target-id> <distribution-id> --type forced
hawkbit deployment assign <target-id> --module-name my-fw --artifact ./firmware-update.fw --version 1.0.0
hawkbit deployment remove <target-id>
hawkbit distributions create --name my-dist --version 1.0.0
hawkbit distributions delete <distribution-id>
hawkbit distributions delete <distribution-id> --delete-modules

Without profile:

hawkbit targets list \
  --management-url https://hawkbit.example.com \
  --username admin \
  --password admin \
  --no-verify-ssl

Pretty table output:

hawkbit targets list \
  --management-url https://hawkbit.example.com \
  --username admin \
  --password admin \
  --no-verify-ssl \
  -o table

-o table is available on all commands that return data (config show, config path, config list, config current, targets list/get/delete-inactive, target-filters list/get/create/delete, distributions list, modules list, rollouts list/create, deployment get/history/progress/assign/remove, modules delete, distributions delete).

Default distribution flow

distributions create supports two modes:

1. Distribution-only mode (requires --name and --version)
2. Full flow mode when both --artifact and --module-name are provided

Full flow automates:

1. creating a software module
2. uploading the artifact to that module
3. creating a distribution set
4. associating the module to the distribution set

Behavior:

• Software module vendor defaults to hawkbit-cli
• Distribution set uses the same name and version as the software module

Distribution-only example:

hawkbit distributions create \
  --name my-distribution \
  --version 1.0.0

Full flow example:

hawkbit distributions create \
  --module-name my-firmware \
  --artifact ./firmware-update.fw \
  --version 1.0.0

Environment variables

HAWKBIT_MANAGEMENT_URL, HAWKBIT_USERNAME, HAWKBIT_PASSWORD, HAWKBIT_VERIFY_SSL

OIDC token authentication is also supported via --oidc-token or HAWKBIT_OIDC_TOKEN.

Development workflow

ruff check .
pytest

Documentation (MkDocs)

Install docs dependencies and preview locally:

pip install -e .[docs]
mkdocs serve

Strict documentation build:

mkdocs build --strict

Docs are published to GitHub Pages by .github/workflows/docs.yml.

Build a local standalone executable:

make build-binary
./dist/hawkbit --help   # Linux

CI binaries and releases

• CI builds standalone executables for Linux and Windows on each workflow run.
• Artifacts are available in the workflow run as:
  • hawkbit-linux-x86_64
  • hawkbit-windows-x86_64.exe
• Pushing a tag like v0.2.0 publishes those executable files directly as GitHub Release assets.

Docker and Kubernetes usage

Build a local image:

docker build -t hawkbit-cli:local .

Run commands from the container:

docker run --rm hawkbit-cli:local --help
docker run --rm hawkbit-cli:local targets list \
  --management-url https://hawkbit.example.com \
  --username admin \
  --password admin

This is useful in Kubernetes (for example in Job/CronJob) where the container executes a single hawkbit command and exits.