CLI

Hwaro는 사이트를 만들고, 빌드하고, 서빙하는 명령을 제공합니다.

전역 플래그

이 플래그들은 모든 최상위 명령에서 동작하며 CLI가 터미널에 출력하는 방식을 제어합니다. 스크립트, CI 로그, 깔끔한 출력이 필요한 AI 에이전트에 특히 유용합니다.

stdout이 TTY가 아니면(예: cat으로 파이프, 파일로 리디렉션, 대부분의 CI 환경) 색상은 자동으로 꺼집니다. 어디서든 색상을 강제로 끄려면 NO_COLOR=1만 설정하면 됩니다. 별도 플래그는 필요 없습니다.

# 스크립트·CI용 무음 빌드 — 경고와 오류만 표시됨
hwaro build --quiet

# stdout이 TTY여도 ANSI 이스케이프 없는 일반 텍스트 출력
NO_COLOR=1 hwaro doctor

오류 분류

분류된 실패 경로는 안정적인 오류 코드와 그에 대응하는 프로세스 종료 코드를 함께 내보냅니다. 스크립트, CI, 에이전트가 사람 대상 메시지를 파싱하지 않고도 안정적으로 분기할 수 있습니다.

텍스트 모드에서는 오류 줄 앞에 코드가 붙습니다:

Error [HWARO_E_USAGE]: missing <path> argument

--json(또는 --quiet)에서는 분류된 오류가 stdout에 구조화된 페이로드로 출력됩니다:

{
  "status": "error",
  "error": {
    "code": "HWARO_E_USAGE",
    "category": "usage",
    "message": "missing <path> argument",
    "hint": "Usage: hwaro new <path> [options] — run 'hwaro new --help' for details."
  }
}

분류되지 않은 실패는 기존 Error: <message> 형식과 종료 코드 1을 그대로 유지하므로, 이 규약은 기존 동작에 순수하게 추가만 됩니다.

명령

init

새 사이트를 만듭니다:

hwaro init                    # 기본값으로 즉시 초기화
hwaro init my-site            # my-site/에 초기화
hwaro init --wizard           # 대화형 위저드(TTY): 스캐폴드, 제목
hwaro init my-site --wizard   # 위저드; 디렉터리 프롬프트 생략 (경로는 인자 사용)
hwaro init my-site --scaffold blog
hwaro init my-site --scaffold docs
hwaro init my-site --scaffold book

대화형 모드:

대화형 터미널에서 --wizard를 주면 안내 흐름이 열립니다. 디렉터리, 스캐폴드, 사이트 제목을 차례로 묻고, 요약을 보여 준 뒤 확인을 받고 나서야 파일을 씁니다. 경로 인자를 함께 주면(hwaro init my-site --wizard) 위저드는 디렉터리 프롬프트를 건너뛰고 그 경로를 그대로 사용합니다.

--wizard 없이 실행하면 hwaro init은 기본값으로 즉시 초기화합니다 — 스크립트와 CI가 기존에 의존하던 동작 그대로입니다.

모든 스캐폴드는 읽는 사람의 OS 색상 모드를 자동으로 따릅니다(공유 토큰 시스템이 CSS light-dark() 쌍을 사용). 스타일이 있는 스캐폴드에는 auto → light → dark로 순환하며 선택을 localStorage에 기억하는 헤더 테마 전환 버튼이 들어 있습니다. 한 가지 모드로 고정하려면 css/style.css 끝에 :root { color-scheme: dark; }(또는 light)를 추가합니다.

GitHub 저장소의 원격 스캐폴드도 사용할 수 있습니다:

# GitHub 축약형
hwaro init my-site --scaffold github:user/repo
hwaro init my-site --scaffold github:user/repo/docs

# 전체 URL
hwaro init my-site --scaffold https://github.com/user/repo
hwaro init my-site --scaffold https://github.com/user/repo/tree/main/docs

원격 스캐폴드는 저장소에서 config.toml, templates/, static/, 콘텐츠 구조를 가져옵니다. 콘텐츠 파일은 프론트 매터(메타데이터)만 유지하므로 원본 본문 없이도 기대되는 페이지 구조를 확인할 수 있습니다. API 요청 제한을 피하려면 GITHUB_TOKEN 환경 변수를 설정합니다.

