본문으로 건너뛰기

CLI

Blockstudio은 터미널에서 블록, 파일 기반 페이지, 데이터베이스 레코드, RPC 함수, cron 작업, 설정, WPML 언어 구성을 관리하는 WP-CLI 명령을 등록합니다.

블록

모든 블록 나열

셸
wp bs blocks list
코드
+----------------------------+---------------------+-----------+------------------------+
| name                       | title               | component | category               |
+----------------------------+---------------------+-----------+------------------------+
| my-theme/hero              | Hero                |           | my-theme               |
| my-theme/card              | Card                | yes       | my-theme               |
| my-theme/newsletter        | Newsletter          |           | my-theme               |
+----------------------------+---------------------+-----------+------------------------+

컴포넌트만 필터링

셸
wp bs blocks list --components

JSON 형식으로 출력

셸
wp bs blocks list --format=json

저장된 필드 검증

셸
wp bs blocks validate 42
wp bs blocks validate 42 57 --format=json

지정한 게시물 ID의 저장된 콘텐츠를 중첩된 innerBlocks을 포함해 bs_validate_block()을 사용하여 검사합니다. 블록을 렌더링하거나 동기화된 패턴 참조를 확장하거나 게시물을 수정하지 않습니다. Blockstudio 확장 기능이 없는 알 수 없는 블록은 건너뜁니다.

기본 표에는 게시물 ID, 0부터 시작하는 블록 경로, 블록 이름, 발견 코드, 필드 경로, 소스, 메시지가 표시됩니다. JSON에는 원래 value 및 expected 값도 포함됩니다. 중첩 블록의 블록 경로는 0/1이고 필드 경로는 cards/2/style일 수 있습니다. 두 경로는 서로 다릅니다.

발견 사항이 없으면 명령은 0으로 종료하고, 발견 사항이 있으면 1로 종료합니다. JSON 출력은 성공 시 []도 포함하는 일반 목록이므로, 명령이 1로 종료되더라도 자동화에서 읽을 수 있습니다. 게시물 누락, ID 누락, table 또는 json 이외의 형식은 오류입니다. 검증을 시작하기 전에 모든 ID를 검사합니다.

블록 렌더링

셸
wp bs blocks render
wp bs blocks render my-theme/hero my-theme/card
wp bs blocks render my-theme/card --attributes='{"variant":"wide"}'
wp bs blocks render my-theme/card --attributes=@card.json --format=json

등록된 블록을 페이지에서처럼 렌더링하고 템플릿에서 발생하는 모든 PHP 알림, 경고, 지원 중단 알림 및 예외 오류를 보고합니다. 테마는 CI에서 명령을 실행해 설치된 Blockstudio에 맞춰 블록을 스모크 테스트할 수 있습니다. 이름을 지정하지 않으면 구성 요소를 포함해 등록된 모든 블록을 렌더링합니다.

각 블록은 WP-CLI의 프런트엔드 컨텍스트에서 편집기의 삽입기 미리보기가 아닌, 편집기에 저장되는 형태인 blockstudio.attributes이 있는 블록 주석으로부터 do_blocks()을 통해 렌더링됩니다. 렌더링에 사용할 게시물은 설정되지 않습니다. 동적 아일랜드는 자리 표시자만이 아니라 실제 템플릿 본문을 렌더링하며, 부수적으로 출력되는 템플릿 내용은 보고서에서 제외됩니다.

명령 자체는 게시물이나 필드 값을 저장하지 않지만 템플릿과 렌더링 훅을 일반적인 PHP처럼 실행합니다. 이들은 데이터를 쓰거나 외부 서비스를 호출하거나 다른 부작용을 일으킬 수 있습니다. 신뢰할 수 있는 코드로 전용 테스트 사이트에서 실행하세요. 읽기 전용 샌드박스가 아닙니다.

렌더링 속성은 블록별로 선택됩니다.

사례 속성
example block.json의 example.attributes, 즉 편집기의 삽입기 미리보기가 사용하는 값입니다.
defaults 각 필드의 default입니다. example.attributes이 없는 블록에 사용되며, 명령은 각 필드마다 한 줄을 출력합니다.
attributes --attributes의 값으로 예시를 대체합니다.

