# CLI 참조

import { Tabs, TabItem } from '@astrojs/starlight/components';

`kubetail` CLI는 데스크톱에서 Kubetail을 사용하는 주요 진입점입니다. 웹 대시보드를 시작하거나, 로그를 터미널로 스트리밍하거나, 클러스터의 Kubetail 리소스를 관리할 때 사용할 수 있습니다.

## 전역 플래그

이 플래그들은 모든 명령에서 사용할 수 있습니다.

| Flag | Default | Description |
|------|---------|-------------|
| `--kubeconfig` | | kubeconfig 파일 경로 |
| `--in-cluster` | `false` | In-cluster Kubernetes 설정 사용 |
| `-c, --config` | `~/.kubetail/config.yaml` | 설정 파일 경로 |

## 명령어

### `kubetail serve`

dashboard server를 시작하고 기본 브라우저에서 웹 UI를 엽니다.

```sh
kubetail serve [flags]
```

**플래그**

| Flag | Default | Description |
|------|---------|-------------|
| `-p, --port` | `7500` | 수신할 포트 번호 |
| `--host` | `localhost` | 바인딩할 호스트 주소 |
| `-l, --log-level` | `info` | 로그 레벨 (`debug`, `info`, `warn`, `error`, `disabled`) |
| `--skip-open` | `false` | 브라우저를 열지 않음 |

**예시**

```sh
# dashboard 시작 (http://localhost:7500 에서 열림)
kubetail serve

# 사용자 지정 포트 사용
kubetail serve --port 8080

# 브라우저를 열지 않고 시작
kubetail serve --skip-open
```

---

### `kubetail logs`

컨테이너 또는 여러 workload container의 로그를 가져옵니다.

```sh
kubetail logs [source1] [source2] ... [flags]
```

**소스**

소스는 어떤 Pod 또는 컨테이너에서 로그를 스트리밍할지 식별합니다. 소스는 다음 구문을 사용합니다.

```
[namespace:]<resource>[/name[/container]]
```

| Example | Description |
|---------|-------------|
| `web-abc123` | default namespace 의 `web-abc123` Pod |
| `deployments/web` | default namespace 의 `web` Deployment |
| `deployments/*` | default namespace 의 모든 Deployment |
| `deployments/web/container1` | Deployment 내 특정 컨테이너 |
| `deployments/web/*` | Deployment 내 모든 컨테이너 |
| `frontend:web-abc123` | `frontend` namespace 의 Pod |
| `frontend:deployments/web` | `frontend` namespace 의 Deployment |

여러 소스를 지정할 수 있습니다.

```sh
kubetail logs <source1> <source2>
```

**플래그**

| Flag | Default | Description |
|------|---------|-------------|
| `--kube-context` | | 사용할 kubeconfig context |
| `-h, --head[=N]` | `10` | 처음 N개 레코드 반환 |
| `-t, --tail[=N]` | `10` | 마지막 N개 레코드 반환 |
| `--all` | `false` | 모든 레코드 반환 |
| `-f, --follow` | `false` | 새 레코드 스트리밍 |
| `--since` | | 지정 시점부터의 레코드 포함(포함) |
| `--until` | | 지정 시점까지의 레코드 포함(포함) |
| `--after` | | 지정 시점 이후의 레코드만 포함 |
| `--before` | | 지정 시점 이전의 레코드만 포함 |
| `-g, --grep` | | 정규식으로 레코드 필터링 (`--force` 필요) |
| `--region` | | region 으로 source Pod 필터링(쉼표 구분) |
| `--zone` | | zone 으로 source Pod 필터링(쉼표 구분) |
| `--os` | | 운영체제로 source Pod 필터링(쉼표 구분) |
| `--arch` | | CPU 아키텍처로 source Pod 필터링(쉼표 구분) |
| `--node` | | node 이름으로 source Pod 필터링(쉼표 구분) |
| `--raw` | `false` | 메타데이터 없이 원시 로그 메시지만 출력 |
| `--columns` | | 출력 열 설정(기본값 덮어쓰기) |
| `--add-columns` | | 기본 출력 열에 추가 |
| `--remove-columns` | | 기본 출력 열에서 제거 |
| `--with-cursors` | `false` | 페이징 커서 표시 |
| `--hide-header` | `false` | 테이블 헤더 숨기기 |
| `--all-containers` | `false` | Pod 내 모든 컨테이너의 로그 표시 |
| `--force` | `false` | 명령 강제 실행 (`--grep` 사용 시 필요) |

