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

# CLI 참고

> clicklink clctl 명령어 참고: init, preflight, 지원 세션, gateway 신뢰, 감사, 액세스 프로비저닝

커넥터는 `clicklink`라는 단일 바이너리로 제공되며, 실행할 명령어는 `clicklink clctl` 아래에 있습니다. 이 페이지에서는 설치 및 일상적인 운영에 사용하는 명령어를 다룹니다. 각 명령어에 `--help`를 지정하면 전체 도움말을 확인할 수 있습니다. `troubleshoot` 및 `preflight` 하위 트리의 플래그는 `CLCTL_*` 환경 변수(각 플래그의 도움말 출력에 이름이 표시됨) 또는 `~/.clicklink/clctl.yaml`로도 지정할 수 있습니다.

<div id="init">
  ## clicklink clctl init
</div>

등록 토큰, 저장된 등록 번들 또는 대역 외에서 서명된 인증서를 사용하여 커넥터를 초기 설정합니다. 한 번의 호출로 구성을 준비하고, ClickHouse 액세스를 프로비저닝하며, mTLS 클라이언트 인증서를 가져오고, 배포(Helm 차트 또는 systemd unit)한 후 상태를 확인합니다. 다시 실행해도 안전합니다. 구성과 클러스터 UUID는 유지되며, 자격 증명은 원자적으로 덮어쓰고, `--force`를 전달하지 않는 한 기존 클라이언트 키를 재사용합니다. 전체 흐름은 [onboarding](/docs/ko/products/bring-your-own-cloud/connector/onboarding)을 참조하십시오.

<div id="init-entry-points">
  ### 진입점
</div>

3개의 진입점 중 정확히 하나를 지정해야 하며, 동시에 사용할 수 없습니다.

| 플래그                    | 설명                                                                                                                                                                                                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--enroll <url>`       | 표준 흐름입니다. 조직의 커넥터 endpoint(`https://<subdomain>.<커넥터 domain>`)를 받아 일회용 등록 토큰을 사용합니다. 토큰은 터미널에서는 에코 없이 프롬프트로 입력받고, 그 외 환경에서는 stdin의 첫 번째 줄에서 읽습니다. 생성된 번들을 `handoff.yaml`(mode 0600)에 기록한 뒤 `--handoff handoff.yaml`으로 계속 진행합니다. 토큰은 명령줄, 디스크 또는 logs에 기록되지 않습니다. |
| `--handoff <path>`     | 저장된 등록 번들을 사용하여 Bootstrap합니다. `handoff.yaml`이 있으면 재실행 및 recovery 시 이 옵션을 사용합니다.                                                                                                                                                                                  |
| `--signed-cert <path>` | air-gapped 흐름의 단계 2입니다. 별도 경로로 서명된 클라이언트 인증서를 설치하고 단계별 설치를 완료합니다. 필요에 따라 `--chain <path>`를 사용하여 CA 체인도 함께 대체할 수 있습니다.                                                                                                                                            |

<div id="init-common-flags">
  ### 공통 플래그
</div>