옵션:

new

새 콘텐츠 파일을 만듭니다:

hwaro new                                     # 대화형 위저드(TTY): 모든 항목을 프롬프트로 입력
hwaro new content/about.md
hwaro new content/blog/my-post.md
hwaro new posts/my-post.md -a posts
hwaro new my-post.md --section blog --draft --tags "go,web" --date 2026-03-22

프론트 매터 템플릿이 채워진 마크다운 파일을 만듭니다. 커스터마이즈 가능한 템플릿인 아키타입을 지원합니다.

대화형 모드:

대화형 터미널에서 <path> 없이 hwaro new를 실행하면 안내 위저드가 열립니다. 제목, 설명, (제목과 섹션에서 만들어 낸) 추천 경로, 태그, 날짜, 초안 여부, 아키타입을 차례로 묻고, 요약을 보여 준 뒤 확인을 받고 나서 파일을 씁니다. 이미 넘긴 플래그는 해당 프롬프트를 미리 채우므로 hwaro new -t "My Post"는 나머지만 묻습니다. 마지막 확인에서 Ctrl-D를 누르거나 n으로 답하면 아무것도 만들지 않고 취소합니다.

위저드는 비대화형 컨텍스트 — 파이프, CI, 에이전트, --json, --quiet — 에서는 절대 실행되지 않고 대신 분류된 HWARO_E_USAGE 오류를 출력하므로, 스크립트 호출은 예측 가능하게 유지됩니다. <path>(그리고 필요한 플래그)를 주면 프롬프트를 완전히 건너뜁니다.

옵션:

아키타입:

아키타입은 새 콘텐츠의 기본 프론트 매터를 정의하는 archetypes/ 디렉터리의 템플릿 파일입니다:

• archetypes/default.md - 모든 콘텐츠의 기본 템플릿
• archetypes/posts.md - hwaro new posts/...에 사용
• archetypes/tools/develop.md - hwaro new tools/develop/...에 사용

아키타입 파일은 플레이스홀더를 지원합니다: {{ title }}, {{ date }}, {{ draft }}, {{ tags }}, {{ description }}

아키타입 예시 (archetypes/posts.md):

---
title: "{{ title }}"
date: {{ date }}
draft: false
tags: []
---

# {{ title }}

아키타입 매칭 우선순위:

1. 명시적 -a 플래그 (예: -a posts는 archetypes/posts.md 사용)
2. 경로 기반 매칭 (예: posts/hello.md는 archetypes/posts.md 확인)
3. 중첩 경로는 상위 아키타입을 시도 (예: tools/dev/x.md는 tools/dev.md, 그다음 tools.md)
4. archetypes/default.md로 대체
5. 아키타입이 없으면 내장 템플릿 사용

build

사이트를 public/으로 빌드합니다:

hwaro build
hwaro build --drafts
hwaro build --minify
hwaro build -i /path/to/my-site
hwaro build -i /path/to/my-site -o ./dist

옵션:

--stream / --memory-limit (스트리밍 빌드):

페이지가 수천 개인 사이트에서는 렌더링된 HTML을 전부 메모리에 올리면 메모리 사용량이 커질 수 있습니다. 스트리밍 빌드는 Render 단계에서 페이지를 배치 단위로 처리하고, 각 배치를 디스크에 쓴 뒤 렌더링된 HTML을 해제합니다.

• --stream은 기본 배치 크기 500페이지로 스트리밍을 켭니다.
• --memory-limit SIZE는 스트리밍을 켜고 주어진 제한에 맞춰 배치 크기를 자동 계산합니다(휴리스틱: 페이지당 약 50KB). G, M, K 접미사를 받습니다(예: 2G, 512M, 256K).
• 대체 수단으로 HWARO_MEMORYLIMIT 환경 변수도 설정할 수 있습니다. CLI 플래그가 환경 변수보다 우선합니다.

