LinuxCommandLibrary

finch

Build, run, and manage container images

TLDR

Launch finch

$ finch
copy

Quit
$ [<Alt q>|<Ctrl c>]
copy

Show actions menu
$ <Alt a>
copy

Jump to n-th window
$ <Alt [Number]>
copy

Close current window
$ <Alt c>
copy

Start moving a window, use to move, press when done
$ <Alt m>
copy

Start resizing a window, use to resize, press when done
$ <Alt r>
copy

SYNOPSIS

finch [OPTIONS] COMMAND [ARG...]

Examples:
finch run alpine echo hello
finch build -t myimage .
finch ps -a

PARAMETERS

--debug
    Enables debug logging for detailed output during command execution.

-h, --help
    Displays help information for the finch command or a specific subcommand.

--version
    Shows the installed finch version information.

Common 'run' options:
    Subcommands like 'run' have their own specific options. For example, -d (detach), -p (publish ports), --name (assign a name), --rm (auto-remove on exit), and -v (bind mount volume).

Common 'build' options:
    Subcommands like 'build' also have specific options. For example, -t (tag the image) and -f (specify Dockerfile path).

DESCRIPTION

finch is a command-line interface (CLI) client designed for building, running, and managing Linux containers in local development environments, particularly on macOS and Windows.

It serves as a lightweight alternative to tools like Docker Desktop for certain use cases, focusing on simplicity and efficiency. finch leverages a stack of well-established open-source components: containerd as the core container runtime, nerdctl as the CLI for interactions with containerd, and Lima to provision and manage a minimal Linux virtual machine where the containers execute. This architecture provides a familiar Docker-like user experience while being resource-efficient.

finch supports standard Dockerfile syntax, enabling seamless integration of existing container projects. It simplifies the setup of a local container environment, offering essential commands for image building, container execution, and lifecycle management, making it highly beneficial for developers who need to run Linux containers without the overhead of larger container platforms.

CAVEATS

finch relies on a virtual machine (Lima) to run Linux containers on macOS and Windows, which adds an abstraction layer and consumes system resources for the VM itself.

While highly compatible with Dockerfile syntax and many Docker CLI commands, it may not support every single feature or advanced orchestration capability found in a full Docker installation or dedicated orchestration tools.

Its primary focus is on local development environments rather than production deployments or complex multi-host container orchestration.

ARCHITECTURE

finch operates on a layered architecture. The finch CLI acts as a user-friendly frontend that translates commands to nerdctl. nerdctl then communicates with containerd, which is the core container runtime. On macOS and Windows, containerd runs inside a lightweight Linux virtual machine managed by Lima. This setup isolates the container environment and provides a native Linux kernel for container execution.

INSTALLATION

finch can be installed using platform-specific package managers. On macOS, it's commonly installed via Homebrew (brew install finch). For Windows, an installer is typically provided. It includes all necessary dependencies like containerd and Lima, simplifying the setup process for developers.

HISTORY

finch was introduced by Amazon Web Services (AWS) in late 2022 as an open-source project. Its development aimed to provide a lightweight, open-source alternative for local container development, especially for users within the AWS ecosystem or those seeking a more resource-efficient solution compared to existing container desktop environments.

It was designed to leverage mature open-source projects like containerd, nerdctl, and Lima, demonstrating a commitment to open standards and community collaboration. Since its release, finch has continued to evolve with ongoing development and contributions from the community.

SEE ALSO

docker(1), nerdctl(1), containerd(1), ctr(1), buildah(1)

Copied to clipboard