> ## 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 --reuse-values

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

### Uninstall

```bash theme={"system"}
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.10+ (OCI registry support)
* **LLM Provider**: At least one API key configured (OpenAI, Anthropic, Google, xAI, StackSpot, GitHub Copilot, or Ollama)

***

## Next Steps

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

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

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