# CLI Usage Guide

## Scope

This guide covers the internal `metrics-integration` CLI implemented in the Global service codebase.

Reference implementation:

- `global/cmd/metrics-integration/main.go`
- `global/internal/domain/cmd/root.go`
- `global/internal/domain/cmd/server.go`
- `global/internal/domain/cmd/workflow.go`
- `global/internal/domain/cmd/job/workflow.go`
- `global/internal/domain/cmd/job/integration.go`

## Positioning

The CLI is an internal management tool. It:

- loads service config
- initializes dependency injection
- initializes DB migrations
- calls internal workflow, integration, Helm, and dataplane logic

Use it for:

- local development
- on-call recovery
- integration operations

Related docs:

- `docs/operations/2026-03-20-cli-management-design.md`
- `docs/operations/2026-03-20-operations-index.md`

## Build and Run

### Build

```bash
cd global
make build
```

### Run with config

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml <command>
```

Common local form:

```bash
go run ./cmd/metrics-integration/main.go -c ./deployment/config/local/config.yaml <command>
```

## Command Tree

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

## Top-Level Commands

### `server`

Starts the Global service.

Flags:

- `--grpc-port`
- `--gateway-port`

### `workflow`

Starts the background workflow runtime.

## `job workflow`

### `retry-dag-ins`

Retry a failed DAG instance.

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job workflow retry-dag-ins --dag-ins-id <DAG_INSTANCE_ID>
```

### `cancel-dag-ins`

Cancel a running DAG instance.

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job workflow cancel-dag-ins --dag-ins-id <DAG_INSTANCE_ID>
```

## `job integration`

### Supported integration types

- `datadog`
- `newrelic`

### `create`

Required flags:

- `--org-id`
- `--project-id`
- `--cluster-id`
- `--type`

Provider-specific flags:

- Datadog: `--datadog-api-key`, `--datadog-site`
- New Relic: `--newrelic-api-key`, `--newrelic-site`

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job integration create \
  --org-id <ORG_ID> \
  --project-id <PROJECT_ID> \
  --cluster-id <CLUSTER_ID> \
  --type datadog \
  --datadog-api-key <DATADOG_API_KEY> \
  --datadog-site us1
```

### `list`

Required flag:

- `--cluster-id`

Optional:

- `--type`

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job integration list --cluster-id <CLUSTER_ID>
```

### `delete`

Confirmed required flag in current code:

- `--pipeline-id`

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job integration delete --pipeline-id <PIPELINE_ID>
```

### `redeploy`

Required:

- `--pipeline-id`

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job integration redeploy --pipeline-id <PIPELINE_ID>
```

### `redeploy-region`

Required:

- `--cloud`: `aws`, `gcp`, `azure`, or `alicloud`
- `--regions`: one or more comma-separated regions

Optional:

- `--pipeline-id-allowlist`: only include the listed pipeline IDs
- `--pipeline-id-blocklist`: exclude the listed pipeline IDs
- `--apply`: execute the redeployments; without it the command only prints the plan

The command selects non-deleted Datadog and New Relic integrations in the requested
cloud and regions. It continues after individual failures and returns a non-zero exit
status when any selected pipeline fails.

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job integration redeploy-region \
  --cloud aws \
  --regions us-west-2,sa-east-1

./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job integration redeploy-region \
  --cloud aws \
  --regions us-west-2,sa-east-1 \
  --apply
```

### `clean-integration`

Required:

- `--pipeline-id`

Example:

```bash
./bin/metrics-integration -c /etc/metrics-integration/config.yaml \
  job integration clean-integration --pipeline-id <PIPELINE_ID>
```

## Known Limitation

The `global/Makefile` contains a historical `job-integration-update` target, but the current Cobra command tree does not register an `update` subcommand. The current confirmed commands are:

- `create`
- `delete`
- `list`
- `redeploy`
- `redeploy-region`
- `clean-integration`

## Operational Caution

High-risk commands include:

- `job integration create`
- `job integration delete`
- `job integration redeploy`
- `job integration redeploy-region --apply`
- `job integration clean-integration`
- `job workflow cancel-dag-ins`

Always confirm:

- target object
- expected impact
- rollback plan