| 플래그                         | 설명                                                                                                                                                       |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--target <shape>`          | 배포 형태: `systemd`(기본값, 현재 사용 중인 VM 부트스트랩) 또는 `helm`(kubeconfig가 있는 워크스테이션에서 `clicklink-connector` 차트 스테이징)입니다.                                            |
| `--instance <spec>`         | 쉼표로 구분된 `key=value` 쌍으로 지정하는 ClickHouse 인스턴스(`name`, `host`, `port`, `secure`, `database`, `namespace`, `cluster`)입니다. 반복 지정할 수 있으며, 대화형 인스턴스 입력을 건너뜁니다. |
| `--operators <emails>`      | 지원 세션을 열 수 있는 운영자 이메일을 쉼표로 구분하여 지정합니다. 세션 게이트웨이를 활성화하고 입력을 건너뜁니다.                                                                                        |
| `--no-gateway`              | 세션 게이트웨이를 비활성화합니다(OIDC로 관리되는 세션 없음). 입력을 건너뜁니다. VM에서는 호스트의 root 사용자가 로컬 세션 파일을 통해 계속 세션을 관리할 수 있습니다.                                                     |
| `--force`                   | 기존 구성 또는 오버레이를 덮어쓰고 클라이언트 키를 다시 생성합니다. 또한 아직 만료되지 않은 자체 서명 인증서를 대체하는 데 동의합니다. `--force`를 사용해도 클러스터 UUID는 유지됩니다.                                          |
| `--skip-provision`          | 스테이징만 수행합니다. 역할별 ClickHouse 액세스 프로비저닝을 건너뛰며(`systemd` 대상에서는 유닛 활성화 및 검증도 건너뜀), `clicklink clctl {scraper,troubleshoot} access provision`을 별도로 실행하십시오.    |
| `--ch-user-suffix <suffix>` | 프로비저닝된 ClickHouse 사용자 이름에 추가할 선택적 접미사입니다(`pcm_scraper`는 `pcm_scraper_<suffix>`가 됨). 이를 통해 두 번째 커넥터 배포가 첫 번째 배포의 사용자와 충돌하지 않고 인스턴스를 공유할 수 있습니다.           |
| `--ch-admin-password-stdin` | SQL 프로비저닝에 필요한 경우 stdin에서 ClickHouse 관리자 비밀번호를 읽습니다. 터미널에서 실행하는 경우에는 대신 입력을 요청합니다.                                                                       |

<div id="init-signing-flags">
  ### 서명 플래그(1단계에만 해당)
</div>

| 플래그                     | 설명                                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `--no-auto-sign`        | 1단계에서만 사용: air-gapped 또는 대역 외 서명 흐름을 위해 등록 endpoint를 통한 자동 CSR 서명을 건너뜁니다.              |
| `--sign-endpoint <url>` | 등록 서명 endpoint를 재정의합니다(기본값: 번들 endpoint에 `enroll` DNS 레이블을 삽입해 파생됨). HTTPS URL이어야 합니다. |

<div id="init-kubernetes-flags">
  ### Kubernetes 전용 플래그
</div>

`--target helm`에서만 유효합니다.

| 플래그                         | 설명                                                                                                               |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--target-namespace <ns>`   | 차트가 설치되고 해당 시크릿이 생성되는 네임스페이스입니다(기본값: `clicklink`, 터미널에서 입력 요청).                                                  |
| `--instance-namespace <ns>` | 대상 ClickHouse 인스턴스의 네임스페이스입니다. 네이티브 Service 감지 및 인스턴스 관련 입력 요청의 초기값을 설정합니다.                                      |
| `--storage-class <name>`    | 문제 해결 도구 상태 볼륨에 사용할 StorageClass입니다(기본값: 클러스터의 기본 StorageClass, 클러스터에 기본 StorageClass가 없으면 입력 요청 또는 필수).         |
| `--values <path>`           | 준비된 values 오버레이의 경로입니다(기본값: `clicklink-values.yaml`).                                                            |
| `--chart <ref>`             | 배포할 차트입니다. `--chart-repo`에서 해석되는 이름이나, 미러링 설치용 직접 `oci://` 참조, URL 또는 로컬 참조를 지정합니다(기본값: `clicklink-connector`).  |
| `--chart-repo <url>`        | 차트 이름을 해석할 Helm 리포지토리입니다(기본값: `https://releases.clicklink.clickhouse.com/charts`). 직접 지정한 `--chart` 참조에서는 무시됩니다. |
| `--chart-version <ver>`     | 배포할 차트 버전입니다(기본값: 이 바이너리의 릴리스 버전).                                                                               |
| `--ch-pod <ref>`            | 파드 내 프로비저닝 단계에 사용할 ClickHouse 파드입니다. 이름 또는 `k=v` 레이블 셀렉터로 지정합니다(기본값: 각 인스턴스의 Service를 지원하는 Running 파드).          |
| `--api-private-ca`          | API endpoint가 등록 번들의 CA에서 발급한 인증서를 제공하는 경우 사용합니다. 시스템 루트 대신 마운트된 CA 체인을 가리키도록 `api.tls.caFile`을 준비합니다.           |

<div id="init-vm-flags">
  ### VM 전용 플래그
</div>

`--target systemd`와 함께 사용할 때만 유효합니다.

| 플래그                  | 설명                                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| `--server <url>`     | 액세스 번들이 가리키는 Kubernetes API server URL입니다(기본값: 이 host의 kubeconfig, 없으면 입력하라는 메시지가 표시됨).              |
| `--ca-data <base64>` | `--server`용 Base64 인코딩 `certificate-authority-data`입니다(기본값: 이 host의 kubeconfig, 없으면 입력하라는 메시지가 표시됨). |