--attributes은 저장 키를 기준으로 지정한 필드 값을 담은 JSON 객체 또는 @와 그 객체가 들어 있는 파일의 경로를 받으며, 블록 이름은 정확히 하나만 필요합니다. 예시로는 도달할 수 없는 템플릿 분기(예: 변형)에 접근할 때 사용하세요. 삽입기 미리보기에서 자리 표시자 이미지만 생성하는 예시 값은 건너뛰며, 예시의 innerBlocks은 렌더링하지 않습니다.

코드
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| block               | case     | level      | message                                                                       | file                                                                         | line |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+
| smoke/deprecated    | defaults | Deprecated | strlen(): Passing null to parameter #1 ($string) of type string is deprecated | /wordpress/wp-content/themes/smoke-theme/blockstudio/deprecated/index.php    | 1    |
| smoke/undefined-key | example  | Warning    | Undefined array key "subtitle"                                                | /wordpress/wp-content/themes/smoke-theme/blockstudio/undefined-key/index.php | 2    |
+---------------------+----------+------------+-------------------------------------------------------------------------------+------------------------------------------------------------------------------+------+

표에는 문제별로 한 행씩 표시됩니다. JSON 출력은 문제가 없는 블록을 포함해 렌더링된 블록마다 항목 하나가 있는 목록이므로, 자동화에서 사용된 사례를 확인할 수 있습니다.

JSON
[
  {
    "block": "smoke/branch",
    "case": "attributes",
    "problems": [
      {
        "level": "Warning",
        "message": "Undefined array key \"width\"",
        "file": "/wordpress/wp-content/themes/smoke-theme/blockstudio/branch/index.php",
        "line": 2
      }
    ]
  }
]

level은 Notice, Warning, Deprecated 또는 Error입니다. 예를 들어 루프 안에서처럼 같은 파일과 줄에서 반복되는 문제는 블록별로 한 번씩 보고합니다. @로 억제한 문제는 보고하지 않습니다. WordPress 자체의 지원 중단 알림(예: _deprecated_function()의 알림)은 WP_DEBUG이 활성화된 경우에만 발생합니다.

문제가 없으면 명령은 0으로 종료하고, 그렇지 않으면 1로 종료합니다. 알 수 없는 블록 이름, 읽을 수 없거나 유효하지 않은 --attributes, table 또는 json 이외의 형식은 오류입니다. 첫 번째 블록을 렌더링하기 전에 모든 이름을 검사합니다.

페이지

파일 기반 페이지 동기화는 명시적으로 실행해야 합니다. 일반적인 WordPress 요청은 전체 페이지를 검색하거나 페이지 게시물을 작성하지 않습니다. 콜드 런타임은 콘텐츠를 동기화하지 않고 경로를 복원하기 위해 컬렉션 매니페스트를 한 번 읽을 수 있습니다.

셸
wp bs pages sync

명령은 원하는 전체 인벤토리를 조정하고 검색, 생성, 업데이트, 변경 없음, 잠금, 보존, 제거 및 실패한 페이지를 보고합니다. 지문이 같으면 게시물이나 게시물 메타데이터를 쓰지 않습니다.

표 출력에는 변경, 잠금, 콘텐츠 보존, 제거된 페이지와 해당 게시물 ID가 표시됩니다. JSON에는 페이지 이름, 키, 게시물 ID, 정리 작업이 포함된 pages.<name>.preserved, pages.<name>.overwritten 및 removedPages 항목이 표시됩니다. 키 기반 병합 후 게시물이 동일하면 변경 없음으로 보고하며, 개정판을 만들거나 수정 타임스탬프를 갱신하지 않습니다.

기존 공개 상태는 유지됩니다. 파일이 소유한 제목 및 슬러그 대체는 경고로 출력됩니다. 게시물 필드 소유권을 참조하세요.

키가 지정된 편집기 콘텐츠를 보존하지 않고 관리 대상 콘텐츠를 교체하려면 --authoritative를 사용하고, 저장된 소스 ID와 관계없이 해당 실행을 전체 조정으로 보고하려면 --full을 사용하세요. 어느 쪽이든 매번 전체 목록을 비교합니다:

셸
wp bs pages sync --authoritative --full

