> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ArtifactHub

> ChatCLI Helm chart distribution via ArtifactHub — the public package registry for Kubernetes.

**ChatCLI** publishes its Helm charts to [ArtifactHub](https://artifacthub.io), the official public package registry for the **Cloud Native** ecosystem. This allows anyone to discover, install, and keep the charts up to date directly from the ArtifactHub catalog or via the Helm CLI.

***

## Available Charts

<CardGroup cols={2}>
  <Card title="ChatCLI Server" icon="server" href="https://artifacthub.io/packages/search?repo=chatcli">
    Multi-provider LLM gRPC gateway with agent mode, K8s watcher, MCP, and AIOps.
    **OCI Registry:** `oci://ghcr.io/diillson/charts/chatcli`
  </Card>

  <Card title="ChatCLI Operator" icon="dharmachakra" href="https://artifacthub.io/packages/search?repo=chatcli-operator">
    Kubernetes operator for autonomous incident detection, AI analysis, and automated remediation.
    **OCI Registry:** `oci://ghcr.io/diillson/charts/chatcli-operator`
  </Card>
</CardGroup>

***

## How the Integration Works

The ArtifactHub integration is fully automated and based on three pillars:

### 1. Repository Files (`artifacthub/`)

In the `artifacthub/` directory there are **two separate files**, one per chart, that register the repositories on ArtifactHub:

**`artifacthub/chatcli-repo.yml`**

```yaml theme={"system"}
repositoryID: 193ab92d-52ac-4ac1-863f-aa29927c8d74
owners:
  - name: Edilson Freitas
    email: diillson@hotmail.com
```

**`artifacthub/chatcli-operator-repo.yml`**

```yaml theme={"system"}
repositoryID: ccc35f25-d27b-41ca-ba20-b8de9ee2f828
owners:
  - name: Edilson Freitas
    email: diillson@hotmail.com
```

These files are pushed to the OCI registry via [ORAS](https://oras.land/) with the MIME type `application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml`, allowing ArtifactHub to automatically discover and index the charts.

<Info>
  Each chart has a unique `repositoryID` and its own metadata file. ArtifactHub reads these OCI artifacts to automatically sync repository metadata.
</Info>

### 2. Chart Annotations (`Chart.yaml`)

Each chart's `Chart.yaml` contains ArtifactHub-specific annotations that enrich the package page in the catalog:

```yaml theme={"system"}
annotations:
  artifacthub.io/license: Apache-2.0
  artifacthub.io/containsSecurityUpdates: 'false'
  artifacthub.io/prerelease: 'false'
  artifacthub.io/operator: 'false'         # 'true' for the operator chart
  artifacthub.io/operatorCapabilities: Seamless Upgrades  # operator only
  artifacthub.io/crds: |
    - kind: AIInsight
      version: v1alpha1
      description: AI-generated analysis and recommendations
    # ... 17 CRDs total
  artifacthub.io/crdsExamples: |
    - apiVersion: platform.chatcli.io/v1alpha1
      kind: Issue
      metadata:
        name: high-cpu-api-server
      spec:
        title: "High CPU usage on api-server"
        severity: critical
    # ... examples for ApprovalPolicy, ServiceLevelObjective, etc.
  artifacthub.io/links: |
    - name: Documentation
      url: https://chatcli.edilsonfreitas.com
    - name: Source
      url: https://github.com/diillson/chatcli
  artifacthub.io/maintainers: |
    - name: Edilson Freitas
      email: diillson@hotmail.com
```

#### Available Annotations

| Annotation | Description | Server | Operator |
| - | - | :-: | :-: |
| `artifacthub.io/license` | Chart license | Apache-2.0 | Apache-2.0 |
| `artifacthub.io/operator` | Whether it is a Kubernetes operator | `false` | `true` |
| `artifacthub.io/operatorCapabilities` | Operator maturity level | — | Seamless Upgrades |
| `artifacthub.io/containsSecurityUpdates` | Flags security updates | `false` | `false` |
| `artifacthub.io/prerelease` | Marks as pre-release version | `false` | `false` |
| `artifacthub.io/crds` | CRDs installed by the chart | 17 CRDs | 17 CRDs |
| `artifacthub.io/crdsExamples` | CRD usage examples | 3 examples | 4 examples |
| `artifacthub.io/links` | Links to documentation and source code | 2 links | 2 links |
| `artifacthub.io/maintainers` | Chart maintainers | 1 | 1 |

### 3. Publishing Pipeline (GitHub Actions)

Publishing is fully automated via GitHub Actions in the `3-publish-release.yml` workflow. On each release:

<Steps>
  <Step title="Release trigger">
    A push to the `main` branch triggers [Release Please](https://github.com/googleapis/release-please-action), which automatically creates a release PR and, once merged, generates the GitHub Release with the version tag.
  </Step>

  <Step title="Automatic versioning">
    The pipeline updates the version in both `Chart.yaml` files:

    ```bash theme={"system"}
    sed -i "s/^version:.*/version: ${VERSION}/" deploy/helm/chatcli/Chart.yaml
    sed -i "s/^appVersion:.*/appVersion: \"${VERSION}\"/" deploy/helm/chatcli/Chart.yaml
    ```
  </Step>

  <Step title="Changelog injection">
    The `scripts/generate-artifacthub-changelog.sh` script extracts changes from `CHANGELOG.md` and injects them as `artifacthub.io/changes` annotations into the `Chart.yaml` files, with structured types (added, fixed, changed, etc.) and PR links.
  </Step>

  <Step title="Packaging">
    Charts are packaged with `helm package`:

    ```bash theme={"system"}
    helm package deploy/helm/chatcli/ -d /tmp/charts/
    helm package deploy/helm/chatcli-operator/ -d /tmp/charts/
    ```
  </Step>

  <Step title="Push to OCI registry">
    Packages are pushed to the GitHub Container Registry:

    ```bash theme={"system"}
    helm push /tmp/charts/chatcli-${VERSION}.tgz oci://ghcr.io/diillson/charts
    helm push /tmp/charts/chatcli-operator-${VERSION}.tgz oci://ghcr.io/diillson/charts
    ```
  </Step>

  <Step title="Cosign signing">
    Both charts are signed with [Cosign](https://docs.sigstore.dev/cosign/) using keyless OIDC, ensuring artifact integrity and provenance:

    ```bash theme={"system"}
    cosign sign --yes "ghcr.io/diillson/charts/chatcli@${CHART_DIGEST}"
    cosign sign --yes "ghcr.io/diillson/charts/chatcli-operator@${CHART_DIGEST}"
    ```
  </Step>

  <Step title="ArtifactHub metadata push via ORAS">
    Repository files are pushed as OCI artifacts with ArtifactHub-specific MIME types, enabling automatic discovery:

    ```bash theme={"system"}
    oras push ghcr.io/diillson/charts/chatcli:artifacthub.io \
      --config /dev/null:application/vnd.cncf.artifacthub.config.v1+yaml \
      artifacthub/chatcli-repo.yml:application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml
    ```
  </Step>

  <Step title="ArtifactHub sync">
    ArtifactHub detects the metadata in the OCI registry and automatically indexes the new chart versions in the catalog.
  </Step>
</Steps>

***

## Documented CRDs

Both charts declare **17 Custom Resource Definitions** in the annotations, which are automatically displayed on the ArtifactHub page:

| CRD | Version | Description |
| - | - | - |
| `AIInsight` | v1alpha1 | AI-generated analysis and recommendations for detected issues |
| `Anomaly` | v1alpha1 | Raw signal from watchers before correlation into issues |
| `ApprovalPolicy` | v1alpha1 | Approval requirements for remediation actions (auto/manual/quorum) |
| `ApprovalRequest` | v1alpha1 | Pending approval with blast radius assessment |
| `AuditEvent` | v1alpha1 | Immutable record of actions on the AIOps platform |
| `ChaosExperiment` | v1alpha1 | Chaos engineering experiment targeting Kubernetes resources |
| `ClusterRegistration` | v1alpha1 | Registered cluster for multi-cluster federation |
| `EscalationPolicy` | v1alpha1 | Escalation chains for incident management |
| `IncidentSLA` | v1alpha1 | SLA targets for response and resolution by severity |
| `Instance` | v1alpha1 | ChatCLI instance configuration |
| `Issue` | v1alpha1 | Correlated operational problem detected in the cluster |
| `NotificationPolicy` | v1alpha1 | Multi-channel notification delivery rules |
| `PostMortem` | v1alpha1 | Full incident lifecycle report after resolution |
| `RemediationPlan` | v1alpha1 | Remediation plan with 54+ action types |
| `Runbook` | v1alpha1 | Operational procedures linked to issue types |
| `ServiceLevelObjective` | v1alpha1 | SLO with burn rate alerting and error budgets |
| `SourceRepository` | v1alpha1 | Links workloads to source code for code-aware analysis |

<Note>
  CRDs are shared between the server and operator charts. If both are installed in the same cluster, the CRDs from whichever chart was installed first will be used.
</Note>

***

## Installation via ArtifactHub

### ChatCLI Server

```bash theme={"system"}
helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli --create-namespace \
  --set llm.provider=OPENAI \
  --set secrets.openaiApiKey=sk-xxx
```

### ChatCLI Operator

```bash theme={"system"}
helm install chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --namespace chatcli-system --create-namespace
```

### From Source

```bash theme={"system"}
git clone https://github.com/diillson/chatcli.git

# Server
helm install chatcli deploy/helm/chatcli \
  --namespace chatcli --create-namespace

# Operator
helm install chatcli-operator deploy/helm/chatcli-operator \
  --namespace chatcli-system --create-namespace
```

### Using an Existing Secret

```bash theme={"system"}
kubectl create secret generic chatcli-llm-keys \
  --namespace chatcli \
  --from-literal=OPENAI_API_KEY=sk-xxx \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-xxx

helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli \
  --set llm.provider=OPENAI \
  --set secrets.existingSecret=chatcli-llm-keys
```

***

## Upgrade and Removal

### Upgrade to Latest Version

```bash theme={"system"}
# Server
helm upgrade chatcli oci://ghcr.io/diillson/charts/chatcli \
  --namespace chatcli --reset-then-reuse-values

# Operator
helm upgrade chatcli-operator oci://ghcr.io/diillson/charts/chatcli-operator \
  --namespace chatcli-system --reset-then-reuse-values
```

`--reset-then-reuse-values` (Helm 3.14+) starts from the new chart's defaults and re-applies your previous overrides. Plain `--reuse-values` skips the defaults of keys added by newer chart versions and can fail the render; with an older Helm, pass your values file (`-f my-values.yaml`) instead.

Before upgrading the operator across several releases, read [Upgrade and uninstall](/kubernetes/k8s-operator#upgrade-and-uninstall): what rolls, what the Instance status shows during the rollout, and the releases that need action first. For the server chart, see [Upgrade, rollback, uninstall](/start/docker-deployment#upgrade-rollback-uninstall).

<Note>
  **CRDs are updated on every upgrade.** Both charts run a `pre-install,pre-upgrade` hook Job that applies every CRD in the chart with `kubectl apply --server-side` before the new controller rolls out. Helm itself never updates `crds/` after the first install, and a controller running against an older schema has its new fields dropped and its new enum values rejected. Turn the hook off (`--set crdUpgrade.enabled=false`) only when you manage the CRDs out of band, and then apply the new chart's `crds/` yourself before upgrading; the operator chart's install notes print the commands.
</Note>

### Uninstall

Delete your `Instance` resources before removing the operator: the operator removes their finalizer, and an Instance deleted after it is gone stays `Terminating` (see [Uninstall](/kubernetes/k8s-operator#uninstall)).

```bash theme={"system"}
kubectl delete instances --all -A     # while the operator still runs
helm uninstall chatcli -n chatcli
helm uninstall chatcli-operator -n chatcli-system
```

<Warning>
  CRDs are **not** automatically removed by Helm. To remove them manually:

  ```bash theme={"system"}
  kubectl get crd -o name | grep platform.chatcli.io | xargs kubectl delete
  ```
</Warning>

***

## Chart Structure

Helm charts are located in `deploy/helm/` in the repository:

```
deploy/helm/
���── chatcli/                          # Server chart
│   ��── Chart.yaml                    # Metadata + ArtifactHub annotations
│   ├── README.md                     # Documentation shown on ArtifactHub
│   ├── values.yaml                   # Default values (322 lines)
│   ├── crds/                         # 17 CRD YAML files
│   │   ├─��� platform.chatcli.io_aiinsights.yaml
│   │   ├── platform.chatcli.io_anomalies.yaml
│   │   ���── ... (15 more)
│   └── templates/
│       ├── deployment.yaml
│       ├── service.yaml
│       ├── secret.yaml
│       ├── configmap.yaml
│       ├── rbac.yaml
│       ├── hpa.yaml
│       ├── pdb.yaml
│       ├── ingress.yaml
│       ├── networkpolicy.yaml
│       ├── pvc.yaml
│       ├── serviceaccount.yaml
│       ├── servicemonitor.yaml
│       ├── mcp-configmap.yaml
│       ├── agents-configmap.yaml
│       ├── bootstrap-configmap.yaml
│       ├── skills-configmap.yaml
│       └── _helpers.tpl
│
└─��� chatcli-operator/                 # Operator chart
    ├── Chart.yaml
    ├── README.md
    ├── values.yaml
    ├── crds/
    └── templates/
```

***

## Differences Between Charts

| Aspect | ChatCLI Server | ChatCLI Operator |
| - | - | - |
| **Purpose** | LLM gRPC gateway with agents and watcher | Autonomous incident detection and remediation |
| **ArtifactHub Type** | Application | Operator |
| **`artifacthub.io/operator`** | `false` | `true` |
| **Capabilities** | — | Seamless Upgrades |
| **CRD Examples** | Issue, ApprovalPolicy, SLO | Issue, ApprovalPolicy, ChaosExperiment, SLO |
| **Keywords** | chatcli, llm, grpc, ai, mcp, aiops | operator, aiops, remediation, sre, chaos-engineering |
| **OCI Registry** | `oci://ghcr.io/diillson/charts/chatcli` | `oci://ghcr.io/diillson/charts/chatcli-operator` |

***

## Chart Security

Both charts follow Kubernetes security best practices:

<CardGroup cols={2}>
  <Card title="Non-Root" icon="shield-halved">
    Containers run as non-root user (UID 1000) with `runAsNonRoot: true`.
  </Card>

  <Card title="Read-Only Filesystem" icon="lock">
    `readOnlyRootFilesystem: true` — only mounted volumes are writable.
  </Card>

  <Card title="Capabilities Dropped" icon="ban">
    All Linux capabilities are dropped with `drop: ["ALL"]`.
  </Card>

  <Card title="Seccomp" icon="fingerprint">
    `RuntimeDefault` seccomp profile enabled by default.
  </Card>
</CardGroup>

***

## Requirements

* **Kubernetes**: 1.30+
* **Helm**: 3.8+ (OCI registry support), Helm 4 included
* **LLM Provider**: A credential for at least one [supported provider](/providers/supported-models) (an API key, IAM for Bedrock, or a local Ollama)

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Docker & K8s Deploy" icon="docker" href="/start/docker-deployment">
    Complete deployment guide with Docker, Compose, and Helm.
  </Card>

  <Card title="K8s Operator" icon="dharmachakra" href="/kubernetes/k8s-operator">
    AIOps operator details with 17 CRDs.
  </Card>

  <Card title="AIOps Platform" icon="brain" href="/kubernetes/aiops-platform">
    Overview of the intelligent operations platform.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.