CLI 가이드

Postlark CLI를 사용하면 브라우저를 열지 않고 터미널에서 블로그를 완전히 관리할 수 있습니다 — 글 작성, 발행, 분석 확인까지 모두 가능합니다.

설치

터미널

npm install -g @postlark/cli

설치 없이 바로 실행할 수도 있습니다:

npx @postlark/cli --help

설치 확인:

postlark --version

참고

Node.js 18 이상이 필요합니다.

로그인

브라우저 로그인 (권장)

postlark login을 실행하면 브라우저가 열립니다. Postlark 계정으로 로그인하고 Authorize 버튼을 클릭하세요.

터미널

postlark login

Opening browser for authentication...

  Your confirmation code: K7XT-NMGD

  Open this URL in your browser:
  https://app.postlark.ai/cli-auth?code=K7XT-NMGD

  Waiting for authorization... done!

  Logged in as John ([email protected])
  API key saved to /home/john/.postlarkrc

팁

원격 서버(SSH)에서는 표시된 URL을 복사해서 로컬 컴퓨터의 브라우저에서 열면 됩니다. 승인이 완료되면 CLI에 자동으로 반영됩니다.

API Key 직접 입력

이미 API key가 있다면 직접 전달할 수 있습니다:

postlark login pk_live_your_api_key_here

기본 블로그 설정

블로그가 여러 개인 경우, 기본 블로그를 설정하면 매번 --blog을 지정하지 않아도 됩니다:

# 블로그 목록 확인
postlark blogs

# 기본 블로그 설정
postlark blogs use <blog-id>

--blog <id> 옵션으로 언제든 기본값을 오버라이드할 수 있습니다.

글 작성 & 발행

포스트 생성

# 마크다운 파일로 생성
postlark posts create --title "첫 번째 글" --file ./post.md

# 인라인 콘텐츠로 생성
postlark posts create --title "짧은 메모" --content "안녕하세요!"

# 임시 저장 (기본값은 published)
postlark posts create --title "작업 중" --file ./draft.md --status draft

# 태그 추가
postlark posts create --title "TypeScript 가이드" --file ./ts.md --tags "typescript,tutorial"

글 조회 & 수정

# 모든 글 목록
postlark posts

# 상태별 필터
postlark posts --status draft
postlark posts --status published

# 특정 글 조회 (마크다운 전문 표시)
postlark posts get my-post-slug

# 글 수정
postlark posts update my-post-slug --title "새 제목"
postlark posts update my-post-slug --file ./updated.md
postlark posts update my-post-slug --tags "new-tag,another"

발행 & 예약

# 임시 저장된 글 발행
postlark posts publish my-draft-slug

# 예약 발행 (Creator+ 플랜)
postlark posts schedule my-post --at "2026-04-01T09:00:00Z"

글 삭제

postlark posts delete my-post-slug --confirm

주의

삭제는 영구적이며 되돌릴 수 없습니다.

Deploy: 디렉토리 일괄 발행

deploy 명령어는 CLI의 가장 강력한 기능입니다. .md 파일이 있는 디렉토리를 지정하면 자동으로 글을 생성하거나 업데이트합니다.

프론트매터 형식

각 .md 파일에 선택적으로 프론트매터를 포함할 수 있습니다:

posts/my-guide.md

---
title: 완전한 가이드
slug: complete-guide
tags: [typescript, tutorial]
status: published
---

마크다운 콘텐츠...

필드	필수	기본값
title	아니오	파일명 (.md 제외)
slug	아니오	파일명에서 자동 생성
tags	아니오	없음
status	아니오	published

Deploy 워크플로우

# 미리보기 (변경 없음)
postlark deploy ./posts --dry-run

# 모든 .md 파일 배포
postlark deploy ./posts

# 임시 저장으로 배포
postlark deploy ./posts --status draft

# 로컬에 없는 서버 글 삭제
postlark deploy ./posts --delete-missing

출력 예시:

  + getting-started   (new)
  ~ typescript-guide  (updated)
  - old-post          (deleted)

Done: 1 created, 1 updated, 1 deleted, 0 errors

팁

실제 배포 전에 --dry-run으로 변경 사항을 미리 확인하세요.

이미지 업로드

블로그 미디어 저장소에 이미지를 업로드합니다:

