Qontract Development CLI

Qontract Development CLI supports your daily qontract-reconcile development work.

• Recommended Installation Method
• Alternative Installation Methods
• Quickstart
• Features
• Examples
• Usage
  • Let your coding agent check an integration
  • Config
    • Global Settings
  • Environments
    • Environment Settings
  • Profiles
    • --no-dry-run
    • Profile Settings
  • Connecting your IDE to QR
  • PR/MR support
• Development
  • Release

Recommended Installation Method

The recommended way to install qontract-development-cli is to use the uv tool:

uv tool install qontract-development-cli

and upgrade an existing installation with:

uv tool upgrade qontract-development-cli

Alternative Installation Methods

You can install this library from PyPI with pip:

python3 -m pip install qontract-development-cli

or install it with pipx:

pipx install qontract-development-cli

and upgrade an existing installation with:

pipx upgrade qontract-development-cli

Quickstart

• Create initial configuration

  qd config init
  

  

• Create a profile sql-query to run the sql-query integration

  qd profile create sql-query
  

  

• Run sql-query profile

  qd profile run dev sql-query
  

  

Features

Qontract Development CLI currently provides the following features (get help with -h or --help):

• Run qontract-reconcile and qontract-server as docker containers on your local machine
• Support for different App-Interface environments (dev, prod, ...) via the env command
• Configure your qontract-reconcile integration with the profile command
• Support pull request reviews (see profile create)
• Bootstrap your initial configurations with the config command
• Shell auto-completion (see qd --help)
• Automatically restart qontract-reconcile container when files change
• Automatically rebuild the App-Interface bundle and restart the qontract-server container when files change

Examples

Take a look at the examples directory for different profile examples.

Usage

The following sections describe all available commands, their options and use-cases.

Let your coding agent check an integration

Your coding agent can set up qd and check integrations against real configuration using your local code—without attaching an IDE debugger or watching logs yourself.

Enable agent support once:

qd agentic skill-install

Then ask your agent:

Help me set up qd for local integration development.

Or, when you're ready to test:

Use qd to dry-run automated-actions-config and summarize the results.

The agent asks for missing details and your approval, then reviews the complete output and reports failures or gaps in coverage.

Config

Manage global qontract-development-cli configuration.

qd config [sub-cmd] --help

• edit: open the configuration file in your favorite editor
• init: create a default configuration

Global Settings

Environments

An environment specifies app-interface instance settings, e.g., dev vs. prod config and path to the actual app-interface instance.

qd env [sub-cmd] --help

• edit: Create/edit an environment file in your editor.
• ls: List all available environments.
• rm: Remove environment.
• show: Display environment.

Environment Settings

👉 Bold keys are mandatory or should be customized.

Profiles

A profile specifies all settings to run a qontract-reconcile integration (e.g., sql-query).

qd profile [sub-cmd] --help

• create: Create a new profile to run an integration.

  Supports the creation of a new profile from an open PR/MR. See $ qd profile create --help for all available options.

• edit: Edit a profile in your editor.

• ls: List all available profiles.

• rm: Remove profile.

• run: Run a profile.

• show: Display profile.

For a non-interactive check, use --headless --output-dir PATH. qd starts the full configured stack, records the integration's output and exit status, then stops the whole stack. This replaces any running qd stack; volumes are retained. Images are reused. Use --force-rebuild when dependencies changed or images have not been built yet.

Use --no-skip-initial-make-bundle to refresh the bundle even when the profile normally skips it; the saved profile remains unchanged.

additional_environment intentionally allows overriding generated runtime settings, including DRY_RUN, MANAGER_DRY_RUN, RUN_ONCE, and DEBUGGER, even in headless mode. These overrides take precedence over the corresponding profile settings; headless dry-run and run-once settings are not guarantees when overridden.

--no-dry-run

By default, qd runs integrations in dry-run mode if not explicitly specified differently in the profile config. There is also a --no-dry-run flag which lets you disable dry-run mode from the command line.

qd profile run dev my-integration --no-dry-run

The command line flag takes precedence over any configuration you might have in the profile settings.

Profile Settings

👉 Bold keys are mandatory or should be customized.

Connecting your IDE to QR

Note that the Qontract Reconcile container will not start running until it is connected to by a debugger. You can use a config like this for VSCode:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python Debugger: Reconcile",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5678 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}", "remoteRoot": "/work" }
      ],
      "justMyCode": false,
      "autoReload": {
        "enable": true
      }
    },
    {
      "name": "Python Debugger: Api",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5679 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}", "remoteRoot": "/opt/app-root/src" }
      ],
      "justMyCode": false,
      "autoReload": {
        "enable": true
      }
    },
    {
      "name": "Python Debugger: Subscriber",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5681 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}", "remoteRoot": "/opt/app-root/src" }
      ],
      "justMyCode": true,
      "autoReload": {
        "enable": true
      }
    },
    {
      "name": "Python Debugger: Worker",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "localhost", "port": 5680 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}", "remoteRoot": "/opt/app-root/src" }
      ],
      "justMyCode": true,
      "autoReload": {
        "enable": true
      }
    }
  ],
  "compounds": [
    {
      "name": "Debug: Reconcile + qontract-api",
      "configurations": [
        "Python Debugger: Reconcile",
        "Python Debugger: Api",
        "Python Debugger: Subscriber",
        "Python Debugger: Worker"
      ],
      "stopAll": true,
      "presentation": {
        "hidden": false,
        "group": "Full Stack",
        "order": 0
      }
    }
  ]
}

Please note that development does not currently work with PyCharm as debugpy is not yet supported. This issue is being tracked here

PR/MR support

It's a pretty handy feature to create a profile from a pull request (merge request). E.g.:

qd profile create --app-interface PATH_TO_YOUR_LOCAL/app-interface-dev-data --app-interface-pr NUMBER --qontract-schemas-pr NUMBER --qontract-reconcile-pr NUMBER --integration-name glitchtip --integration-extra-args '' glitchtip-pr-check

Which results in this profile:

$ qd profile show glitchtip-pr-check
---
app_interface_path: PATH_TO_YOUR_LOCAL/app-interface-dev-data
app_interface_pr: NUMBER
integration_name: glitchtip
qontract_reconcile_pr: NUMBER
qontract_schemas_pr: NUMBER

Running this profile will:

• Create new git worktrees (see config.worktrees_dir) for app-interface-dev-data, qontract-schema, and qontract-reconcile PRs
• Start the containers with the adapted path to these worktrees
• Restarting the profile will fetch PR updates

👉 A git worktree cleanup isn't implemented yet

Development

Release

• Bump the version in pyproject.toml
• Update the CHANGELOG.md
• Commit the changes