Automation and services

Cpak commands return a failing exit status when the requested operation fails. Scripts should inspect exit status first and use JSON output where a command provides it.

Machine-readable status

cpak doctor --json
cpak list --json
cpak update --json
cpak gc --json
cpak alias list --json

Do not parse human tables. JSON fields are designed for status checks and automation.

Unattended updates

cpak update --non-interactive --json

The command refuses any update that requests additional permissions. It exits with an error when one or more package updates fail or are denied, while independent successful results remain visible in the output.

Run several applications

cpak orchestrate starts multiple installed applications and can express startup dependencies:

cpak orchestrate \
  --depends-on frontend=backend \
  --delay 2 \
  --retries 2 \
  backend frontend

Add --health when each started application can answer a health command. Use --ignore-errors only when later applications are safe to start after an earlier failure.

Service lifecycle

cpak service starts the local Cpak service. A user service manager can own it, but systemd is not required by the runtime. Other init systems can run the same command in the user's session.

Keep the service in the same user environment as desktop applications so display, audio, XDG paths, and the system broker resolve the intended session.

Logs and instances

Named instances let automation separate repeated launches of the same package:

cpak run --instance worker-a github.com/example/worker worker
cpak logs --instance worker-a --follow github.com/example/worker
cpak stop --instance worker-a github.com/example/worker

Capture the command exit status and logs around a failing run. Cpak propagates the child process result for commands that wait for the application.

CI package checks

Use cpak validate, cpak lock, and cpak test in package CI after the OCI image has been published. A package test should run through Cpak, not only through the image builder's container command.

Keep production image builds in CI. Local development commands are for package validation and visual testing, not a substitute for a signed multi-architecture publishing workflow.