Skip to main content
Version: v1.1.x

PaletteAI CLI

The paletteai CLI is a command-line tool for authoring and testing Definitions, inspecting Workload statuses, importing profile bundles downloaded from PaletteAI Studio, building air-gapped mirror bundles, and generating support bundles for troubleshooting. The CLI is useful for local development, CI/CD pipelines, and automation workflows.

Installation​

Prebuilt binaries are available for multiple platforms and architectures. Choose the appropriate binary for your system.

macOS​

info

At this time, the PaletteAI CLI binaries for macOS are not signed. Refer to Safely open apps on your Mac for instructions on trusting the PaletteAI binary.

Intel (AMD64)
curl --location --output paletteai https://docs.palette-ai.com/resources/assets/hosted/cli/darwin/amd64/paletteai
chmod +x paletteai
sudo mv paletteai /usr/local/bin/

Linux​

Linux AMD64
curl --location --output paletteai https://docs.palette-ai.com/resources/assets/hosted/cli/linux/amd64/paletteai
chmod +x paletteai
sudo mv paletteai /usr/local/bin/

Windows​

Windows AMD64
Invoke-WebRequest -Uri "https://docs.palette-ai.com/resources/assets/hosted/cli/windows/amd64/paletteai.exe" -OutFile "paletteai.exe"

Once downloaded, move the paletteai.exe binary either to a directory in your $PATH (for example, C:\Windows\System32) or add the current directory where it was downloaded to your $PATH.

RC Builds​

caution

RC builds are pre-release versions intended for testing upcoming features. They may contain bugs or breaking changes and are not recommended for production use.

RC builds are published alongside each release candidate and are available for the same platforms as stable releases. Replace paletteai with paletteai-rc in the filename if you want to keep both versions side by side.

macOS​

info

RC binaries for macOS are unsigned. Refer to Safely open apps on your Mac for instructions on trusting the binary.

Intel (AMD64) RC
curl --location --output paletteai https://docs.palette-ai.com/resources/assets/hosted/cli/darwin/amd64/paletteai?version=rc
chmod +x paletteai
sudo mv paletteai /usr/local/bin/

Linux​

Linux AMD64 RC
curl --location --output paletteai https://docs.palette-ai.com/resources/assets/hosted/cli/linux/amd64/paletteai?version=rc
chmod +x paletteai
sudo mv paletteai /usr/local/bin/

Windows​

Windows AMD64 RC
Invoke-WebRequest -Uri "https://docs.palette-ai.com/resources/assets/hosted/cli/windows/amd64/paletteai.exe?version=rc" -OutFile "paletteai.exe"

Once downloaded, move the paletteai.exe binary either to a directory in your $PATH (for example, C:\Windows\System32) or add the current directory where it was downloaded to your $PATH.

Verification​

Use the command paletteai --help to verify the CLI was installed.

paletteai --help
Example output
Usage:
  paletteai [command]

Available Commands:
  completion      Generate the autocompletion script for the specified shell
  convert-crd     Convert a CRD to a CUE template
  def             Manage Definitions
  dry-run         Dry Run a Workload and output the resulting K8s resources to stdout
  export          Export CUE template parameters to OpenAPI v3 schema
  help            Help about any command
  migrate         Dry runs migrations from old resource definitions to new resource definitions
  mirror          Mirror Profile Bundle content from source registries to air-gapped OCI registry (export, export-images, export-pack, push, or sync)
  status          Displays the status of each subresource of one or more workloads
  support-bundle  Generate a support bundle for a PaletteAI cluster (hub or spoke)
  studio          Manage Palette artifact studio artifacts
  version         Print the CLI version and the PaletteAI server component versions

Flags:
  -h, --help                help for paletteai
      --log-format string   Log output format (text or json) (default "text")
  -v, --verbosity int       Log verbosity level (0-10, where 0 is least verbose)

Use "paletteai [command] --help" for more information about a command.

Updates​

The CLI binaries are automatically updated with each PaletteAI release. To get the latest version, download it and replace your existing binary using the Installation instructions.

Global Flags​

The following flags are available on all commands.

FlagDefaultRequiredDescription
-h | --helpN/A❌Display help for any command.
--log-formattext❌Log output format. Accepted values: text, json.
-v | --verbosity0❌Log verbosity level (0-10, where 0 is least verbose).

Commands​

convert-crd​

Convert a Kubernetes Custom Resource Definition (CRD) to a PaletteAI CUE template. The generated template includes template and parameter blocks derived from the CRD's OpenAPI v3 schema, providing a starting point for authoring PaletteAI Definitions from existing CRDs.

Flags​

