Use the devopspadctl command-line tool

devopspadctl is the command-line companion to the desktop app. It reads the same saved connections and the same local project directory, so scripts and AI coding agents can record builds and releases that then show up in the Infra console. It never changes a cluster, runs Docker or pushes images.

Install

Each GitHub release includes a signed and notarized devopspadctl-<version>-darwin-arm64.tar.gz for macOS on Apple silicon. Download it from the releases page, extract it and put devopspadctl on your PATH. On other platforms, build it from source:

go build -o build/bin/devopspadctl ./cmd/devopspadctl

See build from source for prerequisites.

Commands

devopspadctl release validate -f <spec.yaml>
devopspadctl runs record --project <dir> -f <event.json|->
devopspadctl runs list --project <dir>
devopspadctl runs get --project <dir> --id <run-id>
devopspadctl fleet list
devopspadctl cluster inspect --connection <name> --namespace <namespace>
devopspadctl cluster attach --connection <name> --namespace <namespace> --environment <name> [--project <dir>]
devopspadctl cluster attach --connection <name> --namespace <namespace> --environment <name> --application <name> --selector <labels> [--project <dir>]

cluster inspect and attach

cluster inspect reads the workloads in a namespace through a saved connection, read-only. cluster attach registers the discovered workloads into the local project under the given environment, like the Connect K3s wizard.

Add --application and --selector together to register an application that has no workload yet. That mode does not contact the cluster; it validates the saved connection and project and writes the mapping. Repeating an identical mapping is accepted; a conflicting one is rejected.

runs record, list and get

These implement the AI run records protocol. runs record accepts one JSON event from a file or from stdin (-f -):

devopspadctl runs record --project "$PROJECT" -f start.json
devopspadctl runs list --project "$PROJECT"
devopspadctl runs get --project "$PROJECT" --id d2123752-39ab-4ae6-9e87-8856419db18b

On success it prints the full run record as JSON and exits 0. A rejected record exits 1 with a JSON error on stderr. Bad arguments exit 2.

release validate

Checks a service.release.yaml spec locally: apiVersion: devopspad.release/v1, service and version format, image references pinned to a sha256 digest (:latest is always rejected), allowed workload kinds, file paths, Nginx file names, timeouts, and that the file contains no DSNs, private keys, kubeconfig bodies or shell substitution. It opens no SSH session and writes no record. Applying these specs to machines is planned but not implemented.

fleet list

Lists the fleets stored in fleet.json in the DevOpsPad config directory. Fleets group saved connections into machines with cluster or edge roles, up to 32 per fleet.

Choosing the project directory

When --project is omitted, devopspadctl uses, in order:

DEVOPSPAD_PROJECT_DIR
the project-path file in the DevOpsPad config directory (the folder you last chose in the app)
the default applications directory

DEVOPSPAD_CONFIG_DIR overrides the config directory, which on macOS is ~/Library/Application Support/DevOpsPad. The project must already exist; a wrong path never silently creates an empty project.

Frequently asked questions

Can devopspadctl deploy to my cluster?

No. It reads clusters, records runs and validates spec files. It does not run Docker, push images or change Kubernetes resources. Desktop releases happen in the Infra console.