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

# LogBrew CLI 레퍼런스: 명령어와 필터

> LogBrew 명령어, 필터, 커서 기반 페이지네이션, 실시간 감시, JSON 출력, 오류를 찾아보세요.

[오픈 소스 LogBrew CLI](https://github.com/LogBrewCo/cli)는 터미널에서 텔레메트리를 읽고 계정 데이터를 관리합니다. 설치, 로그인, 자주 하는 작업은 [CLI 사용하기](/ko/guides/cli)부터 읽으세요.

## CLI 작동 방식

터미널에서는 읽기 쉬운 텍스트를 사용하세요. 스크립트와 코딩 에이전트에서는 `--json`을 사용하세요.

계정 데이터를 읽으려면 계정 로그인이 필요합니다. 로그인을 시작하기 전에 `logbrew status --json`을 실행하세요. 브라우저 승인은 사람이 완료해야 합니다. 프로젝트 수집 키는 텔레메트리를 보냅니다. 계정 로그인을 대신할 수는 없습니다.

프로젝트 생성, 키 생성, 이슈 상태·우선순위·담당자 변경, 배포, 지원 티켓 업데이트는 계정 데이터를 바꿉니다. 실행하기 전에 작업과 대상이 맞는지 확인하세요.

모든 명령어를 보려면 `logbrew --help`를 실행하세요. 명령어의 플래그를 보려면 `logbrew read logs --help`처럼 명령어에 `--help`를 추가하세요. JSON 규칙은 `logbrew help json`을 실행하세요.

| 명령어 그룹 | 용도 |
| - | - |
| `login`, `whoami`, `me`, `logout` | 로그인을 시작하거나, 계정 식별 정보를 읽거나, 로컬 세션을 닫습니다. |
| `status`, `health`, `doctor`, `version`, `examples` | 접근 권한, 프로젝트 준비 상태, CLI 버전, 첫 실행 예제를 읽습니다. |
| `setup` | 로컬 매니페스트를 읽고 SDK 설정 계획을 출력합니다. 파일을 바꾸거나 설치 명령어를 실행하지 않습니다. |
| `projects` | 활성 프로젝트 목록을 읽습니다. |
| `projects repositories` | 연결된 저장소를 읽거나 저장소 1개의 구성 요소를 찾습니다. |
| `projects create`, `projects keys create` | 프로젝트를 만들거나 기존 프로젝트의 수집 키를 만듭니다. |
| `projects setup` | 기존 프로젝트에서 확인된 설정을 기록합니다. |
| `projects archive`, `projects delete` | 프로젝트를 보관하거나, 확인 후 영구 삭제합니다. |
| `usage`, `account usage` | 사용량, 한도, 할당량 상태, 초기화 날짜를 읽습니다. |
| `mcp grants`, `mcp revoke` | 계정에 연결된 MCP 클라이언트를 이름으로 나열하거나 연결 1개를 해지합니다. |
| `read` | 로그, 이슈, 액션, 릴리스, 메트릭, 트레이스 또는 항목 1개를 읽습니다. |
| `explain` | 이슈, 로그, 액션, 트레이스, 스팬, 메트릭, 릴리스에 대한 범위가 제한된 근거를 읽습니다. |
| `investigate issue` | 이슈 조사 근거를 읽거나 후보 배포를 검증합니다. |
| `issues archive`, `issues resolve`, `issues reopen` | 이슈 1개 또는 한 프로젝트의 이슈 최대 100개의 상태를 설정합니다. |
| `issues priority` | 이슈 1개 또는 한 프로젝트의 이슈 최대 100개의 우선순위를 설정합니다. |
| `issues assign`, `issues unassign` | 이슈 1개 또는 한 프로젝트의 이슈 최대 100개의 담당자(계정 또는 팀)를 설정하거나 제거합니다. |
| `issues assignees` | 한 프로젝트에서 이슈를 할당할 수 있는 계정과 팀을 나열합니다. |
| `issues owners` | 이슈 1개의 추천 소유자를 나열합니다. |
| `issues ownership` | 한 프로젝트의 소유권 규칙과 CODEOWNERS 파일을 읽거나 설정합니다. |
| `issues activity` | 이슈 1개의 변경 기록을 읽습니다. |
| `issues rule`, `logs rule` | 이슈 1개 또는 로그 시그니처 1개의 심각도 규칙을 설정합니다. |
| `inbox` | 다른 사람이 나나 내 팀에 할당한 이슈를 읽거나, 읽음으로 표시합니다. |
| `set issue`, `resolve`, `close`, `ignore`, `reopen` | 이슈 1개의 상태를 설정합니다. `close`는 `resolved`를 뜻합니다. `ignore`와 `ignored`는 `archived`를 뜻합니다. |
| `deploy` | 완료된 배포 1건을 기록합니다. |
| `debug-artifacts` | Apple 또는 Android 네이티브 디버그 파일을 업로드하거나 이미지 식별 정보 1개를 조회합니다. |
| `analytics` | 개요, 속성, 비교, 경로, 퍼널, 재방문, 라이프사이클을 읽습니다. |
| `support` | 지원 티켓을 만들고, 읽고, 답장하고, 닫고, 다시 엽니다. |
| `watch` | 실시간 로그, 이슈, 액션을 스트리밍합니다. |

## <span id="read-a-project-doctor-report">프로젝트 doctor 보고서 읽기</span>

`logbrew projects --json`에서 얻은 프로젝트 ID를 사용하세요.

```bash theme={null}
logbrew doctor --project "<project_id>" --json
```

이 명령어는 프로젝트 상태와 최근 로그 1개를 읽습니다. 프로젝트를 만들거나, 키를 바꾸거나, 설정을 기록하지 않습니다.

보고서에는 `status`, `checks`, `next`가 있습니다. 각 검사에는 `check`, `status`, `next`가 있습니다. 검사 항목은 `api`, `auth`, `project`, `ingest_key`, `setup`, `telemetry`, `logs`입니다.

종료 코드 `0`은 CLI가 보고서를 작성했다는 뜻입니다. 프로젝트가 준비되었다는 뜻은 아닙니다. 보고서의 `status`와 각 검사를 읽으세요. `not_checked`인 검사는 통과한 것이 아닙니다.

| 보고서 `status` | 의미와 다음 단계 |
| - | - |
| `auth_invalid` | 계정 접근 권한이 없거나 유효하지 않습니다. 사람이 `logbrew login`을 실행합니다. |
| `project_missing` | 이 계정은 프로젝트에 접근할 수 없습니다. `logbrew projects --json`에 있는 ID를 사용하세요. |
| `api_unreachable` | API 요청이 완료되지 않았습니다. 네트워크 연결을 확인한 다음 명령어를 다시 실행하세요. |
| `check_failed` | 요청이 실패했거나 응답이 유효하지 않습니다. 아무것도 바꾸지 말고 명령어를 다시 실행하세요. 다시 실패하면 [문제 신고](/ko/guides/report-a-problem)하세요. |
| `needs_ingest_key` | 프로젝트에 활성 수집 키가 없습니다. 프로젝트를 변경할 권한이 있을 때만 키를 만드세요. |
| `needs_setup` | SDK 설정이 필요합니다. [빠른 시작](/ko/quickstart)을 따르세요. |
| `needs_telemetry` | 설정은 시작했지만 LogBrew에 이 프로젝트의 텔레메트리가 없습니다. 테스트 이벤트를 보내세요. |
| `ready` | 프로젝트에 활성 키와 텔레메트리가 있습니다. 작업에 필요한 시그널을 읽으세요. |

프로젝트 읽기에 성공하면 `logs` 검사는 `visible`, `empty`, `unavailable`, `error`, `invalid_response` 중 하나입니다. 이 검사는 보고서 `status`를 바꾸지 않습니다. 로그 결과가 비어 있어도 다른 시그널에 대해서는 알 수 없습니다. 읽기에 실패한 것은 빈 결과와 다릅니다.

`next`는 복구 안내로 사용하세요. 계정이나 프로젝트 상태를 바꿀 권한을 주는 것은 아닙니다.

### 예: 계정 접근 권한이 없는 경우

계정 자격 증명이 없으면 이 명령어는 API 요청을 보내지 않습니다. 다음 보고서를 표준 출력에 쓰고 코드 `0`으로 종료합니다.

```json theme={null}
{
  "checks": [
    { "check": "api", "next": "run the API reachability check first", "status": "not_checked" },
    { "check": "auth", "next": "run logbrew login", "status": "missing" },
    { "check": "project", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "ingest_key", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "setup", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "telemetry", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "logs", "next": "resolve the prior check first", "status": "not_checked" }
  ],
  "next": "run logbrew login",
  "status": "auth_invalid"
}
```

이 보고서는 [프로젝트 API 진단](/ko/concepts/projects#diagnose-project-setup)과 다릅니다. API 필드인 `state`, `setup_status`, `next_action`이 들어 있지 않습니다.

## <span id="filters">필터</span>

| 필터 | 명령어 |
| - | - |
| `--project <project_id>` | logs, issues, actions, releases, metrics, traces, trace |
| `--release <release>` | logs, issues, actions, releases, metrics, traces, trace |
| `--environment <environment>` | logs, issues, actions, releases, metrics, traces, trace |
| `--service <service_name>` | logs, issues, actions, releases, metrics, traces |
| `--since 24h` | logs, issues, actions, releases, metrics, traces, analytics |
| `--until <RFC3339>` | logs, issues, actions, releases, metrics, traces, analytics |
| `--limit 100` | logs, issues, actions, releases, metrics, traces |
| `--severity error` | logs, watch |
| `--search checkout` | logs |
| `--trace <trace_id>` | logs |
| `--status unresolved` | issues (`unresolved`, `resolved`, `archived`) |
| `--priority high` | issues (`high`, `medium`, `low`) |
| `--assignee me` | issues (`me`, `none`, `my_teams`, 사용자 ID 또는 `team:<team_id>`) |
| `--status error` | traces (`error`, `ok`) |
| `--min-duration-ms <milliseconds>` | traces |
| `--name <name>` | actions, metrics |
| `--user <distinct_id>` | actions |

`--since`에는 `24h`나 `7d` 같은 기간 또는 RFC 3339 타임스탬프를 쓸 수 있습니다. `--until`에는 RFC 3339 타임스탬프를 쓸 수 있습니다. 끝 시각은 포함하지 않으며 `--since`보다 늦어야 합니다. ID로 이슈 1개를 읽을 때는 `--until`을 쓸 수 없습니다.

로그 심각도는 `info`, `warning`, `error`, `critical` 중 하나입니다. 이슈 상태는 심각도가 아니라 이슈의 처리 단계입니다. `--status ignored`는 `--status archived`의 이전 이름입니다. `--status open`은 `unresolved`를, `--status closed`는 `resolved`를 뜻합니다. `--assignee none`은 담당자가 없는 이슈를, `--assignee my_teams`는 내 팀의 이슈를 선택합니다. 그 밖의 `--assignee` 값은 `invalid_assignee`로 실패합니다.

CLI는 다음 별칭도 받습니다. `--project-id`, `--env`, `--service-name`, `--trace-id`, `--distinct-id`, 그리고 `--severity`의 별칭인 `--level`입니다. 새 스크립트에서는 표에 있는 이름을 사용하세요.

다음 명령어는 1일 동안의 오류를 읽습니다.

```bash theme={null}
logbrew read logs --severity error \
  --since 2026-10-01T00:00:00Z --until 2026-10-02T00:00:00Z --json
```

프로젝트 ID는 프로젝트를 선택합니다. 서비스 이름은 그 프로젝트 안의 구성 요소를 선택합니다. 공백이 있는 값은 따옴표로 감싸세요.

```bash theme={null}
logbrew read logs --project "<project_id>" \
  --service checkout-api --since 24h \
  --severity error --search "checkout failed" --json
```

하이픈으로 시작하는 검색 텍스트는 텍스트 앞에 `--`를 붙이세요.

```bash theme={null}
logbrew logs --json -- --timeout
```

## 이슈 발생 건 선택하기

이슈는 일치하는 발생 건을 묶습니다. 이슈를 읽으면 상태, 발생 횟수, 최초 발생 및 마지막 발생 시각을 알 수 있습니다.

```bash theme={null}
logbrew read issue "<issue_id>" --json
```

발생 건 1개의 근거를 보려면 `explain issue`나 `investigate issue`를 사용하세요. `--occurrence`가 없으면 LogBrew가 권장 발생 건을 선택합니다. 이 발생 건이 항상 최신 이벤트는 아닙니다. 최신 이벤트를 읽으려면 다음을 실행하세요.

```bash theme={null}
logbrew explain issue "<issue_id>" --occurrence latest --json
```

`--occurrence`에는 `recommended`, `first`, 또는 LogBrew가 반환한 발생 건 ID도 쓸 수 있습니다. 이 명령어들은 프로젝트, 릴리스, 환경, 시간 필터를 거부합니다. 근거를 비교하기 전에 선택된 발생 건의 타임스탬프를 읽으세요. 근거 필드는 [이슈 조사하기](/ko/guides/investigate-an-issue)를 참고하세요.

## <span id="change-issue-status-and-priority">이슈 상태와 우선순위 변경하기</span>

이슈 1개를 바꾸려면 이슈 ID 1개를 사용하세요.

```bash theme={null}
logbrew issues archive "<issue_id>" --json
logbrew issues priority high "<issue_id>" --json
```

`archive`는 `archived`를, `resolve`는 `resolved`를, `reopen`은 `unresolved`를 설정합니다. 우선순위는 `high`, `medium`, `low` 중 하나입니다. 직접 설정한 우선순위는 고정됩니다. 그렇지 않으면 우선순위는 이슈 심각도를 따릅니다.

이슈 여러 개를 바꾸려면 `--project`를 추가하세요. 모든 이슈가 그 프로젝트에 있어야 합니다. 명령어 1개로 이슈를 최대 100개까지 바꿀 수 있습니다.

```bash theme={null}
logbrew issues resolve "<issue_id_1>" "<issue_id_2>" \
  --project "<project_id>" --json
```

결과에는 이슈마다 항목이 1개씩 있습니다. 각 항목은 `updated`, `unchanged`, `not_found` 중 하나입니다. `unchanged` 이슈는 이미 요청한 값을 가지고 있었습니다. 네트워크 오류가 난 뒤에는 같은 명령어를 다시 실행해도 됩니다.

이 명령어들은 확인을 묻지 않습니다. 먼저 이슈 ID를 확인하세요. 이슈 읽기와 변경 결과에는 `ignored` 대신 `archived`가 나오며, 각 이슈의 `priority`, `priority_source`, `assignee`가 나옵니다. [이슈 응답](/ko/reference/telemetry-response-shapes#issue-response)을 참고하세요.

## 이슈 할당하기

이슈의 담당자는 최대 1개이며, 계정이나 팀 하나입니다. 프로젝트에서 할당할 수 있는 계정과 팀을 나열하세요.

```bash theme={null}
logbrew issues assignees --project "<project_id>" --json
```

이슈 1개를 계정이나 팀에 할당하거나, `me`로 자신에게 할당하세요.

```bash theme={null}
logbrew issues assign "<user_id>" "<issue_id>" --json
logbrew issues assign me "<issue_id>" --json
logbrew issues assign "team:<team_id>" "<issue_id>" --json
```

담당자를 제거하세요.

```bash theme={null}
logbrew issues unassign "<issue_id>" --json
```

상태와 우선순위처럼, `--project`를 추가하면 그 프로젝트의 이슈를 최대 100개까지 바꿀 수 있습니다. 계정은 프로젝트를 읽을 수 있어야 하고, 팀은 프로젝트의 조직에 속해야 합니다. 나나 내 팀에 할당된 이슈를 찾으려면 다음을 실행하세요.

```bash theme={null}
logbrew read issues --project "<project_id>" --assignee my_teams \
  --status unresolved --json
```

텍스트 출력에는 담당자 이름이 나오고, 팀이면 `team #<slug>`가 나옵니다. 계정에 이름이 없으면 이메일 주소가, 그다음에는 사용자 ID가 나옵니다. 담당자가 없는 이슈에는 `unassigned`가 나옵니다.

## 소유자, 변경 기록, 수신함

```bash theme={null}
logbrew issues owners "<issue_id>" --json
logbrew issues ownership --project "<project_id>" --json
logbrew issues ownership set --project "<project_id>" \
  --rules ownership.txt --codeowners .github/CODEOWNERS --json
logbrew issues activity "<issue_id>" --limit 50 --json
logbrew inbox --json
logbrew inbox read --json
```

`issues owners`는 추천 소유자와 확인한 근거를 나열합니다. `issues ownership set`은 각각 128 KiB 이하인 로컬 파일을 보냅니다. 빈 파일을 보내면 그 텍스트가 지워집니다. `issues activity`와 `inbox`는 1부터 200까지의 `--limit`, 그리고 `next_cursor`에서 가져온 `--cursor-time`과 `--cursor-id`를 받습니다. [이슈 소유자 찾기](/ko/guides/issue-workflow#find-who-owns-an-issue)를 참고하세요.

## 심각도 규칙 설정하기

```bash theme={null}
logbrew issues rule "<issue_id>" warning --json
logbrew logs rule "<log_id>" info --ignore --json
```

심각도는 `info`, `warning`, `error`, `critical`, `source` 중 하나입니다. `source`는 수집된 심각도를 다시 보여 줍니다. `--ignore`를 붙이면 일치하는 로그가 기본 로그 목록에서 숨겨집니다. `--ignore`가 없으면 규칙은 그 로그를 목록에 보이게 합니다.

## <span id="read-the-next-page">다음 페이지 읽기</span>

로그, 이슈, 액션, 메트릭, 트레이스는 커서 기반 페이지네이션을 지원합니다. 릴리스는 지원하지 않습니다. 첫 페이지에는 `--pagination cursor`를 사용하세요.

```bash theme={null}
logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 --json
```

응답에는 `logs`와 `next_cursor`가 있습니다. `next_cursor`가 null이 아니면 `time`과 `id`가 들어 있습니다. 이 값을 `--cursor-time`과 `--cursor-id`로 보내세요.

```bash theme={null}
logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 \
  --cursor-time "<returned_time>" \
  --cursor-id "<returned_id>" --json
```

모든 페이지에서 같은 필터와 한도를 유지하세요. `next_cursor`가 `null`이면 멈추세요. 다음 페이지가 있는지는 행 수가 아니라 커서로 판단하세요. 마지막 페이지는 비어 있을 수 있습니다.

```json theme={null}
{
  "logs": [],
  "next_cursor": null
}
```

이슈, 액션, 메트릭도 같은 형식을 사용하며, `logs` 대신 `issues`, `actions`, `metrics`가 들어갑니다.

## <span id="live-watch">실시간 감시</span>

`logbrew watch --json`은 실시간 로그, 이슈, 액션을 스트리밍합니다. 유형 1개만 스트리밍하려면 `logs`, `issues`, `actions` 중 하나를 추가하세요. `tail`, `follow`, `stream`은 `watch`의 별칭입니다. watch는 트레이스와 스팬을 지원하지 않습니다.

watch에는 `--json`이 필요합니다. 없으면 명령어가 `watch streams JSON for agents`를 출력하고 코드 `1`로 종료합니다.

watch의 이슈 이벤트는 보관된 이슈를 우선순위 없이 `ignored`로 표시합니다. 현재 상태와 우선순위를 알려면 이슈를 읽으세요.

watch는 `--severity error,critical`처럼 `--severity`만 받습니다. `logbrew watch actions`는 `--severity`를 받지 않습니다. CLI는 이벤트를 받은 뒤에 이 필터를 적용합니다. 서버가 보내는 양을 줄이지는 않습니다. watch에는 프로젝트, 릴리스, 환경, 시간 필터가 없습니다. 이런 필터가 필요하면 `read` 명령어를 사용하세요. 연결이 잠시 끊기면 CLI는 기다렸다가 다시 연결합니다.

## <span id="read-results-and-errors">결과와 오류 읽기</span>

`--json`은 명령어 앞이나 뒤에 붙이세요. 출력을 사용하기 전에 종료 코드를 읽으세요. 사람이 읽는 출력을 파싱하지 마세요. 버전에 따라 바뀔 수 있습니다.

| 종료 코드 | 의미 |
| - | - |
| `0` | 성공입니다. JSON이 표준 출력에 나옵니다. |
| `1` | 명령어가 실행 중에 실패했습니다. 예를 들어 API 오류나 네트워크 오류입니다. |
| `2` | CLI가 실행 전에 명령어를 거부했습니다. |

성공 출력은 API 응답 형식을 그대로 유지합니다. 배열일 수도 있고 객체일 수도 있습니다. 커서 기반 페이지네이션 없이 로그를 읽으면 배열을 반환합니다. 빈 배열은 일치하는 로그가 없다는 뜻입니다. 오류가 아닙니다.

오류는 표준 오류로 나옵니다. 예외는 `debug-artifacts --json`이며, 이 명령어는 오류를 표준 출력에 씁니다. JSON 오류에는 `ok`, `error`, `message`, `next`가 있습니다. 고정된 실패 코드로는 `error`를 사용하세요. `next`가 제안하는 명령어를 실행하기 전에 `next`를 검토하세요.

예를 들어 `logbrew watch traces --json`은 코드 `2`로 종료하고 다음을 출력합니다.

```json theme={null}
{
  "ok": false,
  "error": "unknown_resource",
  "message": "unknown resource: traces",
  "next": "use logbrew traces for recent traces, or logbrew trace <trace_id> for one trace"
}
```

`logbrew read logs --limit 0 --json`은 코드 `2`로 종료하고 다음을 출력합니다.

```json theme={null}
{
  "ok": false,
  "error": "invalid_limit",
  "message": "invalid limit: 0",
  "next": "use --limit with a positive whole number"
}
```

값을 고친 다음 명령어를 다시 실행하세요. 거부된 명령어는 빈 결과가 아닙니다. HTTP 오류는 [API 오류](/ko/reference/api-errors)를, API 직접 요청은 [텔레메트리 API](/ko/reference/telemetry-api)를 참고하세요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.