CLI Installation

The OpenChoreo CLI (occ) is the command-line interface for managing OpenChoreo resources, projects, and deployments.

Installation

Download and install the latest development build from GitHub:

macOS (Apple Silicon)

curl -L https://nightly.link/openchoreo/openchoreo/workflows/build-and-test/main/occ.zip -o occ.zip && \
unzip occ.zip && \
sudo mv darwin/arm64/occ /usr/local/bin/ && \
rm -rf occ.zip darwin linux

macOS (Intel)

curl -L https://nightly.link/openchoreo/openchoreo/workflows/build-and-test/main/occ.zip -o occ.zip && \
unzip occ.zip && \
sudo mv darwin/amd64/occ /usr/local/bin/ && \
rm -rf occ.zip darwin linux

Linux (x64)

curl -L https://nightly.link/openchoreo/openchoreo/workflows/build-and-test/main/occ.zip -o occ.zip && \
unzip occ.zip && \
sudo mv linux/amd64/occ /usr/local/bin/ && \
rm -rf occ.zip darwin linux

Linux (ARM)

curl -L https://nightly.link/openchoreo/openchoreo/workflows/build-and-test/main/occ.zip -o occ.zip && \
unzip occ.zip && \
sudo mv linux/arm64/occ /usr/local/bin/ && \
rm -rf occ.zip darwin linux

Verify Installation

occ version

Login

After installing the CLI, configure the OpenChoreo control plane URL and authenticate to start managing resources.

Configure Control Plane

Set the OpenChoreo API server endpoint:

occ config controlplane update default --url https://api.<your-domain>

For example, if you followed the On Your Environment guide using nip.io domains, the URL uses the CP_BASE_DOMAIN variable exported in Step 3:

occ config controlplane update default --url https://api.${CP_BASE_DOMAIN}

For local k3d setups, the URL is http://api.openchoreo.localhost:8080. Add the following entries to your /etc/hosts file:

127.0.0.1       api.openchoreo.localhost
127.0.0.1       thunder.openchoreo.localhost
127.0.0.1       observer.openchoreo.localhost

Self-Signed TLS Certificates

If your OpenChoreo setup uses self-signed certificates (the default for the On Your Environment guide), the CLI will fail with certificate verification errors like x509: certificate is not trusted. You need to trust the CA certificate on your machine.

Extract the CA certificate from your cluster:

kubectl get secret openchoreo-ca-secret -n cert-manager \
  -o jsonpath='{.data.ca\.crt}' | base64 -d > openchoreo-ca.crt

macOS

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain openchoreo-ca.crt

Linux

sudo cp openchoreo-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Windows

# Run as Administrator
Import-Certificate -FilePath .\openchoreo-ca.crt -CertStoreLocation Cert:\LocalMachine\Root

Authenticate

Login to OpenChoreo using the web browser:

occ login

This opens a browser window for authentication. Use the default credentials:

Username	Password
admin@openchoreo.dev	Admin@123

Verify

After login, confirm you can reach the API and list resources:

# List namespaces
occ namespace list

# List projects
occ project list -n default

# List components in the default project
occ component list -n default

See Also

• CLI Reference: CLI Reference