전체 보고서가 필요한 배포 스크립트의 경우:

셸
wp bs pages sync --format=json

명령이 파싱하는 모든 페이지에서 블록이 저장하지만 렌더링하지 않는 속성을 확인합니다. 즉, Blockstudio 블록이 필드로 선언하지도 루트 요소로 전달하지도 않는 속성(예: 선언되지 않은 class)입니다. 표 출력에는 페이지와 블록별 경고가 표시되고, dropped 열에는 해당 개수가 집계되며, JSON 보고서는 이를 pages.<name>.droppedAttributes 아래에 나열합니다. 소스가 변경되지 않은 페이지는 다시 파싱하지 않으므로, 다음 변경 시점이나 파서를 변경하는 업그레이드 후 첫 동기화 때 보고됩니다.

검색 또는 조정 중 오류가 보고되면 명령은 실패로 종료됩니다. 페이지에서 PHP API 및 배포 ID 계약을 확인하세요.

데이터베이스

스키마 나열

셸
wp bs db schemas
코드
+-------------------+-------------+---------+---------------------+
| block             | schema      | storage | fields              |
+-------------------+-------------+---------+---------------------+
| my-theme/app      | subscribers | table   | email, name, plan   |
| my-theme/app      | logs        | jsonc   | action, details     |
| my-theme/app      | events      | storh   | title, status       |
+-------------------+-------------+---------+---------------------+

CRUD 작업

셸
# List records
wp bs db list my-theme/app subscribers

# List with filters
wp bs db list my-theme/app subscribers --plan=pro --limit=10

# Get a single record
wp bs db get my-theme/app subscribers 1

# Create a record
wp bs db create my-theme/app subscribers --email=a@b.com --plan=pro

# Update a record
wp bs db update my-theme/app subscribers 1 --plan=enterprise

# Delete a record
wp bs db delete my-theme/app subscribers 1

단일 스키마 블록의 경우 스키마 이름은 기본적으로 default입니다:

셸
wp bs db list my-theme/leads

JSONC 레코드를 Storh(으)로 마이그레이션

스키마에 이미 db/{schema}.jsonc 파일이 있고 해당 레코드를 Storh 파일 백엔드로 옮기려면 migrate를 사용하세요:

셸
wp bs db migrate my-theme/app subscribers --to=storh

단일 스키마 블록의 경우:

셸
wp bs db migrate my-theme/app --to=storh

이 명령은 정수 레코드 ID를 보존하고, uploads/blockstudio/db/{block-scope}/{schema}/에 기록하며, Storh 인덱스를 다시 작성하고, 대상 저장소를 확인하며, 원본 .jsonc 파일을 그대로 둡니다.

출력 형식

모든 목록 명령은 --format=table(기본값), --format=json 및 --format=csv를 지원합니다:

셸
wp bs db list my-theme/app subscribers --format=json

RPC

모든 함수 나열

셸
wp bs rpc list
코드
+-------------------+-------------+--------+----------------+---------+
| block             | function    | public | capability     | methods |
+-------------------+-------------+--------+----------------+---------+
| my-theme/app      | subscribe   | yes    |                | POST    |
| my-theme/app      | stats       |        | edit_posts     | POST    |
| my-theme/app      | get_status  |        |                | GET,POST|
+-------------------+-------------+--------+----------------+---------+

함수 호출

셸
wp bs rpc call my-theme/app subscribe --email=user@example.com

출력은 JSON입니다:

JSON
{
  "success": true
}

매개변수는 --key=value 플래그로 전달됩니다:

셸
wp bs rpc call my-theme/app load_more --offset=10 --limit=5

Cron

모든 작업 나열

셸
wp bs cron list
코드
+-------------------+----------+----------+---------------------+
| block             | job      | schedule | next_run            |
+-------------------+----------+----------+---------------------+
| my-theme/app      | cleanup  | daily    | 2026-03-17 00:00:00 |
| my-theme/app      | sync     | hourly   | 2026-03-16 15:00:00 |
+-------------------+----------+----------+---------------------+

작업 수동 실행

셸
wp bs cron run my-theme/app cleanup

예약된 시간과 관계없이 콜백을 즉시 실행합니다. 테스트와 디버깅에 유용합니다.