FlagDefaultRequiredDescription
-f | --fileN/A✅Path to the input CRD YAML file.
-o | --outputN/A❌Output CUE template file path. If omitted, the template prints to stdout.
--versionN/A❌CRD version to convert. If omitted, uses the first version in the CRD.

Examples​

# Convert a CRD and print to stdout
paletteai convert-crd --file /path/to/crd.yaml

# Convert a CRD and save to a file
paletteai convert-crd --file /path/to/crd.yaml --output /path/to/output.cue

# Convert a specific CRD version
paletteai convert-crd --file /path/to/crd.yaml --version v1alpha1

def​

Utility commands for working with PaletteAI Definitions.

def render​

Render a CUE-formatted Definition into Kubernetes YAML or JSON. Use this command to validate that a CUE Definition produces the expected Kubernetes manifests. If a directory is provided as input, all CUE Definitions in the directory are rendered.

Flags​
FlagDefaultRequiredDescription
--formatyaml❌Output format. Accepted values: yaml, json.
--messageN/A❌Header comment for the top of the rendered Definition. If empty, uses a default message.
-o | --outputN/A❌Output file path. If empty, prints to stdout. If input is a directory, the output path must be a directory as well.
--versionN/A❌Version string to set in the rendered Definition's spec.version.
Examples​
# Render a CUE Definition to stdout
paletteai def render my-webservice.cue

# Render to a file
paletteai def render my-webservice.cue --output my-webservice.yaml

# Render all CUE Definitions in a directory to another directory
paletteai def render ./defs/cue/ --output ./defs/yaml/

# Render as JSON
paletteai def render my-webservice.cue --format json

dry-run​

Dry-run a Workload locally and output the resulting Kubernetes resources to stdout. This renders a Workload using its referenced Definitions without applying anything to a cluster.

By default, the command connects to the cluster (via kubeconfig) to read feature flags. Use --offline to skip cluster connectivity and all validation steps.

Flags​

FlagDefaultRequiredDescription
--debugfalse❌Enable debug mode. When enabled, raw output is printed on manifest errors.
-d | --definitionN/A✅Path to a Definition file or a directory containing Definition files.
-f | --fileworkload.yaml✅Path to the Workload YAML file.
--k8s-minor-version32❌Kubernetes minor version to target when rendering resources.
-n | --workload-namespacedefault❌Namespace for the Workload.
--offlinefalse❌Run in offline/local mode. All cluster validation steps are skipped.
-x | --definition-namespacemural-system❌Namespace to load Definitions from.

Examples​

# Dry-run a Workload with a Definition directory
paletteai dry-run --definition ./definitions/ --file ./workload.yaml

# Dry-run in offline mode (no cluster connection needed)
paletteai dry-run --definition ./definitions/ --file ./workload.yaml --offline

# Dry-run with a custom namespace
paletteai dry-run --definition ./definitions/ --file ./workload.yaml --workload-namespace my-namespace

migrate​

Dry runs migrations from old resource definitions to new resource definitions.

By default, the command connects to the cluster through your kubeconfig and impersonates the system:serviceaccount:mural-system:hue service account, which the migrations require.

Flags​

FlagDefaultRequiredDescription
--dry-runtrue❌Dry run all migrations.
--listN/A❌List all migrations by name.

Examples​

# List all migrations by name
paletteai migrate --list

# Run all migrations in dry-run mode
paletteai migrate

# Trigger retry of all failed migrations through hue controller
paletteai migrate --dry-run=false

mirror​

Produces an air-gapped content bundle from a Helm chart (mirror export), from an explicit list of container images with no chart (mirror export-images), from a Palette Pack tarball that contains values.yaml with pack.content charts and images (mirror export-pack), or from a profile bundle (mirror pull). "Mirroring" refers to rendering templates with the Helm v3 API (for chart-based export), collecting container images, and optionally pushing charts, images, and—when applicable—the pack archive to an OCI registry. mirror pull mirrors the content declared in a profile bundle downloaded from Artifact Studio, without Helm templating.

Each bundle must contain at least one chart or image. For chart-based flows (mirror export and mirror sync), the tool always pulls the Helm chart and pulls every container image referenced by the rendered manifests when present. If the rendered manifests contain no pullable images (for example CRD-only charts), export succeeds with an empty images/ directory and mirror push uploads the chart only. You can also pass --extra-image zero or more times; each occurrence names one additional container image to pull into the same bundle (for example sidecars, init containers, or images not wired through chart values). Those images are included in bundle.json alongside manifest-derived images and are pushed with mirror push like any other bundle image. Similarly, --extra-chart pulls additional Helm charts into the same bundle; all chart sources share one --repo-* credential set (refer to mirror export). You can also pass --extra-repo to clone a Git tree and include it in the bundle as a Flux-compatible OCI artifact, or --extra-artifact to stage a local file or directory (for example a downloaded model) and push it as a generic OCI artifact. To mirror a Palette pack that is published in Artifact Studio, pass --extra-pack with the pack's content bundle URL; the tool downloads, validates, and stages the content bundle and, on push, uploads its constituent artifacts to the destination registry.