`--columns`, `--add-columns`, `--remove-columns` 플래그는 쉼표로 구분된 열 이름 목록을 받습니다: `timestamp`, `dot`, `node`, `region`, `zone`, `os`, `arch`, `namespace`, `pod`, `container`.

`--head`, `--tail`, `--all` 은 서로 배타적입니다. `--since` 와 `--after`, `--until` 과 `--before` 도 각각 서로 배타적입니다.

`--since`, `--until`, `--after`, `--before` 플래그는 다음을 허용합니다.
- ISO 8601 타임스탬프(예: `2006-01-02T15:04:05Z07:00`)
- 현재 시각 기준 ISO 8601 기간(예: 30분 전을 의미하는 `PT30M`) - `--since` 와 `--until` 에만 적용

**기본 동작**: `--since` 를 지정하지 않으면 tail 모드(마지막 10개 레코드)이며, `--since` 를 지정하면 head 모드가 사용됩니다.

**예시**

```sh
# Pod의 마지막 10개 레코드 tail
kubetail logs nginx

# Deployment tail
kubetail logs deployments/web

# 새 레코드 추적
kubetail logs deployments/web --follow

# 모든 레코드를 반환하고 계속 추적
kubetail logs deployments/web --all --follow

# 처음 100개 레코드 반환
kubetail logs nginx --head=100

# 지난 30분간의 레코드 반환
kubetail logs nginx --since PT30M --all

# 두 타임스탬프 사이의 레코드 반환
kubetail logs nginx --since 2006-01-02T15:04:05Z --until 2007-01-02T15:04:05Z --all

# 정규식으로 필터링 (--force 필요)
kubetail logs nginx --grep "GET /about" --force

# region 으로 Pod 필터링
kubetail logs deployments/web --region=us-east-1

# 원시 로그 메시지만 출력
kubetail logs nginx --raw
```

---

### `kubetail cluster`

Helm을 내부적으로 사용해 Kubetail 클러스터 리소스를 관리합니다(Helm을 별도로 설치할 필요는 없습니다).

```sh
kubetail cluster <subcommand> [flags]
```

#### `kubetail cluster install`

클러스터에 새 Kubetail release 를 생성합니다.

```sh
kubetail cluster install [flags]
```

**플래그**

| Flag | Default | Description |
|------|---------|-------------|
| `--kube-context` | | 사용할 kubeconfig context 이름 |

**예시**

```sh
kubetail cluster install
```

#### `kubetail cluster upgrade`

기존 Kubetail release 를 로컬에 उपलब्ध한 최신 chart version으로 업그레이드합니다.

```sh
kubetail cluster upgrade [flags]
```

**플래그**

| Flag | Default | Description |
|------|---------|-------------|
| `--kube-context` | | 사용할 kubeconfig context 이름 |

**예시**

```sh
kubetail cluster upgrade
```

#### `kubetail cluster uninstall`

기존 Kubetail release 를 클러스터에서 제거합니다.

```sh
kubetail cluster uninstall [flags]
```

**플래그**

| Flag | Default | Description |
|------|---------|-------------|
| `--kube-context` | | 사용할 kubeconfig context 이름 |

**예시**

```sh
kubetail cluster uninstall
```

#### `kubetail cluster list`

현재 설치된 Kubetail release 를 나열합니다.

```sh
kubetail cluster list [flags]
```

**플래그**

| Flag | Default | Description |
|------|---------|-------------|
| `--kube-context` | | 사용할 kubeconfig context 이름 |

**예시**

```sh
kubetail cluster list
```

#### `kubetail cluster repo`

Kubetail의 Helm chart 저장소를 관리합니다 (`https://kubetail-org.github.io/helm-charts/`).

```sh
kubetail cluster repo <subcommand>
```

| Subcommand | Description |
|------------|-------------|
| `add` | Kubetail chart 저장소를 Helm에 추가 |
| `update` | Helm의 Kubetail chart 저장소를 업데이트 |
| `remove` | Helm에서 Kubetail chart 저장소를 제거 |

**예시**

```sh
kubetail cluster repo add
kubetail cluster repo update
kubetail cluster repo remove
```

---

### `kubetail config`

Kubetail CLI 설정을 관리합니다.

```sh
kubetail config <subcommand>
```

#### `kubetail config init`

기본 설정 파일을 생성합니다.

```sh
kubetail config init [flags]
```

**플래그**

| Flag | Default | Description |
|------|---------|-------------|
| `--path` | `~/.kubetail/config.yaml` | 설정 파일의 대상 경로 |
| `--format` | `yaml` | 설정 파일 형식 (`yaml`, `json`, `toml`) |
| `--force` | `false` | 기존 설정 파일 덮어쓰기 |

