ebisi/polaris-cli repository overview

⁠polaris-cli

A Docker image that packages the Apache Polaris⁠ command-line interface, so you can run polaris commands without installing Python or the CLI locally.

Apache Polaris is a catalog service for Apache Iceberg. The CLI (published on PyPI as apache-polaris⁠) talks to a Polaris REST catalog server to manage catalogs, principals, roles, and grants. Full command and option reference: https://polaris.incubator.apache.org/in-dev/unreleased/command-line-interface/⁠

⁠Image overview

The Dockerfile uses a two-stage build on alpine:3.24.1:

1. build-stage — installs Python 3 and creates a virtualenv at /app/venv, then installs apache-polaris into it with pip using the pinned version from requirements.txt⁠ (currently 1.7.0).
2. runtime-stage — a fresh Alpine base with only python3 and curl, into which the populated virtualenv is copied from the build stage. It also downloads the official jq 1.8.2 Linux binary from the upstream release and verifies its SHA-256 checksum, so jq is available in the final image without relying on Alpine's vulnerable stable package.

PATH includes /app/venv/bin, so the polaris executable is available directly. The default CMD is /app/venv/bin/polaris -h.

There is no ENTRYPOINT, only CMD, so any arguments passed to docker run replace the default command entirely — you need to include polaris yourself when running commands (see examples below).

⁠Prerequisites

• Docker (or a compatible container runtime)

⁠Building the image

From the repository root:

docker build -t polaris-cli .

Optionally tag it for your own registry:

docker build -t <registry>/polaris-cli:<tag> .

Published images are built for both linux/amd64 and linux/arm64.

To build a multi-platform image yourself, use Docker Buildx and specify the different platforms:

docker buildx build --platform linux/amd64,linux/arm64 -t polaris-cli --load .

⁠Running the CLI

Show the CLI help (default command):

docker run --rm polaris-cli

Run any other polaris subcommand by specifying it explicitly, since it replaces the default CMD:

docker run --rm polaris-cli polaris --version
docker run --rm polaris-cli polaris catalogs list

⁠Connecting to a Polaris server

Most commands need connection details for a running Polaris server (host/port and authentication, e.g. an OAuth2 client ID/secret or access token). Pass these as CLI options per the CLI reference⁠, for example:

docker run --rm polaris-cli polaris \
  --host polaris.example.com --port 8181 \
  --client-id "$POLARIS_CLIENT_ID" --client-secret "$POLARIS_CLIENT_SECRET" \
  catalogs list

You can also run multiple commands in a bash shell, and make use of jq to parse JSON output:

POLARIS_CLIENT_ID=root
POLARIS_CLIENT_SECRET=s3cr3t
docker run --rm --env CLIENT_ID="$POLARIS_CLIENT_ID" --env CLIENT_SECRET="$POLARIS_CLIENT_SECRET" --env HOST="host.docker.internal" \
  polaris-cli bash -c "polaris --host host.docker.internal catalogs list" | jq

⁠License

Licensed under the Apache License, Version 2.0. See LICENSE⁠.