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

# CLI

> 터미널에서 URL을 Markdown으로 변환하세요 — LLM에 파이프하거나, 일괄 처리하거나, Obsidian에 저장할 수 있습니다

## 개요

Web2MD CLI를 사용하면 터미널에서 바로 어떤 URL이든 깔끔한 Markdown으로 변환할 수 있습니다. 브라우저를 열지 않고도 출력을 LLM에 파이프하거나, URL 목록을 일괄 처리하거나, Obsidian vault에 콘텐츠를 가져올 수 있습니다.

```bash theme={null}
npx web2md-cli https://example.com/article
```

<Note>
  CLI를 사용하려면 \*\*Node.js 18+\*\*가 필요합니다. `node -v`로 버전을 확인하세요.
</Note>

## 설치

별도 설치는 필요 없습니다 — `npx`로 바로 실행하세요.

```bash theme={null}
npx web2md-cli <url> [options]
```

또는 더 빠른 시작을 위해 전역으로 설치할 수 있습니다.

```bash theme={null}
npm install -g web2md-cli
web2md <url> [options]
```

## 모드

Web2MD CLI는 설정에 따라 세 가지 모드로 동작합니다.

<CardGroup cols={3}>
  <Card title="Local" icon="laptop">
    **기본 모드입니다.** API 키가 필요하지 않습니다. 페이지를 가져와 로컬에서 변환합니다. 대부분의 공개 웹사이트에서 작동합니다.
  </Card>

  <Card title="Server" icon="server">
    **API 키가 필요합니다.** `WEB2MD_API_KEY`를 설정하면 Reddit, Fandom/Wikia 등 서버 측 처리가 필요한 제한된 사이트를 이용할 수 있습니다.
  </Card>

  <Card title="Bridge" icon="bridge">
    **`--bridge` 플래그를 사용합니다.** Chrome 확장 프로그램을 이용해 정적 가져오기로는 접근할 수 없는 JS 렌더링 페이지나 로그인 보호 페이지를 가져옵니다.
  </Card>
</CardGroup>

## 플래그

| 플래그                   | 설명                                                                            |
| --------------------- | ----------------------------------------------------------------------------- |
| `--no-images`         | 출력에서 이미지 참조 제거                                                                |
| `--no-links`          | 출력에서 하이퍼링크 제거                                                                 |
| `--meta`              | YAML frontmatter 추가 (title, source, wordCount, tokenCount, readingTime, date) |
| `--json`              | JSON `{ markdown, metadata }` 형식으로 출력                                         |
| `-o, --output <file>` | 출력을 파일에 저장                                                                    |
| `--output-dir <dir>`  | 각 URL을 별도의 `.md` 파일로 저장                                                       |
| `--batch <file>`      | 파일에서 URL 목록 읽기 (한 줄에 하나씩, `#`은 주석)                                            |
| `--vault <dir>`       | Obsidian vault 모드: `<dir>/raw/`에 저장하고 `<dir>/INDEX.md`를 업데이트                  |
| `--concurrency <n>`   | 최대 병렬 요청 수 (기본값: 3, 최대: 20)                                                   |
| `--bridge`            | JS 렌더링 또는 로그인 보호 사이트에 Chrome 확장 프로그램 사용                                       |
| `-q, --quiet`         | 진행 메시지 숨기기                                                                    |

## 명령어

URL 변환 외에도, CLI에는 인증과 Library 동기화를 위한 두 가지 하위 명령어가 있습니다.

| 명령어                 | 설명                                          |
| ------------------- | ------------------------------------------- |
| `web2md login`      | 한 번 인증하고 API 키를 `~/.web2md/config.json`에 저장 |
| `web2md sync [dir]` | Web2MD Library를 로컬 디렉터리에 Markdown 파일로 동기화   |

### login

```bash theme={null}
npx web2md-cli login
```

