# CLI Management Design

## Summary

The `metrics-integration` repository contains an internal management CLI implemented with Cobra. It is not just a loose collection of debug commands. It is a structured management surface embedded into the Global service codebase.

Core implementation entrypoints:

- `global/internal/domain/cmd/root.go`
- `global/internal/domain/cmd/job/jobs.go`
- `global/internal/domain/cmd/job/workflow.go`
- `global/internal/domain/cmd/job/integration.go`
- `global/Makefile`

## Positioning

This CLI is primarily intended for:

- internal development and debugging
- on-call recovery
- workflow intervention
- integration lifecycle operations

It is not designed as a thin API client. Many commands directly invoke internal service logic.

## Command Tree

```text
metrics-integration
  job
    workflow
      retry-dag-ins
      cancel-dag-ins
    integration
      create
      delete
      list
      redeploy
      clean-integration
```

## Design Intent

### `job workflow`

Purpose:

- recover failed DAG instances
- cancel running DAG instances

This part of the CLI exists because workflow failures are operationally important and often require targeted manual intervention.

### `job integration`

Purpose:

- create integrations
- inspect current integrations
- delete integrations
- redeploy pipeline resources
- clean residual integration resources

This makes the CLI a real management plane for integration lifecycle operations.

## Operational Characteristics

### Create

`create` is not a simple database mutation. It performs:

- parameter validation
- provider-specific site parsing
- online API key validation
- integration controller calls
- provider-specific URL and dashboard output

### Redeploy

`redeploy` is a strong signal that the CLI was designed for real operational recovery:

- resolve pipeline by id
- load target cluster
- decrypt stored provider key
- build Helm package config
- apply through regional or global dataplane

### Clean

`clean-integration` exists to remove pipeline resources while preserving database semantics where needed. It is a cleanup and recovery tool, not just a CRUD function.

## Why This Matters

The CLI centralizes operational actions that would otherwise be spread across:

- workflow internals
- DB records
- Helm deployment logic
- dataplane apply logic
- integration controllers

That centralization reduces repeated ad-hoc commands during incidents.

## Current Documentation Gap

The implementation is more complete than the historical documentation. The repo needed an explicit description of:

- who should use the CLI
- what each command actually changes
- which commands are read-only vs mutating
- where the boundaries are between CLI, API, and workflow systems