home/docs/cli

CLI and `doctor`

Three commands. Most of the time your agent host runs sidekit mcp for you and you never type any of them — except doctor, which is the one to reach for when something is wrong.

Command	What it does
`sidekit doctor`	Diagnose the environment once and print a JSON report.
`sidekit mcp`	Serve MCP over stdio for a coding agent.
`sidekit run`	Run the daemon headless, without the MCP server.
`sidekit --help`	Print usage. `-h` works too.

Every command takes -w / --workspace <path> — see choosing the workspace.

sidekit doctor

Probes your environment and writes a structured report to stdout. Nothing is assumed: the SDK is resolved, the restore state is read, each test project is classified by the runner it would actually use, and the coverage collector is launched to see whether it is there.

shell

sidekit doctor

A healthy report — every check Ok, and ok: true at the end:

a real report, lightly trimmed

{
  "checks": [
    { "name": "sdk",           "status": "Ok", "detail": "10.0.103 (global.json requests 10.0.100)" },
    { "name": "workspace",     "status": "Ok", "detail": "/repo/Sidekit.slnx" },
    { "name": "discovery",     "status": "Ok", "detail": "10 project(s)" },
    { "name": "restore",       "status": "Ok", "detail": "10 project(s) restored." },
    { "name": "runner",        "status": "Ok", "detail": "6 test project(s): 0 MTP host, 6 dotnet test/VSTest." },
    { "name": "coverage",      "status": "Ok", "detail": "dotnet-coverage 18.8.0 — build the per-test map with …" },
    { "name": "git",           "status": "Ok", "detail": "Git working tree — select_tests reads the diff, …" },
    { "name": "index",         "status": "Ok", "detail": "/repo/.sidekit/index.db" },
    { "name": "file-watching", "status": "Ok", "detail": "Live file events available." }
  ],
  "ok": true
}

Exit code	Meaning
`0`	`ok: true` — no check failed. Warnings do not change this.
`1`	At least one check failed.

What each check means

Only two checks can fail. Without an SDK or a workspace there is nothing to be right about, so those stop everything. The other seven warn: Sidekit still works, with less resolution, and the warning names exactly what you lose.

Check	Worst case	What it means
`sdk`	Fail	The .NET SDK could not be resolved — usually `dotnet` is not on the `PATH` the process inherited.
`workspace`	Fail	No solution or project at the path given. Point `-w` at the repository root.
`discovery`	Warn	No buildable projects found, or the count on disk disagrees with what the solution declares.
`restore`	Warn	Some projects are not restored. Run `dotnet restore` — until then build truth is degraded.
`runner`	Warn	A test project has no recognised framework reference (xunit, NUnit, MSTest, TUnit, `Microsoft.NET.Test.Sdk`) or explicit `<IsTestProject>`, so its tests cannot be run.
`coverage`	Warn	`dotnet-coverage` is unavailable, so the per-test map cannot be built and answers stay at project resolution.
`git`	Warn	Not a git working tree, so `select_tests` has no diff to read and must be given files explicitly.
`index`	Warn	The index is not writable, so run history cannot persist: `get_flaky_tests` stays empty and selection never reaches file resolution.
`file-watching`	Warn	Live file events are unavailable — on Linux usually the inotify watch limit. The daemon falls back to polling; raise `fs.inotify.max_user_watches` to restore it.

Because it exits non-zero on failure, doctor drops straight into a shell conditional or a CI step. Run it in a terminal to tell a Sidekit problem from an agent-host environment problem: if it passes here and your host still reports a broken server, the difference is the host's PATH.

sidekit mcp

Serves the MCP tools over stdio, and runs a live daemon loop in the background: a filesystem watcher plus a periodic git working-tree reconcile — which catches branch switches and bulk external edits — keep queried projects' build state warm.

shell

sidekit mcp

stdout is reserved for the JSON-RPC protocol. All logging goes to stderr. If you wrap or pipe this command, do not let anything else write to stdout — it will corrupt the protocol stream.

You rarely run this by hand: your agent host spawns it. See Agent host recipes.

sidekit run

Starts the same daemon loop headless — watching the workspace, keeping tracked projects' build state warm — without the MCP server. Runs until interrupted (SIGINT / SIGTERM), draining cleanly.

shell

sidekit run

Choosing the workspace

Option	Default	Meaning
`-w`, `--workspace <path>`	current directory	The directory, solution or project to bind to.

The path is resolved to an absolute one at startup, so the process's working directory afterwards never affects which workspace it answers about.

Because sidekit mcp defaults to its launch directory, agent host configs need no absolute paths at all — which is what makes them committable. Pass -w only when the workspace is not the launch directory.

CLI and doctor

sidekit doctor

What each check means

sidekit mcp

sidekit run

Choosing the workspace

CLI and `doctor`