빌드 결과물은 동일합니다 — 스트리밍은 빌드 중 메모리 사용량에만 영향을 줍니다.

--minify:

이 플래그는 생성된 파일을 줄이되 압축 전 출력과 시각적으로 동일하게 유지합니다:

• HTML: 주석을 제거하고(조건부 주석, SSI 지시문, <!-- more -->는 보존), 줄 끝 공백을 지우고, 태그 내부 공백을 접고(속성 사이 연속 공백은 한 칸으로, 따옴표로 감싼 속성 값은 그대로), 태그 사이 공백은 이웃 요소 분류에 따라 접습니다. 어느 한쪽 이웃이라도 블록 레벨 요소면 공백을 완전히 제거합니다(블록 형제의 시작·끝·사이 공백은 어차피 브라우저가 접습니다). 양쪽 이웃이 모두 인라인일 때만 한 칸을 남겨 <a>x</a> <a>y</a>처럼 눈에 보이는 간격을 보존합니다.
• JSON: 공백과 줄바꿈을 제거해 압축된 출력을 만듭니다.
• XML: 태그 사이 공백을 제거해 파일 크기를 줄입니다.

공백에 민감한 요소 — <pre>, <code>, <textarea>, <script>, <style>, <svg>, <math>, <noscript> — 는 공백 처리 전에 추출했다가 그대로 복원하므로 내용을 절대 건드리지 않습니다.

더 공격적인 축소(속성 따옴표 처리, 엔티티 축약 등)가 필요하면 html-minifier-terser나 minify-html 같은 전용 도구로 public/을 후처리합니다.

--cache (증분 빌드):

켜면 Hwaro가 파일 수정 시각과 콘텐츠 체크섬을 프로젝트 루트의 .hwaro_cache.json 파일에 기록합니다. 이후 빌드에서는 지난 빌드 이후 바뀐 파일만 다시 렌더링합니다. 캐시는 템플릿과 설정 체크섬도 추적합니다 — 템플릿이나 config.toml이 바뀌면 모든 항목이 자동으로 무효화되어 전체 페이지가 재빌드됩니다.

--full을 --cache와 함께 쓰면 깨끗하게 재빌드하면서도 다음 실행을 위한 캐시는 저장합니다:

hwaro build --cache --full

자세한 내용은 증분 빌드를 참고합니다.

--jobs (렌더 동시성):

기본적으로 Hwaro는 CPU 기반으로 자동 산정한 수의 동시 워커로 페이지를 렌더링합니다. --jobs N은 그 수의 상한을 정합니다. 생성 결과물은 절대 바뀌지 않고, 한 번에 렌더링하는 페이지 수만 달라집니다.

값을 낮추면 템플릿/Crinja 비중이 큰 사이트의 빌드가 빨라질 수 있습니다. 이런 페이지는 작은 객체를 많이 할당해서, 워커가 약 2개를 넘어가면 코어를 더 쓰는 이득보다 가비지 컬렉터의 할당 락 경합이 더 커집니다. 마크다운 비중이 큰 사이트(본문이 큰 페이지)는 계속 확장되므로 기본값은 자동으로 둡니다.

hwaro build --jobs 2   # 템플릿/숏코드가 많은 빌드라면 시도해 볼 것

설정하지 않으면 자동 기본값을 사용합니다. --no-parallel과 함께 쓰면 --jobs는 효과가 없습니다.

-i, --input:

지정하면 Hwaro가 빌드 전에 작업 디렉터리를 해당 경로로 바꿉니다. 먼저 cd하지 않고도 다른 디렉터리에 있는 사이트를 빌드할 수 있습니다.

• 모든 사이트 소스(config.toml, content/, templates/, static/)를 입력 디렉터리에서 읽습니다.
• -o 없이: 기본 출력 디렉터리 public/은 입력 디렉터리 안에 만들어집니다(즉, 그 사이트 자신의 public/ 폴더). 이것이 자연스러운 동작입니다 — hwaro build -i ../my-site는 ../my-site/public/을 만듭니다.
• -o와 함께: 출력 경로는 (입력 디렉터리가 아니라) 현재 디렉터리 기준으로 해석되므로, hwaro build -i ../my-site -o ./dist는 셸의 CWD에 있는 ./dist에 출력합니다.
• -i를 생략하면 동작은 그대로입니다 — 현재 디렉터리를 사용합니다.

