Quick start

A cpak package is addressed by its Git repository. The repository contains the package contract, while its manifest points to the OCI image that contains the application.

Check the runtime

cpak doctor

Resolve required failures before continuing. Warnings describe optional host features that cpak cannot apply on the current system.

Install an application

Install a package directly from its origin:

cpak install github.com/bottlesdevs/bottles

cpak resolves the repository reference, validates cpak.json, downloads missing image layers by digest, installs declared dependencies, and commits the package record only after the staged data is ready.

Packages can follow a branch or release, or remain pinned to a commit:

cpak install --branch main github.com/bottlesdevs/bottles
cpak install --release v1.0.0 github.com/example/app
cpak install --commit 0123456789abcdef github.com/example/app

Run it

The command accepts the package origin and an optional exported binary:

cpak run github.com/bottlesdevs/bottles bottles

Arguments after the binary are passed to the application as an argument vector:

cpak run github.com/example/editor editor ./notes.txt

Create an alias for a shorter local command:

cpak alias set bottles github.com/bottlesdevs/bottles
cpak run bottles bottles

Inspect the installation

cpak list
cpak list --json
cpak logs github.com/bottlesdevs/bottles

cpak shell opens an interactive shell inside the installed package. It receives the same package layers and configured mounts, which makes it useful for diagnosis.

Update safely

cpak update github.com/bottlesdevs/bottles
cpak update

If an update requests new permissions, the interactive command shows the additions before applying it. Automation can reject such changes with cpak update --non-interactive.

Restore the previous installed version when an update needs to be reverted:

cpak rollback github.com/bottlesdevs/bottles

Remove it

cpak remove github.com/bottlesdevs/bottles

The command finds the sole installed branch, release, or commit and stops its containers before removal. If more than one copy is installed, select one with --branch, --release, or --commit.

Normal removal keeps the application's private home and persistent file grants. Use cpak remove --purge github.com/bottlesdevs/bottles when those should be deleted too. Host files exposed through filesystem permissions are never deleted. Garbage collection remains available for unused shared storage and download cache:

cpak gc --apply

Continue with cpak concepts to understand how origins, images, state, and permissions fit together.