conduitctl

conduitctl runs a local Conduit with one command and helps connect agents to it. It needs only Docker: the quickstart’s compose files are built into the binary, and the released, signed images are pulled.

Install

Download the archive for your platform from the latest release, check it, and put conduitctl on your PATH:

# Linux and macOS; pick linux|darwin and amd64|arm64
V=v0.2.0 OS=darwin ARCH=arm64
curl -LO https://github.com/tjscanlan/conduit/releases/download/$V/conduitctl_${V}_${OS}_${ARCH}.tar.gz
curl -LO https://github.com/tjscanlan/conduit/releases/download/$V/SHA256SUMS
curl -LO https://github.com/tjscanlan/conduit/releases/download/$V/SHA256SUMS.sigstore.json
cosign verify-blob SHA256SUMS --bundle SHA256SUMS.sigstore.json \
  --certificate-identity "https://github.com/tjscanlan/conduit/.github/workflows/release.yml@refs/tags/$V" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com   # optional, recommended
shasum -a 256 -c SHA256SUMS --ignore-missing
tar -xzf conduitctl_${V}_${OS}_${ARCH}.tar.gz && sudo mv conduitctl_${V}_${OS}_${ARCH}/conduitctl /usr/local/bin/

Or, with Go: go install github.com/tjscanlan/conduit/cmd/conduitctl@latest.

conduitctl ships with v0.2.0 and later (v0.1.0 has no binaries, and its images lack the quickstart’s conduit-init and conduit-demo-agent). From a checkout, make quickstart runs the same stack.

Commands

Command	What it does
conduitctl quickstart	Writes the compose bundle and generated secrets to ~/.conduit/quickstart, starts the stack, waits for health and the first demo trace, and prints the UI login and the CONDUIT_* settings for your agent. Running it again restarts with the same data and credentials.
conduitctl status	Shows the services, the login, and the settings again.
conduitctl agent-cert NAME	Issues a client certificate for agent NAME, signed by the quickstart’s CA, and prints how to use it. Valid existing certificates are kept.
conduitctl doctor	Checks Docker (running, Compose v2, at least 2 GiB of memory), free ports, every service’s health, the UI, the gateway (an mTLS call as my-agent), and that demo data reached ClickHouse. Each failure says what to do.
conduitctl down	Stops the stack, keeping data and credentials.
conduitctl reset	Stops the stack and deletes its data and credentials.
conduitctl version	Prints the version; images default to the same tag.

Flags (all commands): -dir (default ~/.conduit/quickstart), -ui-port (default 8080), -gateway-port (default 4317), -images (image tag; default is the CLI’s own version), and -no-demo (skip the simulated demo-agent).

Things to know

• Local evaluation only: the CA key sits next to the certificates it signs, and only 127.0.0.1 ports are opened. For anything shared, see Deployment.
• One local stack at a time: conduitctl and make quickstart run the same compose project (conduit-quickstart) and share its data volumes. So docker compose -p conduit-quickstart logs gateway works with either.
• Keep -dir under your home directory: Docker Desktop and Colima share only some host folders with containers, usually your home.
• Development builds: a conduitctl built from a checkout reports version dev and needs -images. scripts/build-quickstart-images.sh ci-local builds every image locally for -images ci-local; CI tests the CLI this way.