**예시**

```sh
# ~/.kubetail/config.yaml 에 기본 설정 생성
kubetail config init

# JSON 형식으로 설정 생성
kubetail config init --format json

# 기존 설정 파일 덮어쓰기
kubetail config init --force

# 사용자 지정 경로에 설정 쓰기
kubetail config init --path /etc/kubetail/config.yaml
```

## 설정

CLI는 YAML(또는 JSON/TOML) 설정 파일로 구성할 수 있습니다. 기본적으로 `~/.kubetail/config.yaml` 에서 읽습니다. `kubetail config init` 으로 기본 설정 파일을 생성하거나 전역 플래그 `-c` / `--config` 로 사용자 지정 경로를 전달하세요.

<Tabs>
  <TabItem label="YAML">
```yaml
## Kubetail CLI Configuration File
#
# This file defines the behavior for the kubetail CLI tool,
# including logs command defaults and dashboard server settings.
#

## version ##
#
# Schema version for the configuration file
#
version: 1

## general ##
#
general:

  ## kubeconfig ##
  #
  # Path to the kubeconfig file to use for CLI requests.
  # If empty, the default path (~/.kube/config) or KUBECONFIG env var is used.
  #
  # Default value: ""
  #
  kubeconfig: ""

## commands ##
#
commands:

  ## logs ##
  #
  # Settings specific to the 'logs' subcommand
  #
  logs:

    ## kube-context ##
    #
    # The specific Kubernetes context to use.
    # If empty, the current active context is used.
    #
    # Default value: ""
    #
    kube-context: ""

    ## head ##
    #
    # The number of lines to show from the beginning of the log buffer
    #
    # Default value: 10
    #
    head: 10

    ## tail ##
    #
    # The number of lines to show from the end of the log buffer
    #
    # Default value: 10
    #
    tail: 10

    ## columns ##
    #
    # Full set of output columns for 'logs' records.
    # Allowed values: timestamp,dot,node,region,zone,os,arch,namespace,pod, container
    #
    # Default value: ["timestamp", "dot"]
    #
    columns:
      - timestamp
      - dot

  ## serve ##
  #
  # Settings for the dashboard server
  #
  serve:

    ## host ##
    #
    # The network interface the server should bind to.
    #
    # Default value: localhost
    #
    host: localhost

    ## port ##
    #
    # The TCP port the server will listen on.
    #
    # Default value: 7500
    #
    port: 7500

    ## skip-open ##
    #
    # If true, the CLI will not automatically open the browser
    # when the server starts.
    #
    # Default value: false
    #
    skip-open: false

## dashboard ##
#
# Settings for the web dashboard UI
#
dashboard:

  ## columns ##
  #
  # The default columns to show when displaying log records.
  #
  # Default value: ["timestamp", "dot"]
  #
  columns:
    - timestamp
    - dot
```
  </TabItem>
  <TabItem label="TOML">
```toml
# Kubetail CLI Configuration File
#
# Defines behavior for the kubetail CLI tool, including
# logs command defaults and dashboard server settings.

# Schema version for the configuration file
version = 1

[general]
# Path to kubeconfig. If empty, uses ~/.kube/config or KUBECONFIG env var.
kubeconfig = ""

[commands.logs]
# Specific Kubernetes context to use. If empty, uses active context.
kube-context = ""

# Number of lines to show from the beginning of the log buffer
head = 10

# Number of lines to show from the end of the log buffer
tail = 10

# Full set of output columns for 'logs' records.
# Allowed values: timestamp,dot,node,region,zone,os,arch,namespace,pod,container
columns = ["timestamp", "dot"]

[commands.serve]
# Network interface the server binds to
host = "localhost"

# TCP port the server listens on
port = 7500

# If true, don't automatically open browser when server starts
skip-open = false

[dashboard]
# The default columns to show when displaying log records.
columns = ["timestamp", "dot"]
```
  </TabItem>
  <TabItem label="JSON">
```json
{
  "version": 1,
  "general": {
    "kubeconfig": ""
  },
  "commands": {
    "logs": {
      "kube-context": "",
      "head": 10,
      "tail": 10,
      "columns": ["timestamp", "dot"]
    },
    "serve": {
      "host": "localhost",
      "port": 7500,
      "skip-open": false
    }
  },
  "dashboard": {
    "columns": ["timestamp", "dot"]
  }
}
```
  </TabItem>
</Tabs>