브라우저 기반의 device authorization 흐름을 시작합니다. CLI가 `https://web2md.org`를 열고 승인할 코드를 표시합니다. 승인되면 API 키가 `~/.web2md/config.json`에 저장됩니다 — 매 셸마다 `WEB2MD_API_KEY`를 export할 필요가 없습니다. [MCP server](/docs/ko/advanced/mcp-server#인증)도 동일한 파일을 읽으므로, 여기서 한 번 로그인하면 MCP 도구 호출도 함께 인증됩니다.

브라우저 흐름 대신 키를 직접 붙여넣고 싶다면 다음을 사용하세요.

```bash theme={null}
npx web2md-cli login --key
```

이 명령은 표준 입력(stdin)으로 키(`w2m_...`)를 요청하고 동일한 방식으로 저장합니다. [대시보드](https://web2md.org/dashboard/api-keys)에서 키를 발급받으세요.

### sync

```bash theme={null}
npx web2md-cli sync [dir] [--tag <t>] [--full]
```

extension, 대시보드, API를 통해 저장한 모든 페이지를 담은 Library를 태그별로 정리되고 frontmatter가 포함된 Markdown 파일로 로컬 디렉터리에 동기화합니다. 로그인되어 있거나(또는 `WEB2MD_API_KEY`가 설정되어) 있어야 합니다.

| 플래그         | 설명                             |
| ----------- | ------------------------------ |
| `dir`       | 대상 디렉터리(기본값: `./web2md-vault`) |
| `--tag <t>` | 이 태그가 있는 항목만 동기화               |
| `--full`    | 증분 커서를 무시하고 전체 기록을 다시 스캔       |

기본적으로 동기화는 증분 방식입니다. `<dir>/.web2md-sync.json`에 커서를 추적해 이후 실행부터는 새 항목만 가져옵니다. 대상 디렉터리를 Obsidian(또는 Markdown을 읽을 수 있는 다른 도구)에 지정하면 Library를 노트처럼 탐색할 수 있습니다.

```bash theme={null}
npx web2md-cli login
npx web2md-cli sync ~/Documents/Web2MD-Library
```

## 환경 변수

| 변수                    | 설명                                                                         |
| --------------------- | -------------------------------------------------------------------------- |
| `WEB2MD_API_KEY`      | Reddit, 제한된 사이트, `sync`용 API 키 (`w2m_xxx`) — `~/.web2md/config.json`보다 우선함 |
| `WEB2MD_API_URL`      | API 기본 URL 재정의                                                             |
| `WEB2MD_EXTENSION_ID` | `--bridge` 모드용 Chrome 확장 프로그램 ID 재정의                                       |

<Tip>
  세션이 바뀌어도 유지되도록 셸 프로필(`~/.zshrc` 또는 `~/.bashrc`)에 다음을 추가하세요.

  ```bash theme={null}
  export WEB2MD_API_KEY="w2m_your_key_here"
  ```
</Tip>

## 사용 예시

### 기본 변환

```bash theme={null}
npx web2md-cli https://example.com/article
```

Markdown을 표준 출력(stdout)으로 출력합니다.

### LLM에 파이프하기

```bash theme={null}
npx web2md-cli https://react.dev/learn/thinking-in-react | llm "Summarize this page"
```

```bash theme={null}
npx web2md-cli https://docs.python.org/3/tutorial/classes.html | claude "Explain the key concepts"
```

### 파일로 저장

```bash theme={null}
npx web2md-cli https://example.com/article -o article.md
```

```bash theme={null}
npx web2md-cli https://example.com/article --meta -o article.md
```

`--meta` 플래그는 title, source URL, word count, token count, reading time, date가 포함된 YAML frontmatter를 앞에 추가합니다.

### 파일에서 일괄 처리

`urls.txt` 파일을 만듭니다.

```text theme={null}
# Research papers
https://arxiv.org/abs/2301.00001
https://arxiv.org/abs/2301.00002

# Blog posts
https://example.com/blog/post-1
https://example.com/blog/post-2
```

그런 다음 실행합니다.

```bash theme={null}
npx web2md-cli --batch urls.txt --output-dir ./research --concurrency 5
```

각 URL은 `./research` 디렉터리에 별도의 `.md` 파일로 저장됩니다.

### Obsidian vault로 가져오기

```bash theme={null}
npx web2md-cli --batch urls.txt --vault ~/Documents/MyVault
```

이 명령은 각 페이지를 `~/Documents/MyVault/raw/`에 저장하고, 변환된 모든 페이지의 링크로 `~/Documents/MyVault/INDEX.md`를 업데이트합니다.

### API 키로 Reddit 변환하기

```bash theme={null}
export WEB2MD_API_KEY="w2m_your_key_here"
npx web2md-cli https://www.reddit.com/r/LocalLLaMA/comments/example
```

<Warning>
  Reddit은 유효한 API 키가 필요합니다. 키가 없으면 Reddit의 봇 제한 정책으로 인해 Reddit URL 변환이 실패합니다.
</Warning>

### Bridge 모드

Chrome 확장 프로그램을 이용해 JS 렌더링 페이지나 로그인 보호 페이지를 처리합니다.

```bash theme={null}
npx web2md-cli --bridge https://app.example.com/dashboard
```

<Note>
  Bridge 모드를 사용하려면 Web2MD Chrome 확장 프로그램이 설치되어 있고 Chrome이 실행 중이어야 합니다. CLI는 Chrome의 네이티브 메시징 프로토콜을 통해 확장 프로그램과 통신합니다.
</Note>

### JSON 출력

```bash theme={null}
npx web2md-cli --json https://example.com/article
```

구조화된 출력을 반환합니다.

```json theme={null}
{
  "markdown": "# Article Title\n\nContent here...",
  "metadata": {
    "title": "Article Title",
    "source": "https://example.com/article",
    "wordCount": 1250,
    "tokenCount": 1680,
    "readingTime": 5,
    "date": "2026-04-11T10:30:00.000Z"
  }
}
```

프로그래밍 방식으로 활용하거나 `jq`에 파이프할 때 유용합니다.

```bash theme={null}
npx web2md-cli --json https://example.com/article | jq '.metadata.tokenCount'
```

## 최적화된 사이트

Web2MD에는 다음 사이트를 위한 내장 어댑터가 포함되어 있어 일반 변환보다 더 깔끔한 출력을 만들어냅니다.

<AccordionGroup>
  <Accordion title="최적화 지원 사이트">
    * **Wikipedia** — 깔끔한 기사 추출, 인포박스 처리
    * **arXiv** — 논문 초록 및 메타데이터
    * **Hacker News** — 댓글이 포함된 스레드
    * **GitHub** — Issues 및 Pull Requests
    * **Stack Overflow** — 질문과 답변
    * **dev.to** — 블로그 게시물
    * **Medium** — 기사 (페이월 미리보기 우회)
    * **Substack** — 뉴스레터 게시물
    * **OpenAI Docs** — 문서 페이지
    * **Mintlify 기반 문서** — Mintlify로 구축된 문서 사이트
    * **Reddit** — 게시물 및 댓글 (API 키 필요)
  </Accordion>
</AccordionGroup>

## 일반적인 워크플로

<AccordionGroup>
  <Accordion title="AI 에이전트에 문서 공급하기">
    ```bash theme={null}
    npx web2md-cli --batch docs-urls.txt --output-dir ./context --quiet
    ```

    AI 에이전트의 컨텍스트 디렉터리를 `./context`로 지정하면 근거 있는 답변을 얻을 수 있습니다.
  </Accordion>

  <Accordion title="연구 코퍼스 구축하기">
    ```bash theme={null}
    npx web2md-cli --batch papers.txt --vault ~/Obsidian/Research --meta --concurrency 10
    ```

    Obsidian에 색인화되고 검색 가능한 연구용 vault를 만듭니다.
  </Accordion>

  <Accordion title="LLM 입력을 위한 서식 제거">
    ```bash theme={null}
    npx web2md-cli --no-images --no-links https://example.com/article | llm "Analyze this"
    ```

    LLM에 파이프할 때 토큰 사용량을 줄이기 위해 이미지와 링크를 제거합니다.
  </Accordion>
</AccordionGroup>