Serve

ghqc serve starts the local HTTP API that powers the ghqc web interface, but does not serve the frontend itself. Use it when you want API-only access for local tooling, tests, or frontend development against a separate dev server.

ghqc serve

Non-interactive

ghqc serve does not have an interactive mode. It binds an HTTP server immediately and keeps running until you stop the process.

ghqc serve

ghqc serve --port 3104 -d /path/to/project --config-dir /path/to/config

ghqc serve --ipv4-only

What It Exposes

The API router includes endpoints for:

repository health and repo status
milestone listing and milestone issue retrieval
issue creation, status lookup, and blocked-issue inspection
comment, review, approve, and unapprove actions
repository file browsing and content preview
record preview, PDF generation, and archive generation
configuration inspection and configuration repo setup

All routes are mounted under /api/....

OpenAPI Specification

Options

Flag	Description
`-p, --port`	Port to listen on. Defaults to `3103`.
`--ipv4-only`	Force an IPv4-only listener.
`-d, --directory`	Set the git project directory the API should operate on.
`--config-dir`	Override the configuration directory used by the API.

Build Features

ghqc serve is only available when the binary is built with the api feature and without the ui feature.

cargo build --features cli,api --release
./target/release/ghqc serve

If you build with cli,api,ui, the separate serve subcommand is omitted entirely and ghqc ui becomes the entry point for the combined API and frontend server.

That means the release binaries do not expose ghqc serve. To use it, you need a custom build without the ui feature.

Frontend Development

One common workflow is to run the API separately and point the UI dev server at it.

cargo run --features cli,api -- serve --port 3104

Then, in the ui/ directory of ghqctoolkit:

bun run dev

UI Command Run the combined embedded UI and API server instead of the API alone