<div id="init-flag-conflicts">
  ### 플래그 충돌
</div>

* `--handoff`, `--enroll`, `--signed-cert`는 상호 배타적이며, 정확히 하나를 지정해야 합니다.
* Kubernetes 전용 플래그는 `--target helm`을 지정한 경우에만 사용할 수 있습니다. `--target helm`에서는 `--server`와 `--ca-data`가 거부됩니다(Helm 흐름은 워크스테이션의 kubeconfig를 읽습니다).
* `--no-auto-sign`과 `--sign-endpoint`는 서로 함께 사용할 수 없으며, 둘 다(`--api-private-ca` 포함) `--signed-cert`와 함께 사용하면 거부됩니다.
* `--operators`와 `--no-gateway`는 서로 함께 사용할 수 없습니다.
* `--skip-provision`을 지정하면 `--ch-pod`, `--ch-user-suffix`, `--server`, `--ca-data`, `--ch-admin-password-stdin`이 거부됩니다(프로비저닝이 수행되지 않음).

<div id="preflight">
  ## clicklink clctl preflight
</div>

구성, 파일, 네트워크, clickhouse, systemd, 액세스, 디스크, 민감 정보 마스킹 범주별로 그룹화된 커넥터 검사 모음을 실행합니다. 각 검사는 통과, 경고, 실패 또는 건너뜀 상태를 보고합니다. 종료 코드 0은 모든 검사가 통과했음을 의미하며(경고는 non-blocking), 종료 코드 2는 하나 이상의 검사가 실패했음을 의미합니다.

