velog-cli

Velog 블로그 플랫폼용 비공식 CLI입니다.

사람이 직접 사용하는 터미널, 로컬 자동화 스크립트, LLM 에이전트가 Velog 글을 조회하고 작성/수정할 수 있도록 설계되었습니다.

참고: 이 프로젝트는 Velog의 비공식 GraphQL/웹 API를 사용합니다. Velog의 공식 프로젝트가 아닙니다.

주요 기능

• 글 조회 — 사용자 글 목록과 글 상세 조회
• 글 작성/수정 — JSON 입력 기반 마크다운 글 작성 및 수정
• 시리즈/프로필 조회 — 사용자 시리즈, 프로필, Velog 설정 조회
• 이미지 업로드 — 포스트/프로필 이미지 업로드
• 브라우저 인증 — Chrome/Edge 로그인 세션 기반 인증
• JSON 출력 — 에이전트와 스크립트가 파싱하기 쉬운 일관된 응답 형식

빠른 시작

설치

cd velog-cli
uv tool install --force --editable .

설치 후에는 uv run 없이 velog 명령을 바로 사용할 수 있습니다.

개발 환경까지 함께 준비하려면:

uv sync --extra dev

읽기 명령

velog profile show --username velog
velog series list --username velog
velog post list --username velog --limit 10
velog post show --username velog --url-slug velog-v3-news

로그인

velog auth login

Chrome 또는 Edge에 이미 Velog 로그인이 되어 있으면 쿠키를 읽어 즉시 인증 정보를 저장합니다. 로그인 세션이 없으면 브라우저를 열고, 로그인 후 같은 명령을 다시 실행하라고 안내합니다.

로그인 후 CLI가 계속 기다리며 쿠키를 가져오게 하려면:

velog auth login --browser edge --wait

글 작성/수정

velog post create --input examples/post-create.json
velog post update --input examples/post-update.json

명령 목록

인증 불필요

명령	설명	주요 옵션
velog profile show	사용자 프로필 조회	--username
velog series list	사용자 시리즈 목록 조회	--username
velog post list	사용자 글 목록 조회	--username, --limit, --cursor, --tag
velog post show	글 상세 조회	--id 또는 --username + --url-slug

인증 필요

명령	설명	주요 옵션
velog auth login	브라우저 세션 기반 로그인	--browser, --wait
velog auth load	env/file/기존 브라우저 세션에서 인증 로드	--source, --file, --browser
velog auth status	현재 인증 상태 확인	—
velog auth logout	로컬 저장 인증 정보 삭제	—
velog post create	새 글 작성	--input
velog post update	기존 글 수정	--input
velog media upload	이미지 업로드	--file, --type, --ref-id

고급/진단

명령	설명	주요 옵션
velog auth check	인증/엔드포인트 진단	—
velog debug run	GraphQL 디버그 호출	--endpoint, --query-file, --variables-file

인증

방법 1: 브라우저 로그인

기본 권장 흐름입니다.

velog auth login
velog auth login --browser chrome
velog auth login --browser edge --wait

지원 브라우저는 Chrome과 Edge입니다. --browser를 지정하지 않으면 기본 브라우저를 먼저 확인하고, 지원 대상이 아니거나 세션이 없으면 Chrome, Edge 순으로 fallback합니다.

macOS에서 특정 브라우저 쿠키를 처음 읽을 때 보안 확인이 뜰 수 있습니다. 이 경우 확인을 마친 뒤 auth login을 다시 실행하면 됩니다.

방법 2: 환경변수 또는 파일

자동화, CI, headless 환경, 브라우저 인증 문제 해결용 fallback입니다.

export VELOG_ACCESS_TOKEN="your_access_token"
export VELOG_REFRESH_TOKEN="your_refresh_token"
velog auth load --source env

velog auth load --source file --file credentials.json

.env 파일의 ACCESS_TOKEN, REFRESH_TOKEN도 인식합니다.

저장 위치

~/.config/velog-cli/credentials.json

인증 우선순위는 환경변수 > 로컬 저장 파일 > 미인증입니다.

출력 형식

기본 출력은 JSON입니다.

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "request_id": "uuid",
    "source": "velog",
    "operation": "profile.show"
  }
}

에러도 같은 형식을 사용합니다.

{
  "ok": false,
  "data": null,
  "error": {
    "code": "auth_required",
    "message": "Not logged in",
    "details": {}
  },
  "meta": {
    "request_id": "uuid",
    "source": "velog",
    "operation": "media.upload"
  }
}

플랫폼 지원

기능	macOS	Windows	Linux
공개 읽기 명령	검증 완료	지원 예상	지원 예상
환경변수/파일 인증	검증 완료	지원 예상	지원 예상
Chrome 브라우저 인증	검증 완료	검증 필요	검증 필요
Edge 브라우저 인증	검증 완료	검증 필요	검증 필요
글 작성/수정/이미지 업로드	검증 완료	브라우저 인증 검증 후 확인 필요	브라우저 인증 검증 후 확인 필요

자세한 검증 상태와 절차는 tests/verification-checklist.md, tests/README.md, tests/cross-platform/README.md를 참고하세요.

사용 예시

velog auth status
velog post list --username velog --limit 5
velog post show --username velog --url-slug velog-v3-news
velog media upload --file image.png --type post --ref-id POST_ID

입력 JSON 예시는 examples/ 디렉터리에 있습니다.

개발

uv sync --extra dev

테스트, 디버그, 인증 검증 절차는 tests/README.md에 정리되어 있습니다. 릴리스 준비는 RELEASE.md를 따르고, 변경 이력은 CHANGELOG.md에 기록합니다.

주의사항

• Velog의 비공식 API를 사용하므로 내부 변경 시 동작이 깨질 수 있습니다.
• 쓰기/업로드 기능은 인증 정보가 필요합니다.
• 과도한 자동 발행이나 과도한 호출은 운영 정책상 문제가 될 수 있습니다.

라이선스

MIT