velogger 0.2.0

velog(velog.io) 를 조회하고, 로그인한 내 계정의 글·반응을 다루는 LLM 에이전트용 비공식 CLI.
An unofficial velog CLI for LLM agents: browse velog, and act on your own account once you log in.

기능 · 빠른 시작 · 설치 · 로그인하기 · LLM 에이전트에 연결하기 · 문서

비공식 API 를 쓴다. 스펙이 예고 없이 바뀔 수 있고, 자동수집·자동작성은 velog 약관과 상충할 소지가 있으니 개인 용도로만 쓴다.

Claude, ChatGPT 같은 LLM 에이전트가 velog 를 다룰 때 셸로 부르는 도구다. 무엇을 할지는 사용자와 LLM 이 정하고, velog 의 조회 절차·요청 제한·로그인을 지키며 결과를 공통 JSON 으로 돌려주는 일은 CLI 가 맡는다. 이름은 velog 사용자를 부르는 말 "벨로거"에서 따왔고, velog 가 만든 공식 도구가 아니다. 같은 구조의 형제 프로젝트로 부동산 jibsa 와 항공권 baenggipyo 가 있다.

기능

• 조회는 로그인 없이 된다. 로그인돼 있으면 세션을 함께 보내 본인 비공개 글도 보인다
• 쓰기는 기본이 안전한 쪽이다. publish 는 기본이 임시저장이고 발행은 --publish 를 붙여야 한다. 댓글 삭제는 --yes 가 필요하고, 글 삭제 명령은 없다
• 발행은 신뢰 계정(is_trusted)만 된다. 캡차를 풀지 않고, 아니면 웹에서 발행하라고 안내한다
• 토큰·쿠키는 어떤 출력에도 나오지 않는다. 로그인 정보는 로그인 여부·username·is_trusted 만 보여 준다 (로그인에 대해)
• 결과는 JSON 이고 글마다 velog 주소(url)가 붙는다. 조회 범위·제한은 notes 로 알린다
• 모든 요청이 요청 제한을 지나고, 그 상태를 모든 velogger 프로세스가 함께 쓴다

명령별 인자·옵션·반환값은 velogger 사용법에 있다.

빠른 시작

uv tool install velogger        # 또는 pipx install velogger
velogger trending --limit 1

결과는 stdout 에 JSON 하나로 나온다 (에러는 stderr 에 JSON). 아래는 위 명령의 실제 출력에서 short_description·thumbnail 을 줄인 것이다 (2026-10-20 조회).

{
  "returned": 1,
  "posts": [
    {
      "id": "3b37cb3d-ef8f-4b16-bb52-059525d16784",
      "title": "AI Native FE 개발로의 전환, 150일간의 여정",
      "username": "teo",
      "display_name": "teo.v",
      "url_slug": "ai-native-fe",
      "url": "https://velog.io/@teo/ai-native-fe",
      "short_description": "AI만으로 개발하는 시대, FE 개발자의 업무는 어떻게 변했을까? …",
      "thumbnail": "https://velog.velcdn.com/images/teo/post/…/image.png",
      "tags": null,
      "released_at": "2026-10-15T00:15:36.325Z",
      "updated_at": "2026-10-19T22:38:20.895Z",
      "likes": 59,
      "comments_count": null,
      "is_private": null,
      "is_temp": null
    }
  ]
}

이어서 velogger post teo ai-native-fe 로 그 글의 본문을 마크다운으로 받는다. 로그인이 필요한 명령은 로그인하기를 먼저 한다.

로그인 없이 guide·trending·post 를 차례로 불러 본 실제 화면이다 (2026-10-21 녹화, 결과는 jq 로 일부 칸만 골랐다).

설치

Python 3.11 이상이 필요하고 (uv 로 설치하면 없어도 된다), macOS·Linux·Windows 에서 쓸 수 있다. 셋 중 하나만 하면 된다.

velogger --help      # 명령 목록이 나오면 성공
velogger limits      # 요청 제한 상태 JSON. 네트워크 요청은 보내지 않는다

설치하지 않고 한 번 써 보려면 uvx velogger --help 로 부른다. 아직 릴리스하지 않은 최신 수정은 uv tool install git+https://github.com/Rukkakka/velogger 로 받는다. 삭제는 uv tool uninstall velogger (pipx 는 pipx uninstall velogger) 다. velogger: command not found 가 나오면 새 터미널을 열거나 uv tool update-shell 로 ~/.local/bin 을 PATH 에 넣는다. 버전마다 바뀐 점은 변경 기록에 있다.