이 명령은 기본적으로 로컬에서 실행됩니다. `--k8s-namespace`를 지정하면 `kubectl exec`를 통해 커넥터 파드의 바이너리를 실행하고, 보고서는 로컬에서 렌더링합니다(systemd 검사는 파드에서 항상 건너뜁니다). [원격 채널 플래그](#channel-flags)를 사용하면 원격 VM에 설치된 바이너리를 대신 실행합니다.

| 플래그                      | 설명                                                                  |
| ------------------------ | ------------------------------------------------------------------- |
| `--config <path>`        | 커넥터 구성 파일의 경로입니다. 원격 대상을 사용하는 경우 해당 호스트의 경로입니다.                     |
| `--output <fmt>`, `-o`   | 출력 형식: `text`(기본값) 또는 `json`.                                       |
| `--timeout <dur>`        | 모든 검사에 적용되는 전체 timeout입니다(기본값 `30s`).                               |
| `--skip-systemd`         | systemd 유닛 상태 검사를 건너뜁니다(non-systemd 호스트).                           |
| `--k8s-namespace <ns>`   | 커넥터 차트의 네임스페이스입니다. `kubectl exec`를 통해 커넥터 파드 내부에서 preflight를 실행합니다. |
| `--k8s-component <name>` | 실행할 커넥터 파드입니다: `scraper`(기본값) 또는 `troubleshooter`.                  |
| `--k8s-pod <ref>`        | 파드 이름 또는 `k=v` 레이블 셀렉터 재정의입니다(기본값: 차트의 컴포넌트 레이블).                   |
| `--k8s-container <name>` | exec할 컨테이너입니다(기본값: 컴포넌트 이름).                                        |

`--k8s-*` 플래그와 원격 채널 플래그는 함께 사용할 수 없습니다. 대상 하나만 선택하십시오.

<div id="troubleshoot-session">
  ## clicklink clctl troubleshoot session
</div>

지원 세션을 활성화, 비활성화하고 상태를 확인합니다. 지원 세션은 문제 해결 도구가 명령어를 수락하는 시간 제한 창입니다. 활성화된 세션이 없으면 WebSocket이 연결되어 있더라도 데몬은 모든 명령어를 거부합니다. [지원 세션](/docs/ko/products/bring-your-own-cloud/connector/support-sessions)을 참조하십시오.

명령어는 다음 두 가지 모드 중 하나로 작동합니다.

* **로컬 파일**(기본값): 문제 해결 도구가 실행되는 호스트에서 세션 상태 파일을 읽고 씁니다(기본값: `/var/lib/clicklink/session.json`).
* **게이트웨이**: `--gateway-url`을 사용하면 워크스테이션에서 OIDC ID 토큰을 획득한 후 문제 해결 도구의 세션 게이트웨이를 호출합니다.

<div id="init-common-flags">
  ### 공통 플래그
</div>

| 플래그                        | 설명                                                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--session-file <path>`    | 세션 상태 파일의 경로입니다(기본값: `/var/lib/clicklink/session.json`).                                                                                          |
| `--config <path>`          | 커넥터 구성 파일입니다. `troubleshooter` 섹션에서 세션 파일 경로를 가져옵니다.                                                                                              |
| `--gateway-url <url>`      | 세션 게이트웨이의 기준 URL입니다. 설정하면 명령이 OIDC bearer 토큰을 가져와 로컬 상태 파일 대신 게이트웨이를 호출합니다. `--session-file` 및 `--config`와 함께 사용할 수 없습니다.                         |
| `--gateway-audience <aud>` | OIDC 토큰이 바인딩되는 audience 클레임입니다(기본값: 게이트웨이의 기본값과 일치하는 `clicklink-clctl`). 게이트웨이 audience를 재구성한 경우에만 설정하십시오.                                        |
| `--gateway-issuer <url>`   | 게이트웨이가 검증하는 OIDC issuer입니다. 비어 있으면 Google 경로를 선택합니다. Google 이외의 IdP(Identity Provider)를 대상으로 device-code 흐름을 실행하려면 `--oidc-client-id`와 함께 설정하십시오. |
| `--oidc-client-id <id>`    | device grant가 활성화된 `--gateway-issuer`에 등록된 device-code 흐름용 공개 OIDC 클라이언트 ID입니다.                                                                   |
| `--token-file <path>`      | 미리 발급된 OIDC ID 토큰이 포함된 파일입니다. 이 토큰을 bearer로 사용하며 다른 토큰 provider를 우회합니다.                                                                           |
| `--gateway-ca <path>`      | 게이트웨이 인증서를 검증하는 CA 번들입니다(BYO 인증서). 설정하지 않으면 `gateway trust`로 고정한 인증서를 사용합니다. 고정 정보가 없는 self-signed 게이트웨이는 연결을 거부하도록 실패합니다.                        |

<div id="session-enable">
  ### 세션 활성화
</div>

| 플래그                | 설명                                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `--duration <dur>` | 세션이 활성 상태로 유지되는 시간(기본값 `4h`, 최대 `24h`)입니다.                                                         |
| `--reason <text>`  | 세션과 함께 기록할 선택적 자유 형식 사유(최대 256자)입니다.                                                               |
| `--user <name>`    | 로컬 파일 모드에서 기록할 운영자 아이덴티티입니다. 기본값은 `$SUDO_USER` 또는 `$USER`입니다. gateway 모드에서는 토큰으로 확인된 이메일이 기준이 됩니다. |

이미 활성 상태인 세션이 있으면 활성화할 수 없습니다. 먼저 비활성화하거나 만료될 때까지 기다리십시오.

<div id="session-disable">
  ### session 비활성화
</div>

session을 즉시 비활성화합니다. 활성 session이 없으면 아무 작업도 수행하지 않습니다.

<div id="session-status">
  ### 세션 상태
</div>

세션의 활성 여부, 활성화한 사용자 및 만료 시점을 표시합니다. `--output`(`-o`)으로 `table`(기본값) 또는 `json`을 선택합니다.

Kubernetes에서는 포트 포워딩을 통해 게이트웨이에 연결합니다.

```bash theme={null}
kubectl -n <connector-namespace> port-forward \
  statefulset/clicklink-connector-troubleshooter 8443:8443
clicklink clctl troubleshoot session enable \
  --gateway-url http://localhost:8443 \
  --duration 1h --reason "support ticket 1234"
```

<div id="gateway-trust">
  ## clicklink clctl troubleshoot gateway trust
</div>

VM에서 세션 게이트웨이는 self-signed TLS 인증서를 제공합니다. 이 명령어는 인증서의 SHA-256 fingerprint를 `~/.clicklink/clctl.yaml`에 기록하여 `session` 명령어가 이를 검증할 수 있도록 합니다. 고정된 fingerprint가 더 이상 일치하지 않으면 연결이 안전하게 실패합니다. 신뢰는 다음 두 가지 방법 중 하나로 대역 외에서 설정됩니다.

* [remote channel flags](#channel-flags)를 사용하면 이미 인증된 channel을 통해 VM에서 인증서를 직접 읽어 고정합니다.
* channel을 사용하지 않는 경우, 커넥터가 인증서를 생성할 때 log에 기록한 SHA-256 값을 `--gateway-fingerprint`로 전달합니다. 가져온 인증서는 일치하는 경우에만 고정됩니다. flag를 생략하면 아무것도 고정하지 않고 제시된 fingerprint를 출력합니다.

| Flag                             | 설명                                                                                    |
| -------------------------------- | ------------------------------------------------------------------------------------- |
| `--gateway-url <url>`            | 신뢰할 게이트웨이 기준 URL(필수)입니다. 예: `https://<vm-host>:8443`.                                 |
| `--gateway-fingerprint <sha256>` | 커넥터 log에 기록된 예상 SHA-256 fingerprint이며, 고정 전에 검증합니다. 콜론과 영문 대소문자는 무시됩니다.               |
| `--remote-cert-file <path>`      | channel을 통해 읽는 VM의 게이트웨이 인증서 경로입니다(기본값: `/var/lib/clicklink/gateway/tls/server.crt`). |

```bash theme={null}
clicklink clctl troubleshoot gateway trust \
  --gateway-url https://<vm-host>:8443 \
  --gateway-fingerprint <sha256-from-connector-log>
```

Kubernetes에서는 pinning을 사용하지 않습니다. CA에서 발급한 인증서를 사용하는 인그레스를 통해 게이트웨이를 노출하거나 포트 포워딩을 사용하십시오.

<div id="audit-tail">
  ## clicklink clctl troubleshoot audit tail
</div>

문제 해결사 감사 로그의 마지막 항목을 출력합니다. 각 줄에 하나의 JSON 객체가 포함되는 형식이며, 데몬이 허용하거나 차단한 명령마다 항목이 하나씩 기록됩니다. 이 명령은 로그를 읽기 전용으로 열며 수정하지 않습니다.

| 플래그                 | 설명                                                              |
| ------------------- | --------------------------------------------------------------- |
| `--lines <n>`, `-n` | 출력할 마지막 항목 수(기본값: 50).                                          |
| `--path <path>`     | 감사 로그 파일의 경로(기본값: `/var/log/clicklink/troubleshoot-audit.log`). |

커넥터 런타임 image에는 셸이 없으므로 Kubernetes에서는 이 명령이 지원되는 reader입니다:

```bash theme={null}
kubectl -n <connector-namespace> exec <troubleshooter-pod> -- \
  /clicklink clctl troubleshoot audit tail
```

<div id="access-provision">
  ## 액세스 프로비저닝
</div>

`clicklink clctl scraper access provision` 및 `clicklink clctl troubleshoot access provision`은 구성 요소별 인스턴스 액세스 번들, 즉 읽기 전용 ClickHouse 사용자와 해당 권한 부여, 그리고 구성 요소가 사용하는 Kubernetes ServiceAccount, RBAC, 토큰을 생성합니다. `--force`를 사용하면 이를 교체합니다. `init`는 설치 과정에서 이를 인라인으로 실행하며, 독립 실행형 명령어는 재실행 및 자격 증명 교체에 사용합니다.

| 플래그                                                                  | 설명                                                                                                                                                 |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--instance <name>`                                                  | 구성에 지정된 인스턴스 이름(필수)입니다.                                                                                                                            |
| `--server <url>`                                                     | Kubernetes API 서버 URL(필수)입니다.                                                                                                                      |
| `--ca-data <base64>`                                                 | 생성되는 kubeconfig에 사용할 Base64 인코딩 클러스터 CA 인증서입니다.                                                                                                    |
| `--config <path>`                                                    | 인스턴스 정보를 읽을 커넥터 구성 파일입니다.                                                                                                                          |
| `--target <shape>`                                                   | `systemd`(기본값: 원격 채널을 통해 번들을 VM으로 전송하거나 `--provider local`을 사용해 로컬에서 생성) 또는 `helm`(차트용 Kubernetes 시크릿으로 번들 푸시)입니다.                                 |
| `--target-namespace <ns>`                                            | 번들 시크릿이 생성될 네임스페이스입니다(`--target helm` 사용 시 필수).                                                                                                    |
| `--instance-namespace <ns>`                                          | (`--target helm`) 대상 ClickHouse 인스턴스의 네임스페이스입니다.                                                                                                   |
| `--force`                                                            | 기존 번들을 덮어씁니다. 재실행 및 자격 증명 교체에 사용합니다.                                                                                                               |
| `--secret-name <name>`                                               | 번들 시크릿 이름을 재정의합니다(기본값 `clicklink-connector-<component>-access-<instance>`).                                                                        |
| `--output-dir <path>`                                                | (`--target helm` 또는 `--provider local`) 번들이 생성될 루트 디렉터리입니다.                                                                                        |
| `--ch-admin-user <name>`                                             | 권한 부여를 적용할 ClickHouse 관리자 사용자입니다(기본값 `default`).                                                                                                   |
| `--ch-admin-password-stdin`                                          | stdin에서 ClickHouse 관리자 비밀번호를 읽습니다.                                                                                                                 |
| `--ch-user-suffix <suffix>`                                          | 프로비저닝된 ClickHouse 사용자 이름에 추가할 선택적 접미사입니다.                                                                                                          |
| `--ch-user-via <mode>`                                               | ClickHouse 사용자 프로비저닝 방식입니다. `sql`(기본값, 생성된 권한 부여를 `--ch-admin-user`로 적용) 또는 `cr`(SQL을 사용할 수 있는 관리자가 없는 operator 관리형 인스턴스의 사용자 지정 리소스에 사용자를 기록)입니다. |
| `--apply-ch-grants`                                                  | (`--target helm`) 생성된 권한 부여를 사용자가 직접 적용하도록 남겨두는 대신 `kubectl exec`를 통해 파드 내에서 적용합니다.                                                                |
| `--ch-pod <ref>`, `--ch-pod-namespace <ns>`, `--ch-container <name>` | (`--target helm`에서 `--apply-ch-grants` 또는 `--ch-user-via cr` 사용 시) exec를 실행할 ClickHouse 파드와 컨테이너를 선택합니다.                                           |
| `--token-duration <dur>`                                             | ServiceAccount 토큰 수명입니다(기본값 `2160h`, 90일, EKS에서는 권한 부여 기간이 최대 24시간).                                                                               |
| `--skip-restart`                                                     | 프로비저닝 후 구성 요소를 재시작하지 않습니다.                                                                                                                         |
| `--dry-run`                                                          | 실행 계획을 출력하고 종료합니다. Kubernetes, 원격 시스템 또는 ClickHouse에 쓰기 작업을 수행하지 않습니다.                                                                             |

구성 요소 하나의 인스턴스 자격 증명을 교체합니다:

```bash theme={null}
clicklink clctl scraper access provision --target helm \
  --target-namespace <connector-namespace> \
  --instance <instance-name> --instance-namespace <clickhouse-namespace> \
  --server <kubernetes-api-server-url> \
  --apply-ch-grants --ch-pod <clickhouse-pod-or-label-selector> --ch-pod-namespace <clickhouse-namespace> \
  --force
```

<div id="channel-flags">
  ## 원격 채널 플래그
</div>

`preflight`, `gateway trust`, `access provision`은 VM 대상에 연결하는 방식을 선택하는 공통 플래그 세트를 지원합니다.

| 플래그                                                                                         | 설명                                                                                                                                                        |
| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--provider <name>`                                                                         | 실행 채널입니다. 원격 VM에는 `ssh`, `aws`(SSM), `gcp`(IAP)를 사용하며, 대상 VM에서 직접 실행하는 경우에는 `local`을 사용합니다. 명시적으로 설정하지 않으면 공급자별 플래그를 기반으로 추론되지만, `local`은 자동으로 추론되지 않습니다. |
| `--ssh-host <host>`, `--ssh-user <user>`, `--ssh-port <port>`, `--ssh-identity-file <path>` | SSH 연결 정보(`--provider ssh`)입니다. 사용자, 포트, 키의 기본값은 SSH 구성에서 가져옵니다.                                                                                          |
| `--instance-id <id>`, `--region <region>`, `--profile <name>`                               | SSM용 EC2 인스턴스, 리전, 공유 구성 프로필입니다(`--provider aws`).                                                                                                        |
| `--project <id>`, `--zone <zone>`, `--instance-name <name>`                                 | IAP 터널링용 프로젝트, 영역, 인스턴스입니다(`--provider gcp`).                                                                                                             |