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

# 설치와 인증

> npm에서 CLI를 설치하고, 브라우저 OAuth로 인증하고, headless / CI 환경을 설정해요.

CLI는 npm에 `@theplato/tiro-cli`로 배포되고 Node.js 20+에서 동작해요. macOS, Linux, Windows를 지원해요.

## 1. 설치

<CodeGroup>
  ```bash npm theme={"system"}
  npm install -g @theplato/tiro-cli
  ```

  ```bash pnpm theme={"system"}
  pnpm add -g @theplato/tiro-cli
  ```

  ```bash yarn theme={"system"}
  yarn global add @theplato/tiro-cli
  ```

  ```bash bun theme={"system"}
  bun add -g @theplato/tiro-cli
  ```
</CodeGroup>

설치를 확인하세요:

```bash theme={"system"}
tiro --version
# → 0.3.1 (or later)
```

<Note>
  **시스템 요구 사항**: Node.js 20 이상. 배포되는 바이너리는 ESM 전용이라 Node 18은 import에서 에러가 나요.
</Note>

## 2. 로그인

```bash theme={"system"}
tiro auth login
```

이 명령은 기본 브라우저를 열어 Tiro의 OAuth Authorization Code + PKCE 플로로 이동해요. CLI는 redirect를 받기 위해 `http://127.0.0.1:<random-port>/callback`에서 일회용 로컬 HTTP 서버를 실행해요. 로그인하고 나면 JWT가 OS native 자격 증명 저장소에 저장돼요:

* **macOS** — Keychain
* **Linux** — Secret Service (`gnome-keyring` 또는 `kwallet` 필요)
* **Windows** — Credential Manager

확인하세요:

```bash theme={"system"}
tiro auth status
# ✓ Signed in
#   source:     keychain
#   hostname:   https://api.tiro.ooo
#   user:       <userId>
#   expires at: <ISO datetime>
#   token:      tk__...***
```

토큰 prefix만 유일하게 표시되는 조각이에요. 전체 bearer token은 절대 keychain을 벗어나지 않아요.

## 3. 로그아웃

```bash theme={"system"}
tiro auth logout
```

keychain 항목과 캐시된 Dynamic Client Registration ID를 지워요. 다음 `tiro auth login`은 새 DCR client를 등록해요.

## 4. 에이전트에 Tiro MCP 연결하기 (선택)

Claude Code(또는 MCP 호환 클라이언트)를 쓴다면, CLI는 `https://mcp.tiro.ooo/mcp`에 호스팅된 Tiro MCP를 위한 한 줄짜리 installer를 제공해요:

```bash theme={"system"}
tiro mcp install
# → claude mcp add --transport http tiro https://mcp.tiro.ooo/mcp
```

출력을 셸로 바로 파이핑하거나, 명령을 MCP 클라이언트의 config에 복사하세요. 구조화된 뷰(transport, URL, docs link)를 보려면 `tiro mcp info --json`을 실행하세요. CLI는 읽기 위주 플로(브라우징, 디스크 저장)를 다루고, MCP는 에이전트 루프 안의 인터랙티브한 tool 호출을 다뤄요. 전체 에이전트 계약은 패키지에 동봉된 [`AGENTS.md`](https://github.com/plato-corp/tiro-cli/blob/main/AGENTS.md)를 참고하세요.

## Headless, CI, 에이전트 환경

일부 환경은 브라우저를 열 수 없어요(CI, SSH, sandbox 에이전트, Docker). 그런 경우엔 `TIRO_TOKEN`을 직접 설정하세요. 여기 들어가는 값은 keychain을 override해요.

```bash theme={"system"}
export TIRO_TOKEN="$(security find-generic-password -s 'io.tiro.cli' -a default -w 2>/dev/null \
  | jq -r '.accessToken')"
tiro notes list --json
```

GitHub Actions에서:

```yaml theme={"system"}
- name: Run tiro
  env:
    TIRO_TOKEN: ${{ secrets.TIRO_TOKEN }}
  run: |
    tiro notes search "release notes" --since 1d --json > recent.jsonl
```

<Warning>
  전체 bearer token을 CI secret에 넣는 것은 180일짜리 Personal Access Token과 같아요. 신뢰할 수 있는 머신에서 `tiro auth logout && tiro auth login`을 실행하고 새 토큰을 secret 저장소에 복사해 rotate하세요.
</Warning>

## 설정 override

| Variable          | 용도                                                  |
| ----------------- | --------------------------------------------------- |
| `TIRO_TOKEN`      | Bearer token — keychain을 override                   |
| `TIRO_HOSTNAME`   | API base URL (기본값 `https://api.tiro.ooo`)           |
| `TIRO_OUTPUT_DIR` | export 명령의 기본 `--output-dir` (v0.3+)                |
| `NO_COLOR`        | ANSI 색상 비활성화 ([no-color.org](https://no-color.org)) |

호출별 override:

```bash theme={"system"}
tiro --hostname https://api.tiro-ooo.dev notes list      # dev environment
tiro notes get <guid> --json --no-color                  # script-friendly
```

## CLI 업데이트

<CodeGroup>
  ```bash npm theme={"system"}
  npm update -g @theplato/tiro-cli
  ```

  ```bash pnpm theme={"system"}
  pnpm update -g @theplato/tiro-cli
  ```

  ```bash yarn theme={"system"}
  yarn global upgrade @theplato/tiro-cli
  ```

  ```bash bun theme={"system"}
  bun update -g @theplato/tiro-cli
  ```
</CodeGroup>

→ 직접 해보는 예제를 보려면 [Quickstart](/ko/developers/cli/quickstart)로 이어가세요.