serve

라이브 리로드(기본 활성화)가 있는 개발 서버를 시작합니다:

hwaro serve
hwaro serve --port 8080
hwaro serve --open
hwaro serve --access-log
hwaro serve --no-live-reload
hwaro serve -i /path/to/my-site
hwaro serve -i /path/to/my-site -p 8080

옵션:

대규모 사이트의 빠른 개발 서버: config.toml에 [og.auto_image] lazy_generate = true를 설정하면 hwaro serve 중 일괄 OG 생성을 생략합니다. 이미지는 첫 요청 시 생성됩니다. 전체 설명과 --fast-start를 곁들인 권장 워크플로는 자동 OG 이미지 문서를 참고합니다.

서버는 파일 변경을 감시해 자동으로 재빌드합니다. 무엇이 바뀌었는지에 따라 스마트 재빌드 전략을 사용합니다:

라이브 리로드:

라이브 리로드는 기본으로 켜져 있습니다. 서버가 모든 HTML 응답에 작은 WebSocket 클라이언트 스크립트를 주입하고, 재빌드가 성공할 때마다 연결된 브라우저가 자동으로 페이지를 새로 고칩니다 — 수동 새로 고침이 필요 없습니다. 클라이언트는 재연결에 지수 백오프(1초–30초)를 사용하므로 서버를 재시작해도 연결이 영구히 끊기지 않습니다.

이 동작을 끄려면 --no-live-reload를 줍니다(프로덕션과 비슷한 전달 방식을 로컬에서 테스트할 때 유용합니다). --live-reload 플래그는 기존 호출과의 하위 호환을 위해 아무 동작 없는 별칭으로 남아 있습니다.

-i를 지정하면 서버는 해당 디렉터리로 cd한 것처럼 동작합니다 — 그 프로젝트 루트를 감시하고 서빙합니다.

커스텀 응답 헤더 (--header / [serve.headers]):

프로덕션 리버스 프록시, CDN, 정적 호스팅이 설정하는 헤더(보안 헤더, Cache-Control, 커스텀 CORS 등)를 재현해, 정적 출력을 배포하기 전에 로컬에서 테스트하는 용도입니다.

[serve.headers]
X-Frame-Options = "SAMEORIGIN"
X-Content-Type-Options = "nosniff"
Referrer-Policy = "strict-origin-when-cross-origin"
# Cache-Control = "public, max-age=3600"

hwaro serve --header "X-Custom: foo" --header "Cache-Control: no-store"

• CLI --header 값이 config.toml의 같은 키보다 우선합니다.
• 헤더는 모든 개발 서버 응답(HTML, 에셋, 404, 리디렉션, 라이브 리로드가 주입된 페이지)에 붙습니다.
• 이 기능은 hwaro serve에만 적용됩니다. public/에 쓰이는 파일은 그대로입니다.

deploy

생성된 사이트를 설정된 대상에 배포합니다.

hwaro deploy [target ...]
hwaro deploy --dry-run

옵션:

doctor

설정, 템플릿, 구조 문제를 진단합니다 (최상위 단축 명령):

hwaro doctor               # 설정, 템플릿, 구조 문제 진단
hwaro doctor --fix         # 설정 값 정규화 (base_url 끝 슬래시, sitemap priority…)
hwaro doctor --approve     # 권장 설정 섹션을 config.toml에 추가
hwaro doctor --full        # 둘 다 (--fix --approve와 동일)

종료 코드. doctor는 보고된 가장 심각한 문제를 기준으로 분류된 종료 코드를 반환하므로, CI 파이프라인이 이 값으로 바로 게이트를 걸 수 있습니다:

경고(빈 base_url, 끝 슬래시, 중복 택소노미 이름 등)는 참고용이며 종료 코드를 바꾸지 않습니다.