mirror export-images is the image-only path: it requires at least one --image and does not include a chart.

Many Palette packs can be downloaded from Artifact Studio. If every pack your deployment needs is available there, use --extra-pack to mirror it and you do not need mirror export-pack for pack acquisition. If you require a pack that is not available in Artifact Studio, obtain a Pack tarball from your Spectro Cloud representative and use mirror export-pack on a connected host, then mirror push toward your air-gapped registry, so the pack file and its declared dependencies are uploaded together.

Pack content bundles compared to Pack tarballs​

The two pack inputs are complementary rather than interchangeable, and differ in what they take and where they push. --extra-pack takes an Artifact Studio content bundle (the .zst download, by URL) and pushes its constituent OCI artifacts to {dest-registry}/packs/, so that the cluster profiles referenced by a profile bundle can resolve their packs. mirror export-pack takes a Palette Pack tarball (.tar / .tgz, from your Spectro Cloud representative) and pushes the tarball to spectro-packs/archive/ plus the charts and images it declares.

info

--extra-pack content is pushed under the packs/ subpath of --dest-registry (for example --dest-registry 10.0.0.1:30003/spectro-content puts pack content under 10.0.0.1:30003/spectro-content/packs/). This keeps it isolated from charts, images, and other bundle content. When you register the OCI pack registry in Palette, set the Endpoint field to the host (10.0.0.1:30003) and the Base Content Path field to the content path including the packs/ suffix (spectro-content/packs), so Palette finds the mirrored pack content.

Use a two-phase workflow when the connected host cannot reach the destination registry: use mirror pull to generate a content bundle, move the bundle across the air-gap, and then use mirror push.

Use mirror sync on a host that can reach both upstream chart and image registries and the destination OCI registry. It runs the same chart-based export as mirror export—including the same --extra-image, --extra-chart, --extra-repo, --extra-artifact, and --extra-pack flags—then pushes in one process. When given --profile-bundle, mirror sync runs mirror pull then mirror push instead of mirror export then mirror push, mirroring the bundle's declared content without Helm templating; in this mode the host must also reach every source the profile bundle references—including the Git repositories, artifact locations, and Artifact Studio pack downloads it declares—in addition to the chart and image registries and the destination. mirror sync does not accept a Pack tarball; for pack inputs you must run mirror export-pack and then mirror push.

HTTP(S) proxy​

All mirror commands use the standard Go net/http transport behavior. Outbound HTTP and HTTPS requests honor the following proxy environment variables: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (and lowercase variants such as http_proxy), as documented for net/http.ProxyFromEnvironment. This applies to all Helm chart pulls, container image pulls/pushes, and OCI chart pushes.

mirror export​

Deprecated

mirror export is deprecated. Use mirror pull with a profile bundle downloaded from Artifact Studio instead: it mirrors the bundle's charts and images directly, without Helm templating.

Arguments: BUNDLE_DIR — output directory for the bundle (must not already contain bundle.json).

Renders the chart, writes bundle.json, pulls the .tgz chart archive into charts/, and pulls each image referenced by the rendered manifests plus any --extra-image references into OCI image layout directories under images/ (preserving multi-architecture indexes). When the rendered manifests contain no pullable images, export still succeeds and produces a chart-only bundle (empty images/). It does not require the --dest-registry flag.