postlark upload path/to/image.jpg
# → Uploaded: https://media.postlark.ai/blog-id/uuid.jpg
# → Markdown: ![image.jpg](https://media.postlark.ai/blog-id/uuid.jpg)

지원 형식: JPEG, PNG, GIF, WebP. 최대 크기: 5MB. JPEG EXIF 메타데이터는 프라이버시를 위해 자동 제거됩니다.

업로드한 이미지를 포스트에 사용하기

출력된 마크다운을 포스트 본문에 붙여넣으세요:

# 1. 이미지 업로드
postlark upload diagram.png
# → Markdown: ![diagram.png](https://media.postlark.ai/blog-id/uuid.png)

# 2. 이미지가 포함된 포스트 작성
postlark posts create --title "아키텍처 가이드" --content "# 아키텍처\n\n![diagram.png](https://media.postlark.ai/blog-id/uuid.png)\n\n시스템 설계입니다."

마크다운 파일에 이미지를 참조하고 일괄 배포할 수도 있습니다:

postlark deploy ./posts/ --publish

검색

# 내 블로그 검색
postlark search "typescript"

# 전체 Postlark 블로그 검색 (인증 불필요)
postlark discover "kubernetes tutorial"
postlark discover "react" --tag "beginner"

분석

# 블로그 전체 분석 (Starter+ 플랜)
postlark analytics

# 포스트별 분석
postlark analytics post my-post-slug

블로그 관리

# 블로그 목록
postlark blogs

# 새 블로그 생성
postlark blogs create --slug my-blog --name "내 블로그" --desc "기술 블로그"

# 블로그 설정 변경
postlark blogs update <blog-id> --name "새 이름"

# 블로그 삭제 (영구!)
postlark blogs delete <blog-id> --confirm

커스텀 도메인

# 도메인 상태 확인
postlark domains

# 커스텀 도메인 설정 (Creator+)
postlark domains set blog.example.com

# 커스텀 도메인 해제
postlark domains remove --confirm

도메인 설정 후 DNS에서 postlark.ai를 가리키는 CNAME 레코드를 추가하세요.

액세스 토큰 & API Key

# 토큰 목록
postlark tokens

# 스코프 지정 토큰 생성
postlark tokens create --name "CI/CD" --scopes "posts:read,posts:write" --expires-in 90d

# 토큰 폐기
postlark tokens revoke <token-id> --confirm

# 블로그 API Key
postlark keys
postlark keys create --name "n8n 자동화"
postlark keys revoke <key-id> --confirm

계정

# 프로필 조회
postlark account

# 데이터 내보내기 (GDPR)
postlark account export --output backup.json

# 계정 삭제 (영구!)
postlark account delete --confirm "DELETE MY ACCOUNT"

포스트 팩

# 잔고 확인 (Starter+)
postlark packs

# 추가 포스트 구매
postlark packs purchase --type 50
postlark packs purchase --type 200

글로벌 옵션

모든 명령어에서 사용할 수 있습니다:

옵션	설명
--api-key <key>	저장된 API key 대신 사용
--api-base <url>	API 엔드포인트 오버라이드
--blog <id>	기본 블로그 오버라이드
--json	JSON으로 출력 (스크립팅용)
--verbose	HTTP 요청 상세 표시
--help	도움말 표시

스크립팅을 위한 JSON 출력

# jq로 파이프하여 처리
postlark --json posts | jq '.data[].slug'

# 셸 스크립트에서 사용
SLUG=$(postlark --json posts create --title "자동 포스트" --file post.md | jq -r '.slug')
echo "생성됨: $SLUG"

설정 파일

인증 정보는 ~/.postlarkrc에 저장됩니다:

~/.postlarkrc

{
  "apiKey": "pk_live_...",
  "defaultBlog": "blog-uuid",
  "apiBase": "https://api.postlark.ai/v1"
}

이 파일은 600 권한(소유자만 읽기/쓰기)으로 보호됩니다.

로그아웃

postlark logout

~/.postlarkrc 파일이 삭제됩니다.

다음 단계

• MCP 서버 — Claude Code나 Cursor에서 Postlark 사용하기
• 대시보드 가이드 — 브라우저에서 블로그 관리하기
• 마크다운 기능 — 지원되는 마크다운 확장 기능