설정

모든 설정 표시

셸
wp bs settings list

특정 설정 가져오기

셸
wp bs settings get tailwind/enabled
wp bs settings get assets/enqueue

Tailwind

HTML을 CSS로 컴파일

셸
wp bs tailwind compile '<div class="flex items-center p-4">'

파일에서 컴파일

셸
wp bs tailwind compile --file=template.html

캐시 관리

셸
wp bs tailwind cache path    # show cache directory
wp bs tailwind cache clear   # clear compiled cache

SCSS

SCSS를 CSS로 컴파일

셸
wp bs scss compile '$color: red; .test { color: $color; }'

파일에서 컴파일

셸
wp bs scss compile --file=styles.scss

사용자 정의 필드

등록된 사용자 정의 필드 모두 나열

셸
wp bs fields list
코드
+-------+----------------+---------------------------+
| name  | title          | fields                    |
+-------+----------------+---------------------------+
| hero  | Hero Section   | heading, description, cta |
| card  | Card           | title, image, link        |
+-------+----------------+---------------------------+

에셋

모든 에셋 나열

셸
wp bs assets list

유형별 필터링

셸
wp bs assets list --type=global
wp bs assets list --type=admin
wp bs assets list --type=editor
wp bs assets list --type=registered

스크립팅

모든 명령은 쉽게 파이프 연결할 수 있도록 --format=json을 지원합니다:

셸
# Export all subscribers as JSON
wp bs db list my-theme/app subscribers --format=json > subscribers.json

# Count records
wp bs db list my-theme/app subscribers --format=json | jq length

# Batch delete
wp bs db list my-theme/app logs --format=json | \
  jq -r '.[].id' | \
  xargs -I {} wp bs db delete my-theme/app logs {}

콘텐츠 동기화

콘텐츠 동기화 프로젝트는 허용 목록에 포함된 WordPress 콘텐츠를 파일로 내보내고 해당 파일을 데이터베이스에 적용합니다. 명시적으로 실행하며 CLI 기반입니다. 페이지 로드나 관리자 초기화 시 동기화하지 않습니다.

구성, 파일 형식 및 파일 기반 데이터베이스 콘텐츠가 적합한 경우에 대한 안내는 콘텐츠 동기화를 참조하세요.

데이터베이스 콘텐츠를 파일로 가져오기

셸
wp bs content pull

가져오기 범위를 구성된 게시물 유형 또는 분류 체계 하나로 제한합니다:

셸
wp bs content pull --post-type=team_member
wp bs content pull --taxonomy=category

UID나 파일을 쓰지 않고 미리 보기:

셸
wp bs content pull --dry-run

파일을 데이터베이스에 적용

셸
wp bs content push

기록 없이 적용 계획 미리 보기:

셸
wp bs content push --dry-run

파일에 더 이상 존재하지 않는 콘텐츠 세트 소유 데이터베이스 게시물과 용어를 정리합니다:

셸
wp bs content push --prune --yes

--prune을 사용하면 Blockstudio는 모든 파일 변경 사항을 먼저 적용한 다음 파일에 더 이상 없는 콘텐츠 세트 소유 항목을 제거합니다. --yes가 없으면 데이터 삭제 작업을 실행하지 않습니다.

상태 확인

셸
wp bs content status

표에는 파일 기반 항목별로 unchanged, would-update, missing-db, conflict, locked 또는 orphaned 상태가 표시됩니다.

정적 사전 렌더링

캐시 자체는 정적 사전 렌더링을 참조하세요. 이 명령들이 캐시를 관리합니다.

오래된 항목 미리 데우기

셸
wp bs prerender warm

오래된 공개 URL을 대기열에 넣은 다음, 영구 웜 대기열에서 최대 warm.concurrency개의 작업을 다시 렌더링하고 JSON 요약에 queued, processed, warmed, skipped 및 failed 개수를 출력합니다. 콘텐츠와 사이트 변경 사항은 대체 작업을 자동으로 대기열에 추가합니다. 더 많은 대기열 작업을 처리하려면 명령을 다시 실행하거나 예약된 워머를 실행하세요. 렌더링에 실패한 URL은 오래된 상태로 남아 다음 실행 때 다시 대기열에 추가됩니다. graph 모드에서는 URL별 워머가 꺼져 있으며 명령은 아무것도 대기열에 추가하지 않습니다.