FlagShorthandDefaultRequiredDescription
--chart-url-cN/A✅Helm chart reference (oci://… or reponame/chart with --repo-url).
--chart-version-VN/A❌Chart version (required for classic repo charts when the version is not in the URL).
--repo-urlN/A❌Classic Helm repository index URL (same idea as helm --repo).
--repo-usernameN/A❌Username for --repo-url or for the oci:// chart registry.
--repo-passwordN/A❌Password for --repo-url or oci:// chart (prefer env PALETTEAI_MIRROR_REPO_PASSWORD).
--repo-ca-certN/A❌CA certificate file or PEM directory for TLS to --repo-url or the oci:// chart registry.
--repo-insecurefalse❌Skip TLS verification for --repo-url or the oci:// chart registry.
--repo-plain-httpfalse❌Use plain HTTP for the oci:// chart registry (no TLS; distinct from --repo-insecure).
--release-name-rN/A✅Helm release name used when templating.
--kube-version1.31.0❌Kubernetes version for offline helm template kubeVersion checks (must satisfy the chart’s Chart.yaml kubeVersion).
--values-fN/A❌Path to a values.yaml file for helm template.
--extra-imageN/A❌Additional container image to pull into the bundle (repeat the flag per image; use when images are omitted from templates or unresolved at template time).
--extra-chartN/A❌Additional Helm chart to pull into the bundle (repeat per chart): oci://registry/repo/chart:version or repo|name|version. Shares the --repo-* credentials (refer to the note below).
--extra-repoN/A❌Additional Git tree to mirror as a Flux OCI artifact (repeat per repository). Cloned with the host's git credentials (refer to the note below).
--extra-artifactN/A❌Additional local file or directory to stage and push as a generic OCI artifact (repeat per artifact): <path>[=<name>[:<tag>]].
--extra-packN/A❌Artifact Studio Pack content bundle to mirror (repeat per pack). The absolute http(s) download URL Artifact Studio provides. Pushed under {dest-registry}/packs/ preserving signatures.
--studio-usernameN/A❌Username for Artifact Studio (optional; not all packs require authentication).
--studio-passwordN/A❌Password for Artifact Studio (optional; prefer env PALETTEAI_MIRROR_STUDIO_PASSWORD).
--archiveN/A❌Write the bundle directory tree as .tar, .tar.gz, or .tgz instead of a directory; BUNDLE_DIR names the top-level folder in the archive.
Authentication for extra charts

The --repo-username, --repo-password, --repo-ca-cert, --repo-insecure, and --repo-plain-http flags apply to the primary --chart-url and every --extra-chart. Extra charts from authenticated registries must therefore use the same credentials as the primary chart (in practice, the same registry). To mirror charts from several different authenticated registries, run mirror export (or mirror sync) once per registry.

Authentication for extra repos

--extra-repo trees are cloned with the system git binary, which uses the host's git credentials. Configure git authentication on the host before mirroring private repositories.

Examples​

# Export a Helm chart from an OCI registry
paletteai mirror export ./my-bundle \
  --chart-url oci://docker.io/myorg/my-chart:1.2.3 \
  --release-name my-release

# Export a Helm chart from a classic Helm repository
paletteai mirror export ./my-bundle \
  --repo-url https://charts.example.com/index.yaml \
  --chart-url myvendor/my-chart \
  --chart-version 2.0.0 \
  --release-name my-release

# Include images not referenced by the chart templates (repeat --extra-image)
paletteai mirror export ./my-bundle \
  --chart-url oci://docker.io/myorg/my-chart:1.2.3 \
  --release-name my-release \
  --extra-image docker.io/library/redis:7 \
  --extra-image docker.io/library/busybox:1.36

# Pull additional Helm charts into the same bundle (repeat --extra-chart)
# All chart sources share one --repo-* credential set.
paletteai mirror export ./my-bundle \
  --chart-url oci://registry.example.com/charts/app:1.0.0 \
  --release-name app \
  --extra-chart oci://registry.example.com/charts/sidecar:1.2.0 \
  --extra-chart 'https://charts.example.com|metrics|2.3.0'

# Mirror Git trees (for example Kustomize manifests) as Flux OCI artifacts (repeat --extra-repo)
# Pushed to oci://<dest-registry>/manifests/kubeflow-manifests:v1.10.2
paletteai mirror export ./my-bundle \
  --chart-url oci://docker.io/myorg/my-chart:1.2.3 \
  --release-name my-release \
  --extra-repo https://github.com/kubeflow/manifests.git:v1.10.2

# Stage a local file or directory and push it as a generic OCI artifact
# Pushed to oci://<dest-registry>/artifacts/model:latest
paletteai mirror export ./my-bundle \
  --chart-url oci://docker.io/myorg/my-chart:1.2.3 \
  --release-name my-release \
  --extra-artifact ./stage/model

# Mirror an Artifact Studio Pack content bundle (repeat --extra-pack)
# Constituent artifacts are pushed under {dest-registry}/packs/ on push, preserving signatures.
paletteai mirror export ./my-bundle \
  --chart-url oci://docker.io/myorg/my-chart:1.2.3 \
  --release-name my-release \
  --extra-pack https://software.spectrocloud.com/artifact-studio/zst/vertex/4.8/4.8.48/cni-cilium-fips-1.19.1/cni-cilium-fips-1.19.1.zst \
  --extra-pack https://software.spectrocloud.com/artifact-studio/zst/vertex/4.7/4.7.0/edge-native-byoi-2.1.0/edge-native-byoi-2.1.0.zst

# Chart-only bundle (for example CRD-only charts with no container images)
paletteai mirror export ./crds-bundle \
  --chart-url oci://registry.example.io/charts/my-crds:1.0.0 \
  --release-name my-crds

mirror export-images​

Deprecated

mirror export-images is deprecated. Use mirror pull with a profile bundle downloaded from Artifact Studio instead; it mirrors all the images the bundle declares.

Arguments: BUNDLE_DIR — output directory for the bundle (must not already contain bundle.json).

Pulls each image you list into an OCI image layout under images/, writes bundle.json with no Helm chart and an empty charts/ directory. Does not use --chart-url, --release-name, or other chart templating flags. The resulting bundle is compatible with mirror push (chart and pack steps are skipped when the manifest lists none).

Does not use --dest-registry; run mirror push separately.

FlagDefaultRequiredDescription
--imageN/A✅Container image reference to pull (repeat the flag for each image; at least one required).
--archiveN/A❌Write the bundle directory tree as .tar, .tar.gz, or .tgz instead of a directory; BUNDLE_DIR names the top-level folder in the archive.
Examples​
# Image-only bundle (directory output)
paletteai mirror export-images ./agent-bundle \
  --image docker.io/library/redis:7 \
  --image docker.io/library/busybox:1.36

# Same, wrapped as a single archive for transfer across an air-gap
paletteai mirror export-images ./agent-bundle \
  --image docker.io/myorg/agent:1.0.0 \
  --image docker.io/library/alpine:3.20 \
  --archive /tmp/agent-images.tar.gz

mirror export-pack​

Arguments: PACK_TAR — path to a Palette Pack archive (.tar, .tar.gz, .tgz, or similar). BUNDLE_DIR — output directory for the bundle (must not already contain bundle.json when writing a directory).

Reads the shallowest values.yaml inside the pack (by path depth); nested files with the same name (for example under chart subdirectories) are ignored. Uses pack.content.images and pack.content.charts to pull image artifacts and chart .tgz files into the same bundle layout as mirror export. Copies the source pack archive into spectro-packs/archive/ and records OCI name and tag in bundle.json by parsing the pack tarball filename: the stem must match <name>-<semver> (for example nvidia-gpu-operator-ai-25.10.1.tar.gz yields repository name nvidia-gpu-operator-ai and tag 25.10.1 on push). There are no CLI flags to override that mapping.

Does not use --dest-registry; run mirror push separately.

FlagDefaultRequiredDescription
--repo-usernameN/A❌Username for oci:// chart registries listed in pack.content.charts.
--repo-passwordN/A❌Password for those registries (prefer env PALETTEAI_MIRROR_REPO_PASSWORD).
--repo-ca-certN/A❌CA certificate file or PEM directory for TLS to oci:// chart registries.
--repo-insecurefalse❌Allow plain HTTP and skip TLS verification for oci:// chart registries.
--archiveN/A❌Write the bundle directory tree as .tar, .tar.gz, or .tgz instead of a directory; BUNDLE_DIR names the top-level folder in the archive.
Examples​
# Build a bundle from a Pack tarball (directory output)
paletteai mirror export-pack ./nvidia-gpu-operator-ai-25.10.1.tar.gz ./my-bundle

# Same, wrapped as a single archive for transfer across an air-gap
paletteai mirror export-pack ./nvidia-gpu-operator-ai-25.10.1.tar.gz ./my-bundle \
  --archive /tmp/my-bundle.tar.gz

mirror pull​

Arguments: PROFILE_BUNDLE — path to a profilebundle.yaml file or a directory containing one. BUNDLE_DIR — output directory for the bundle (must not already contain bundle.json).

Reads a profile bundle downloaded from Artifact Studio and mirrors all the content it declares (images, charts, packs, repositories, and artifacts) into the same bundle layout as mirror export, without Helm templating. Does not require a destination registry. Copy the bundle directory (or the --archive tarball) across the air-gap and then run mirror push. mirror sync --profile-bundle performs the connected download and push in one step.

FlagDefaultRequiredDescription
--repo-usernameN/A❌Username for the http(s) or oci:// chart registries the profile bundle references.
--repo-passwordN/A❌Password for the http(s) or oci:// chart registries (prefer env PALETTEAI_MIRROR_REPO_PASSWORD).
--repo-ca-certN/A❌CA certificate file or PEM directory for TLS to the http(s) or oci:// chart registries.
--repo-insecurefalse❌Skip TLS certificate verification for oci:// chart registries (HTTPS; not plain HTTP).
--repo-plain-httpfalse❌Use plain HTTP for oci:// chart registries (no TLS; distinct from --repo-insecure).
--studio-usernameN/A❌Username for Artifact Studio pack downloads (optional; not all packs require authentication).
--studio-passwordN/A❌Password for Artifact Studio (prefer env PALETTEAI_MIRROR_STUDIO_PASSWORD).
--archiveN/A❌Write the bundle directory tree as .tar, .tar.gz, or .tgz instead of a directory; BUNDLE_DIR names the top-level folder in the archive.
--extra-imageN/A❌Additional container image to mirror beyond the images the profile bundle declares (repeat the flag per image). Useful for content selected at deploy time.
--extra-chartN/A❌Additional Helm chart to mirror beyond the charts the profile bundle declares: oci://registry/repo/chart:version, or repo|name|version for an http(s) Helm repo index (repeat the flag per chart). Shares the --repo-* credentials.
--extra-repoN/A❌Additional Git tree to mirror as a Flux OCI artifact beyond the repositories the profile bundle declares: <clone-url>:<ref>[:<artifact-path>[:<tag>]] (repeat the flag per repository). Cloned with the host's git credentials.
--extra-artifactN/A❌Additional local file or directory to mirror as a generic OCI artifact beyond the artifacts the profile bundle declares: <path>[=<name>[:<tag>]] (repeat the flag per artifact).
--extra-packN/A❌Additional Artifact Studio Pack content bundle (.tar.zst URL) to mirror beyond the packs the profile bundle declares (repeat the flag per pack).
Examples​
# Mirror a profile bundle into a directory
paletteai mirror pull ./profilebundle.yaml ./kgateway-bundle

# Same, wrapped as a single archive for transfer across an air-gap
paletteai mirror pull ./profilebundle.yaml ./kgateway-bundle \
  --archive /tmp/kgateway-bundle.tar.gz

mirror push​

Arguments: BUNDLE — directory produced by mirror export, mirror export-images, mirror export-pack, or mirror pull, or a .tar / .tar.gz / .tgz archive from those commands’ --archive. Archives are extracted to a temporary directory for the duration of the command.

Loads saved image artifacts (OCI layout directories) and pushes them to --dest-registry (skipped when the bundle lists no images). When the bundle lists charts, pushes each chart to OCI (oci://<dest>/charts/<chart>). Chart-only bundles from mirror export push the chart and report zero images pushed. When bundle.json includes packArchive, pushes the Palette Pack tarball as an OCI artifact to <dest-registry>/spectro-packs/archive/<name>:<tag> using the name and tag in the manifest (derived from the original pack filename). When bundle.json includes artifacts (from --extra-artifact), pushes each staged file or directory as a generic OCI artifact to <dest-registry>/<name>:<tag>. When bundle.json includes packs (from --extra-pack), pushes each staged Pack content bundle's constituent artifacts to <dest-registry>/packs/. Bundles from mirror export-images contain images only. Chart and pack pushes are skipped. Pass --skip-pack-archive to push only images and charts (not the pack tarball). Only the destination registry must be reachable.

FlagShorthandDefaultRequiredDescription
--dest-registry-dN/A✅Destination registry prefix (host:port/path).
--dest-usernameN/A❌Registry username (basic auth).
--dest-passwordN/A❌Registry password (prefer env PALETTEAI_MIRROR_DEST_PASSWORD).
--dest-ca-certN/A❌PEM file or directory of PEM/CRT/CER for destination TLS trust.
--dest-insecurefalse❌Skip TLS verification for the destination registry.
--dest-plain-httpfalse❌Use plain HTTP for the destination registry (no TLS; distinct from --dest-insecure).
--skip-pack-archivefalse❌Do not push the Palette pack tarball from bundle.json packArchive. Images and charts are still pushed.

Examples​

# Upload a content bundle produced via `mirror export` to an air-gapped OCI registry
paletteai mirror push ./my-bundle \
  --dest-registry 10.0.0.1:30003/spectro-content \
  --dest-insecure \
  --dest-username admin

# Same destination flags for a bundle from `mirror export-images` (images only)
paletteai mirror push ./agent-bundle \
  --dest-registry 10.0.0.1:30003/spectro-content \
  --dest-insecure \
  --dest-username admin
# Push images and charts only (skip the Palette pack tarball from export-pack)
paletteai mirror push ./my-bundle \
  --dest-registry 10.0.0.1:30003/spectro-content \
  --skip-pack-archive \
  --dest-insecure \
  --dest-username admin

mirror sync​

Chart mode deprecated

Chart-based mirror sync (Helm chart flags, no --profile-bundle) is deprecated. Use mirror sync --profile-bundle to mirror a profile bundle's declared content instead. The --profile-bundle mode is not deprecated.

Arguments: none (uses a temporary bundle directory that is deleted after the command).

Runs mirror export then mirror push in one process. Requires every flag needed for both phases: chart/source flags (including optional repeatable --extra-image) and --dest-registry. Does not accept a Pack tarball; use mirror export-pack then mirror push for pack-based bundles.

When given --profile-bundle, mirror sync runs mirror pull then mirror push instead of mirror export then mirror push, mirroring the bundle's declared content without Helm templating.

FlagDefaultRequiredDescription
--profile-bundleN/A❌Path to a profilebundle.yaml file (or a directory containing one) downloaded from Artifact Studio: mirror the content it declares instead of a Helm chart (skips templating; ignores chart/source flags).

All other flags match those from mirror export and mirror push. When --profile-bundle is used, the Helm chart and templating flags (--chart-url, --chart-version, --repo-url, --release-name, --values, --kube-version) are ignored; --extra-image, --extra-chart, --extra-repo, --extra-artifact, and --extra-pack are still mirrored in addition to the bundle's declared content.

Examples​

# Mirror a Helm chart from a classic Helm repository to an air-gapped OCI registry in one shot
paletteai mirror sync \
  --chart-url clearml/clearml \
  --chart-version 7.14.7 \
  --release-name clearml \
  --repo-url https://clearml.github.io/clearml-helm-charts \
  --dest-registry 10.0.0.1:30003/spectro-content \
  --dest-insecure \
  --dest-username admin
# Same, plus extra images pulled and pushed with the chart-derived set
paletteai mirror sync \
  --chart-url clearml/clearml \
  --chart-version 7.14.7 \
  --release-name clearml \
  --repo-url https://clearml.github.io/clearml-helm-charts \
  --extra-image docker.io/library/redis:7 \
  --dest-registry 10.0.0.1:30003/spectro-content \
  --dest-insecure \
  --dest-username admin
# Mirror a profile bundle's content to an air-gapped OCI registry in one shot
paletteai mirror sync \
  --profile-bundle ./profilebundle.yaml \
  --dest-registry 10.0.0.1:30003/spectro-content \
  --dest-insecure \
  --dest-username admin

Bundle layout (export / export-images / export-pack / pull / sync)​

After mirror export, mirror export-images, mirror export-pack, or mirror pull (or internally during mirror sync for chart-only export or profile-bundle-based pull), the bundle directory contains:

  1. bundle.json — manifest (image list; chart entries when present; for export-pack, also packArchive with the bundle-relative path to the copied pack and the OCI name/tag used on push). For export-images, the chart list is empty.
  2. charts/ — pulled Helm chart .tgz archives for chart-based export (one chart) or export-pack (one entry per pack.content.charts line). Empty for export-images.
  3. images/<n>/ — one OCI image layout per image (multi-arch preserved), including chart-derived images and any --extra-image entries from mirror export / mirror sync. Empty for chart-only mirror export bundles.
  4. repos/<n>-<repo>.tar.gz — present for --extra-repo or the repositories a profile bundle declares: a Flux artifact tarball of each cloned Git tree, pushed as an OCI artifact on mirror push.
  5. artifacts/<n>-<base> — present for --extra-artifact or the artifacts a profile bundle declares: each staged local file or directory, pushed as a generic OCI artifact.
  6. packs/<n>.tar.zst — present for --extra-pack or the packs a profile bundle declares: each downloaded Artifact Studio Pack content bundle, whose constituent artifacts are pushed to <dest-registry>/packs/ on mirror push.
  7. spectro-packs/archive/ — present for export-pack only: copy of the source Pack tarball.

export​

Export the parameter section of a CUE template to an OpenAPI v3 JSON schema. This is useful for generating schema documentation or validation artifacts from Definitions.

This is not the same as paletteai mirror export; the top-level export command only converts CUE parameters to OpenAPI.

Flags​

FlagDefaultRequiredDescription
-o | --outputN/A❌Output file path. If empty, the schema is printed to stdout. If input is a directory, the output path is expected to be a directory as well.

Examples​

# Export a CUE template's parameters to stdout
paletteai export path/to/file.cue

# Export to a file
paletteai export path/to/file.cue --output path/to/output.json

status​

Display the status of each subresource of one or more Workloads in a given namespace. The output includes component statuses, applied resources, policy statuses, and Definition outputs. Data is displayed in YAML format.

If both --workload-namespace and --workload-name are specified, data for only that Workload is shown. If --workload-name is omitted, data for all Workloads in the namespace is displayed.

Flags​

FlagDefaultRequiredDescription
-a | --workload-nameN/A❌Name of a specific Workload. If omitted, all Workloads in the namespace are displayed.
-n | --workload-namespacedefault✅Namespace of the Workloads.

Examples​

# Show status for a specific Workload
paletteai status --workload-namespace nginx-demo --workload-name nginx-demo

# Show status for all Workloads in a namespace
paletteai status --workload-namespace my-namespace

support-bundle​

Generate a support bundle for a PaletteAI cluster, whether a hub or a spoke. A support bundle is a diagnostic archive containing logs, resource manifests, and cluster information useful for troubleshooting. The embedded spec collects from both hub components and spoke components, so the same command works against either cluster role; collectors that do not match any pods on the target cluster are skipped.

The support bundle spec is embedded in the CLI, so no external configuration files are required. Use --spec to provide a custom support bundle specification if needed.

Flags​

FlagDefaultRequiredDescription
--kubeconfig$KUBECONFIG or ~/.kube/config❌Path to the target cluster kubeconfig, hub or spoke (single file).
--output./pai-support-bundle-<timestamp>.tar.gz❌Output path for the generated bundle archive.
--specN/A❌Path to a custom support bundle spec file. When omitted, uses the embedded PaletteAI spec.
--installfalse❌Install the support-bundle plugin via the documented installer when it is not on PATH.
--install-dir$INSTALL_DIR or ~/.local/bin❌Directory to install the support-bundle plugin into (used with --install).
--debugtrue❌Pass --debug to the support-bundle plugin for verbose output.

Examples​

# Generate a support bundle using the default kubeconfig
paletteai support-bundle

# Generate a support bundle with a specific kubeconfig
paletteai support-bundle --kubeconfig /path/to/kubeconfig

# Generate a support bundle with a custom output path
paletteai support-bundle --output /tmp/my-bundle.tar.gz

# Use a custom support bundle spec
paletteai support-bundle --spec /path/to/custom-spec.yaml

# Install the support-bundle plugin automatically if it is missing
paletteai support-bundle --install

Prerequisites​

The command requires the troubleshoot.sh support-bundle plugin to be on PATH. Install it manually with the documented installer:

curl https://krew.sh/support-bundle | bash

Alternatively, pass --install to have the command run that installer for you when the plugin is missing. The --install path requires curl and bash to be available on your system.

studio​

Manage artifacts downloaded from PaletteAI Studio.

studio import​

Import artifacts downloaded from PaletteAI Studio into a Kubernetes cluster. Accepts either gzipped tar archives (.tar.gz) or plain directories as input. The command reads a profilebundle.yaml from the archive, parses its composition (infrastructure, application, or fullstack profiles), generates ProfileBundle and WorkloadProfile Kubernetes resources, and applies them to the cluster.

The command automatically detects the cluster's versioning type (basic or semantic) from the mural-feature-flags ConfigMap. When the cluster uses semantic versioning, the --app-version flag is required. When the cluster uses basic versioning, --app-version must not be provided.

Flags​
FlagDefaultRequiredDescription
--namespaceN/A✅Target Kubernetes namespace for the imported resources.
--registry-mapN/A❌Registry UID mappings in source:target format. Can be specified multiple times. Useful for airgap environments where registry UIDs differ from the original bundle.
--app-versionN/A❌Application version to set in spec.version of WorkloadProfile and ProfileBundle resources. Required for clusters using semantic versioning. Do not use for basic versioning.
--dry-runfalse❌Preview the generated YAML resources without applying them to the cluster.
Examples​
# Import a .tar.gz bundle
paletteai studio import --namespace my-project ~/Downloads/clearml-7.14.7.tar.gz

# Import from an extracted directory
paletteai studio import --namespace my-project ~/Downloads/clearml-7.14.7/

# Preview the generated resources without applying
paletteai studio import --namespace my-project --dry-run ~/Downloads/clearml-7.14.7.tar.gz

# Import with registry UID remapping (e.g., for airgap)
paletteai studio import --namespace my-project --registry-map oldUID:newUID ~/Downloads/clearml-7.14.7.tar.gz

# Import with an explicit application version (semantic versioning clusters)
paletteai studio import --namespace my-project --app-version 1.2.0 ~/Downloads/clearml-7.14.7.tar.gz

version​

Print the CLI version and the PaletteAI control plane component versions. By default, only the CLI version and the PaletteAI version (read from the mural-versions ConfigMap) are printed. With --long, every component is reported: mural-crds from the ConfigMap, the remaining components resolved live from their Deployment image tags, and the OCM version from the ClusterManager spec.

If no kubeconfig is configured, only the CLI version is printed. Any component that cannot be resolved is reported on stderr and the command exits non-zero, while the versions that did resolve are still printed.

Use the global --log-format flag to switch between text and JSON output.

Flags​

FlagDefaultRequiredDescription
--longfalse❌Report every PaletteAI server component version, not just PaletteAI.
-n | --namespacemural-system❌Namespace containing the PaletteAI components.

Examples​

# Print the CLI version and the PaletteAI version
paletteai version

# Print every PaletteAI server component version
paletteai version --long

# Print every component version as JSON
paletteai version --long --log-format json