콘텐츠 검증에는 hwaro tool validate를 사용합니다. 자세한 내용은 doctor를 참고합니다.

tool

콘텐츠 관리를 위한 유틸리티 도구:

# 콘텐츠 도구
hwaro tool list all             # 전체 콘텐츠 파일 목록
hwaro tool list drafts          # 초안 파일 목록
hwaro tool convert to-yaml      # 프론트 매터를 YAML로 변환
hwaro tool convert to-toml      # 프론트 매터를 TOML로 변환
hwaro tool convert to-json      # 프론트 매터를 JSON으로 변환
hwaro tool check-links          # 죽은 외부 링크 검사
hwaro tool stats                # 콘텐츠 통계 표시
hwaro tool validate             # 콘텐츠 프론트 매터와 마크업 검증
hwaro tool unused-assets        # 참조되지 않는 정적 파일 찾기

# 사이트 도구
hwaro tool platform netlify       # Netlify 설정 생성
hwaro tool platform vercel        # Vercel 설정 생성
hwaro tool platform cloudflare    # Cloudflare Pages 설정 생성
hwaro tool platform github-pages  # GitHub Pages 배포 워크플로 생성
hwaro tool platform gitlab-ci     # GitLab CI 설정 생성
hwaro tool platform codeberg-pages # Codeberg Pages(Forgejo Actions) 워크플로 생성
hwaro tool doctor                 # 설정/템플릿/구조 문제 진단
hwaro tool import hugo /path      # Hugo에서 가져오기
hwaro tool import jekyll /path    # Jekyll에서 가져오기
hwaro tool export hugo            # Hugo 형식으로 내보내기
hwaro tool export jekyll          # Jekyll 형식으로 내보내기
hwaro tool agents-md --write      # AGENTS.md를 파일로 쓰기

# JSON 출력
hwaro tool list all --json
hwaro tool stats --json
hwaro tool validate --json
hwaro tool unused-assets --json
hwaro tool doctor --json
hwaro tool check-links --json

서브커맨드:

공통 옵션:

자세한 사용법은 도구와 자동 완성을 참고합니다.

completion

셸 자동 완성 스크립트를 생성합니다:

hwaro completion bash    # Bash 자동 완성 스크립트
hwaro completion zsh     # Zsh 자동 완성 스크립트
hwaro completion fish    # Fish 자동 완성 스크립트

설치:

# Bash (~/.bashrc에 추가)
eval "$(hwaro completion bash)"

# Zsh (~/.zshrc에 추가)
eval "$(hwaro completion zsh)"

# Fish (~/.config/fish/config.fish에 추가)
hwaro completion fish | source

자세한 설치 방법은 도구와 자동 완성을 참고합니다.

예시

# 개발 워크플로
hwaro serve --drafts --verbose

# HTTP 접근 로그를 켠 개발
hwaro serve --access-log

# 라이브 리로드 없는 개발 (프로덕션과 비슷한 서빙)
hwaro serve --no-live-reload

# 프로덕션 빌드
hwaro build

# 커스텀 출력 디렉터리
hwaro build -o dist

# 특정 포트에서 미리 보기
hwaro serve -p 8000 --open

# 다른 디렉터리의 사이트 빌드
hwaro build -i ~/projects/my-blog

# 다른 위치의 프로젝트를 빌드해 현재 디렉터리에 출력
hwaro build -i ~/projects/my-blog -o ./output

# 증분 빌드 (변경 없는 파일 생략)
hwaro build --cache

# 전체 재빌드 강제 + 캐시 재생성
hwaro build --cache --full

# 대규모 사이트용 스트리밍 빌드
hwaro build --stream
hwaro build --memory-limit 512M

# 환경 변수로 스트리밍 빌드
HWARO_MEMORYLIMIT=1G hwaro build

# 다른 디렉터리의 사이트 서빙
hwaro serve -i ~/projects/my-blog --open

전역 옵션

함께 보기

• 설정 — CLI 플래그가 오버라이드하는 설정 옵션
• 빌드 훅 — 빌드 전/후 명령
• 도구와 자동 완성 — 유틸리티 서브커맨드