The current commands for packages, instances, development, storage, and system integration.

CLI reference

Run cpak <command> --help for the flags accepted by the installed build. The tables below describe the current user-facing command surface.

Package lifecycle

Command	Purpose
`install`	Install a package from a Git origin.
`run`	Install when needed, start the environment, and launch a binary.
`list`	List installed packages. Accepts `--json`.
`update`	Update one package or every installed package.
`rollback`	Restore the previous installed version.
`remove`	Remove one installed package and its owned runtime resources.
`extract`	Export a resolved package as a tar archive.
`alias`	Set, remove, or list local origin aliases.

Install, run, remove, stop, and shell accept branch, release, or commit selectors where applicable. Without a selector, remove uses the source of the sole installed copy. It refuses to choose when several copies of the same origin are installed.

cpak remove retains private application data and persistent file grants. Add --purge to delete them with the package. Host files mounted through filesystem permissions are outside the purge scope.

Running instances

Command	Purpose
`launch`	Launch a command in the active package environment.
`shell`	Open an interactive shell in a package instance.
`logs`	Print or follow instance output.
`stop`	Stop a running instance.
`ps`	List runtime, process, health, age, and listener state.
`status`	Show runtime state for one package or named instance.
`inspect`	Return complete runtime state as JSON.
`health`	Check runtime health and fail when it is not ready.
`service`	Manage persistent application services and boot restoration.
`orchestrate`	Start several applications with ordering, health checks, and retries.
`environment`	Manage named environments with persistent writable state.

Use --instance on supported commands to select a named instance of the same package.

cpak environment has its own create, list, inspect, shell, stop, delete, policy, permissions, processes, signals, signal, application-exports, export-application, and unexport-application actions. Read Persistent environments before using a distribution package as a mutable workspace.

cpak service provides enable, disable, remove, start, stop, restart, list, status, logs, setup, and restore. Read Persistent application services for declared commands, restart policies, dependencies, boot adapters, environment files, and secrets.

Package development

Command	Purpose
`init`	Generate a manifest v3 skeleton.
`validate`	Validate `cpak.json`.
`gen-schema`	Write the schema generated by the current runtime.
`migrate-manifest`	Convert a v1 manifest to v2.
`lock`	Resolve manifests and OCI images into `cpak.lock.json`.
`test`	Install and check a local package in a temporary store.
`dev`	Test a local package and launch its selected binary.

test and dev accept --origin for relative dependencies and --lock for an explicit lock file.

Composition and policy

Command	Purpose
`addon`	Inspect addons and slots, select providers, or change activation.
`override`	Replace one local permission value or edit the complete JSON.
`grant`	List, manage, or revoke persistent file grants.
`doctor`	Report host runtime capabilities.
`audit`	Check local store integrity and optionally repair it.

Use cpak addon slots and cpak addon providers to inspect provider state, then cpak addon use to select an exclusive provider. enable and disable remain available for explicit addon choices. JSON output is available for list, slots, and providers.

cpak update --non-interactive rejects updates that request additional permissions. JSON output is available for update, list, doctor, alias list, and garbage collection where shown by command help.

Storage

Command	Purpose
`storage`	Inspect, migrate, verify, or repair the active storage driver.
`dedup`	Deduplicate equal files below a selected path.
`gc`	Report or delete unreferenced layers and cache data.

Run cpak gc --json before cpak gc --apply when automating cleanup.

Runtime and registry access

Command	Purpose
`auth`	Bind private source and registry access to one package origin.
`completion`	Generate completion definitions for Bash, Zsh, or Fish.
`self-update`	Check for or install a newer official cpak binary.

Use cpak auth login, logout, list, or status to manage private package access. Read Private GitHub repositories and OCI registries before adding a separate token host.

Generate the definition for the active shell and load it through that shell's normal completion mechanism:

cpak completion bash > cpak.bash
cpak completion zsh > _cpak
cpak completion fish > cpak.fish

cpak self-update --check reports an available release and leaves the installed binary unchanged. Package-manager builds keep the version notice and delegate replacement to the system package manager. See Update the cpak runtime.

System integration and distribution

Command	Purpose
`system`	Install or inspect the system authority and its enforced policies.
`session`	Manage desktop and kiosk login sessions from installed packages.
`host-action`	Request one typed operation from an allowed host provider.
`discover`	Provide signed Store data and package actions to software centers.
`verify-signature`	Verify a publisher signature against one resolved package state.

discover is the machine interface used by software-center integrations. Use the normal install, remove, and Store interfaces for interactive package management. system and session may require Polkit confirmation; see System integration and Desktop and kiosk sessions.

cpak system provides setup, remove, and status for the system authority; read and write actions for enforcement, signatures, trust, and the permission ceiling; and explain and clear-removal for verified-launch recovery.

host-action is normally called by a package shim rather than by a person. Its provider, action, and arguments remain subject to the package's effective policy. See Host actions.