# 저장소를 받아 개발 설치 (코드를 고칠 때)
git clone https://github.com/Rukkakka/velogger && cd velogger
uv venv --python 3.11
uv pip install -e ".[dev]"
.venv/bin/velogger --help

자세한 개발 환경·검증 방법은 개발 환경에 있다.

로그인하기

velog 가입을 이메일로 했든 깃허브·구글로 했든, 계정 이메일로 로그인 링크를 받는다.

velogger login you@example.com          # 1) velog 가 그 주소로 로그인 링크를 보낸다
# 2) 메일 속 링크(velog.io/email-login?code=...)를 복사한다 (브라우저로 열지 말 것)
velogger login --code '<붙여넣기>'       # 3) 세션 저장
velogger whoami                         # 로그인 확인 (is_trusted 도 보여 준다)

브라우저에 이미 로그인돼 있으면 쿠키를 붙여넣어도 된다: velogger login --cookie 'name=value; ...'.

LLM 에이전트에 연결하기

에이전트에게는 LLM 사용 가이드 하나를 먼저 읽게 한다. 설치본에 들어 있어 velogger guide 로 바로 출력된다 (설치한 버전과 내용이 같고 네트워크를 쓰지 않는다). 지침 파일(CLAUDE.md, AGENTS.md 등)에 이렇게 적어 두면 된다.

velog 를 다룰 때는 velogger CLI 를 쓴다. 처음 쓰기 전에 `velogger guide` 를 실행해 읽고 그 규칙을 따른다.
로그인이 필요하면 사용자가 직접 `velogger login` 을 실행한다.

설정

설정 파일은 없다. 환경 변수만 쓴다.

Windows 에서 쓸 때

Windows 의 Python 은 출력 인코딩이 기본으로 UTF-8 이 아니다 (한국어 Windows 는 cp949). LLM 에이전트가 velogger 를 부르면 출력이 파이프로 넘어가는데, 이때 한글이 깨지거나 cp949 에 없는 문자(이모지 등)에서 오류가 날 수 있다. 아래처럼 사용자 환경 변수를 설정하고 새 터미널을 연다. macOS·Linux 는 따로 할 것이 없다.

setx PYTHONUTF8 1

왜 만들었나

LLM 이 velog 를 다루려면 비공식 API 를 추측해 호출하다 막히거나, 로그인·토큰을 어설프게 다루다 자격증명을 흘릴 수 있다. 이 CLI 는 조회·로그인 절차와 요청 제한을 지키고, 토큰을 안전하게(사용자 전용 파일, 출력 비노출) 보관하며, 결과를 LLM 이 읽기 좋은 JSON 으로 돌려준다.

로그인에 대해 (jibsa·baenggipyo 와 다른 점)

형제 프로젝트는 "로그인 없는 기능만" 이 원칙이지만, velogger 는 로그인을 포함한다. 대신 자격증명은 떳떳하게만 다룬다.

• velog 공식 로그인 API 로 인증하거나(이메일 매직 링크), 사용자가 직접 넘긴 쿠키만 쓴다.
• 브라우저 쿠키 저장소를 몰래 복호화해 꺼내 오지 않는다 (인포스틸러 기법이라 넣지 않는다). 소셜 OAuth 를 헤드리스로 가로채지 않는다.
• 로그인 code·쿠키는 사용자가 자기 터미널에서 직접 넣는다. 에이전트가 대신 다루지 않는다.
• 토큰·쿠키는 어떤 출력에도 나오지 않고, ~/.config/velogger/session.json 에 권한 0600 으로만 저장된다.

문서

사용 문서

• LLM 사용 가이드: 에이전트용 요약. 처음 읽을 문서
• 공통 사용 규칙: JSON 출력, 누락값, 오류 대응, 로그인·요청 제한
• velogger 사용법
• 변경 기록

개발 문서

• 공통 개발 규약 · 개발 환경 · 아키텍처 · 버전·릴리스
• velogger 개발 가이드

기여

버그·기능 제안은 이슈로 열고, 코드를 고치기 전에 개발 규약의 "꼭 지킬 것"(토큰·쿠키 비출력, 로그인은 사용자가, 캡차를 풀지 않음 등)을 읽는다. 개발 환경 설치와 검사는 개발 환경, 브랜치 → 커밋 → PR 절차는 작업 절차에 있다. 모든 변경은 PR 로 들어가고 CI(ruff·mypy·pytest·설치 확인)를 통과해야 한다.

라이선스

MIT