Skip to main content

PaletteAI CLI

The paletteai CLI is a command-line tool for authoring and testing Definitions, inspecting Workload statuses, and importing profile bundles downloaded from PaletteAI Studio. 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.

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
  status      Displays the status of each subresource of one or more workloads
  studio      Manage Palette artifact studio artifacts

Flags:
  -h, --help                help for mural
      --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

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.

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

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