kci-dev

Stand alone tool for Linux Kernel developers and maintainers to interact with KernelCI

Quickstart

Using PyPI and virtualenv

virtualenv .venv
source .venv/bin/activate
pip install kci-dev

Config file

kci-dev results can be used without a config file or KernelCI authorization token.

For other subcommands (like kci-dev bisect) is possible to create a default config file at
~/.config/kci-dev/kci-dev.toml with the following command:

kci-dev config

Shell Completions

kci-dev supports tab completion for bash, zsh, and fish shells. To enable completions:

Bash

# Add to ~/.bashrc
source /path/to/kci-dev/completions/kci-dev-completion.bash

Zsh

# Add to ~/.zshrc (make sure compinit is enabled)
fpath=(/path/to/kci-dev/completions $fpath)
autoload -U compinit && compinit

Fish

# Copy to fish completions directory
cp /path/to/kci-dev/completions/kci-dev.fish ~/.config/fish/completions/

After adding the appropriate lines, restart your shell or source your configuration file.

KernelCI authorization tokens

Authorizaton tokens can be requested here

Contributing to kci-dev

The kci-dev project welcomes, and depends on, contribution from developers and users in the open source community.
The Contributor Guide should guide you on how to contribute to kci-dev project.

Documentation

For latest informations check out the documentation here

Using kci-dev as a Python library

Python applications can import kci-dev directly instead of shelling out to the kci-dev command. This is useful for services such as mail clients, patchwork integrations, or websites that want to test kernel email patches and then submit or inspect KernelCI data.

Create a client

from kcidev import KernelCIClient

client = KernelCIClient(
    kcidb_rest_url="https://kcidb.kernelci.org/submit",
    kcidb_token="<token>",
)

The client also accepts the same config dictionary layout used by the CLI:

from kcidev import KernelCIClient
from kcidev.libs.common import load_toml

cfg = load_toml(".kci-dev.toml", "submit")
client = KernelCIClient(cfg=cfg, instance="staging")

If explicit credentials are not provided, KCIDB submission can also use the KCIDB_REST environment variable supported by the CLI.

Build and submit KCIDB build results

from kcidev import KernelCIClient

client = KernelCIClient(kcidb_rest_url="https://example.test/submit", kcidb_token="secret")

payload = client.build_kcidb_build_submission(
    origin="my-mail-ci",
    giturl="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
    branch="master",
    commit="0123456789abcdef0123456789abcdef01234567",
    tree_name="mainline",
    arch="x86_64",
    config_name="defconfig",
    compiler="gcc-14",
    status="PASS",
    log_url="https://ci.example.test/logs/0123456789abcdef",
    comment="Build triggered from an email patch series",
)

result = client.submit_kcidb(payload)

For applications that already have a checked-out git tree, git_folder can be used instead of manually passing giturl, branch, and commit:

payload = client.build_kcidb_build_submission(
    origin="my-mail-ci",
    git_folder="/srv/builds/linux",
    arch="arm64",
    config_name="defconfig",
    status="FAIL",
)

Use client.submit_build(...) to build and submit the payload in a single call.

Query KernelCI dashboard data

The library exposes Python methods for common dashboard requests and returns the JSON-compatible Python objects returned by the API:

summary = client.get_summary(
    origin="maestro",
    giturl="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
    branch="master",
    commit="0123456789abcdef0123456789abcdef01234567",
)

builds = client.get_builds(
    origin="maestro",
    giturl="https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git",
    branch="master",
    commit="0123456789abcdef0123456789abcdef01234567",
    arch="x86_64",
)

issues = client.get_issue_list(
    origin="maestro",
    start_date="2026-08-01T00:00:00Z",
    end_date="2026-08-08T00:00:00Z",
)

get_issue_list() defaults to the last 7 days. Pass days=N for a relative window, or both start_date and end_date for exact boundaries, without days. Date-only values use midnight UTC; timestamps must include a timezone. The CLI equivalent is kci-dev results issues --start-date ... --end-date ..., with optional --origin and --json (see issue commands).

To query a specific issue version, pass version to get_issue(), get_issue_builds(), or get_issue_tests():

issue = client.get_issue("maestro:<issue-id>", version=0)
builds = client.get_issue_builds(issue["id"], version=issue["version"])
tests = client.get_issue_tests(issue["id"], version=issue["version"])

Without version, issue details select the latest version; related-result queries select the latest version with incidents. Pass the returned detail version to keep all three queries consistent. Empty issue listings return {"issues": [], "extras": {}}, and unavailable extras return {"issues": {}}.

Run kci-dev subcommands from Python

For existing integrations that still need full CLI behavior, the public API can invoke the Click commands implemented under kcidev/subcommands/ without starting a shell process. Pass the same arguments you would pass after the kci-dev executable name and inspect the returned click.testing.Result:

from kcidev import run_command

result = run_command(["results", "summary", "--help"])
if result.exit_code != 0:
    raise RuntimeError(result.output)
print(result.output)

The same helper is available on KernelCIClient:

from kcidev import KernelCIClient

client = KernelCIClient()
result = client.run_command(["maestro", "results", "--help"])

Additional helper functions remain importable from kcidev.libs.* for advanced use cases, but new applications should prefer KernelCIClient for a stable, Click-free library interface. Library methods raise kcidev.KciDevError for recoverable kci-dev failures instead of aborting the process like the CLI. Use run_command when you specifically need command-compatible behavior from the modules in kcidev/subcommands/.

MCP server

kci-dev ships an MCP (Model Context Protocol) server so AI agents and automation tools can work with KernelCI data:

• query build, boot and test results, as well as known issues, from the dashboard
• compare results across checkouts of a tree
• inspect Maestro jobs
• retry jobs or trigger custom checkouts (with a token)

Tools that only read data are annotated as read-only, so MCP clients can require confirmation before the job-triggering ones run. The MCP server is experimental: tool names, parameters and response formats may change between releases.

MCP support is an optional extra:

pip install kci-dev[mcp]

MCP is an open protocol, so the server works with any MCP-capable client: Claude Code, Gemini CLI, VS Code Copilot, Cursor, or your own agent built on an MCP SDK. Run it over stdio and register it with your client, for example with Claude Code:

claude mcp add kernelci -- kci-dev mcp

Other clients are configured the same way: run kci-dev mcp as a stdio command, or start kci-dev mcp --transport http and point the client at the HTTP endpoint.

Then ask things like "which trees have results in KernelCI this week?" or "find the failing baseline boots on mainline and check whether they look flaky". Read-only dashboard tools work without any configuration; Maestro node lookup and job triggering use the api/pipeline URLs and token from your config file. See the full MCP documentation for the tool list, transports and examples.

License

LGPL-2.1