캐시 상태 보고

셸
wp bs prerender status

활성 ID, 파일, 바이트, 그래프 레코드, 대기열 상태, 조기 제공 맵 보고서, 범위별 적중/실패/빌드/오류 카운터를 보고합니다.

캐시 비우기

셸
wp bs prerender purge

현재 사이트의 사전 렌더링 문서를 제거합니다. 다음 익명 요청 또는 웜 패스에서 다시 생성합니다.

조기 제공 맵 확인 및 정리

셸
wp bs prerender map status
wp bs prerender map prune --dry-run
wp bs prerender map prune

map status는 설치 전체의 조기 제공 맵을 보고합니다. 여기에는 항목과 경로, 누락된 경로 문서, 사이트가 더 이상 존재하지 않는 orphaned 항목, 디렉터리가 사라진 dead 항목이 포함됩니다. map prune은 고아 항목과 유효하지 않은 항목을 제거하고 제거된 항목과 이유를 출력합니다. --dry-run은 기록 없이 같은 보고서를 출력합니다. 다른 도구가 소유한 맵은 건드리지 않습니다.

WPML

언어 구성 생성

셸
wp bs wpml config
wp bs wpml config --file=wp-content/themes/my-theme/wpml-config.xml

번역할 모든 등록 블록의 텍스트 필드와 첨부 파일 ID로 지정할 파일 필드를 선언하는 wpml-config.xml을 출력하거나 --file을 사용해 기록합니다. 기존 파일에서는 Blockstudio 마커 사이의 섹션만 대체됩니다. 무엇을 선언하며 파일을 최신 상태로 유지하는 방법은 WPML을 참조하세요.

블록 태그 마이그레이션

독립 실행형 스크립트가 접두사 및 별칭 축약 표기를 표준 <bs:namespace-slug> 표기로 바꿉니다. WordPress를 로드하지 않으며 --apply를 명시적으로 제공하지 않으면 기록하지 않습니다:

셸
php vendor/blockstudio/blockstudio/bin/migrate-block-tags.php \
  --root="$PWD" \
  --prefix-map=/tmp/project-prefixes.json \
  --known-blocks=/tmp/project-blocks.json \
  --aliases=/tmp/project-aliases.json \
  --report=/tmp/blockstudio-tag-migration.json \
  --dry-run

접두사 파일은 호출자가 소유한 접두사를 순서가 있는 네임스페이스에 매핑합니다. 알려진 블록 파일은 등록된 블록 이름의 JSON 목록입니다. 정확한 별칭은 선택 사항입니다. 보고서에는 결정론적 매핑, 변경 전후 해시, 알 수 없는 태그, 모호한 별칭, 동적 태그 및 주석, 코드 펜스, <pre> 또는 <code> 범위에서 발견된 예제가 포함됩니다.

스캐너는 쌍을 이루거나 중첩된 태그, 자체 닫는 마크업을 처리하며 PHP 문자열 안의 리터럴 태그도 포함합니다. 속성을 보존하고 태그 이름만 변경합니다. 주석과 코드 예제는 보고서에만 표시됩니다. 관련 없는 사용자 정의 요소는 무시합니다. 호출자가 의도적으로 --allow-unresolved를 전달하지 않는 한 알 수 없거나 모호하거나 동적인 사례가 남아 있으면 마이그레이션 적용을 차단합니다. 표준 형식으로 명령을 다시 실행하면 변경 사항이 발생하지 않습니다.

표준 표기가 필요한 이유와 해결하는 문제는 마이그레이션을 참조하세요.

제거

셸
wp bs teardown

설치가 소유하는 cron 이벤트와 정적 사전 렌더링 상태를 제거합니다. 즉, 현재 사이트의 조기 제공 맵 항목과 마지막 소유 항목이 사라진 뒤 공유 advanced-cache.php 드롭인 및 WP_CACHE 선언을 제거합니다. Composer 번들 설정처럼 플러그인 비활성화 훅이 없는 설치에서 깔끔하게 제거할 때 사용합니다. 구성 파일은 그대로 둡니다.