Task 명령어

이 문서는 비공개 호스트 환경에 이미 접근 권한이 있는 Nexia 유지관리자를 위한 참고 자료입니다. Core는 외부 개발자에게 배포하지 않습니다. 아래 호스트 명령은 공개 CLI·클라우드 샌드박스의 선행 조건이 아닙니다. 외부 개발자는 빠른 시작을 따라주세요.

호스트 명령은 Core 루트에서 실행합니다. 명령을 찾거나 일반 App 개발 환경을 시작하세요.

코드 예시

Shell

task help
task dev:up:core12

아래에서 인자 전달, 실행 모드, 초기화 범위를 확인합니다.

시그니처

Core 저장소 root에서 Task를 실행합니다.

코드 예시

Shell

task <task-name> [VARIABLE=value] [-- <forwarded arguments>]1

Taskfile.yml이 tasks/ 아래 recipe를 포함합니다. :로 구분된 각 부분도 명령 이름에 포함됩니다. 예를 들어 task dev:up:typesense 전체가 명령 하나입니다. 현재 목록은 언제든 작업 영역별로 묶어 확인합니다.

코드 예시

Shell

task help1

최소 예시

가장 짧은 일반 개발 사이클은 다음과 같습니다.

코드 예시

Shell

task up
task status
task logs -- app  # Ctrl+C로 로그 추적 종료
task down1234

task up은 유일한 짧은 시작 alias이며 task dev:up:core를 뜻합니다. Script와 문서에서는 결과 구성이 드러나는 profile 이름을 쓰는 편이 좋습니다.

인자

전달 인자

-- 뒤의 내용은 Task가 해석하지 않고 recipe가 호출하는 도구로 전달합니다.

형식	전달 대상	예시
`task logs -- <service>`	`docker compose logs -f`	`task logs -- typesense`
`task artisan -- <command>`	`app` 안 `php artisan`	`task artisan -- route:list --no-ansi`
`task composer -- <arguments>`	`app` 안 Composer	`task composer -- show amuzcorp/nexia-app-sdk-laravel`
`task pnpm -- <arguments>`	`app` 안 pnpm	`task pnpm -- why react`
`task test -- <path-or-options>`	PHP test runner	`task test -- tests/Feature/Agent`
`task frontend:test -- <options>`	Vitest	`task frontend:test -- --run`

Task 변수

Task 변수는 전달 인자가 아니라 NAME=value 형식입니다.

패키지 명령은 packages/ 아래에 있는 SDK와 App의 소스 폴더를 다룹니다. 로컬 소스 목록은 PACKAGES=...로 전달해 따로 저장하는 package key 목록이며, 생성된 로컬 Composer 설정이 어느 소스 폴더를 사용할지 결정합니다.

변수	사용하는 명령	동작
`MODE=core\|agent\|runtime\|typesense\|full`	`dev:rebuild`, `dev:reset`, `dev:restore`	최종 실행 프로필 선택. 기본값 `core`
`PACKAGES=key,...`	`setup`, `dev:rebuild`, `apps:checkout`, `apps:status`, `apps:update`, `apps:add`, `apps:remove`	최초 선택 또는 status/update subset 전달. setup 뒤에는 `apps:add`와 `apps:remove`만 선택을 바꾸며 setup/rebuild/checkout은 교체를 거부
`TENANT=<id>`	`db:tenant:migrate`, `db:tenant:seed`, `nexia-db:audit`	tenant 하나 선택
`SNAPSHOT=<name>`	`dev:snapshot`, `dev:restore`	수동 QA checkpoint 이름. 기본값 `baseline`
`SCENARIO=<name>`	`perf:scenario`	성능 scenario 하나 선택
`PERF_TENANT=<id>`	`nexia-perf:provision-fixture`	`perf-wave1` fixture tenant 변경

실행 프로필

시작 명령은 최종 프로필로 수렴합니다. 선택된 서비스는 켜고 선택하지 않은 선택 서비스는 끄며, 이미 있는 Compose 컨테이너는 재사용합니다. core에서 runtime으로 바꿔도 app이나 database가 하나 더 생기지 않습니다.

프로필	명령	실행 서비스	용도
core	`task dev:up:core` 또는 `task up`	`app`, `vite`, `postgres`, `redis`	일반 Core·SDK·App 작업
agent	`task dev:up:agent`	core + `agent-gateway`, `agent-gateway-edge`, `horizon`	큐 기반 파일 첨부를 포함한 Agent Gateway 작업
runtime	`task dev:up:runtime`	core + `horizon`, `scheduler`, `reverb`	큐·예약 작업·WebSocket
typesense	`task dev:up:typesense`	core + `typesense`	Typesense 기반 Search
full	`task dev:up:full`	core + Agent Edge·Gateway, runtime 서비스, `mailpit`, `clamav`, `typesense`	여러 서비스를 엮는 end-to-end 검증

위 구성은 각 프로필의 기본 서비스 집합입니다. Reverb backend 또는 browser key가 설정돼 있으면 선택한 모든 프로필이 reverb를 추가로 실행하고 정지 목록에서는 제외합니다. Agent 답변 stream은 SSE를 유지하며, Reverb는 Agent task 변경을 포함한 Shell realtime 무효화를 전달합니다.

의미가 모호한 bare task dev:up, task full, task agent:up은 두지 않습니다. 결과 서비스 구성이 명령에 드러나도록 프로필 이름을 사용합니다.

환경과 상태 확인

명령	Alias	용도
`task setup [PACKAGES=key,...]`	—	새 Core 소스 폴더 준비. 최초에는 로컬 패키지 소스 없음, 이후 선택 생략 시 저장된 목록 유지
`task dev:down`	`task down`	volume을 보존하고 로컬 서비스 전체 정지
`task dev:status`	`task status`, `task ps`	서비스 상태 표시
`task dev:logs`	`task logs`	전체 로그 또는 `--` 뒤 서비스 로그 추적
`task dev:reload-app`	`task app:reload`	로컬 Octane `app` 컨테이너만 재시작하고 healthy 상태까지 대기
`task dev:doctor`	`task doctor`	런타임과 seed 기준 상태 진단
`task dev:doctor-container`	—	컨테이너 안에서 환경 진단
`task dev:rebuild`	`task rebuild`	저장된 로컬 소스 목록을 유지하며 의존성 갱신, 선택한 실행 프로필 image와 frontend asset 재빌드
`task dev:snapshot`	—	DB와 tenant file을 이름 있는 checkpoint로 저장
`task dev:restore`	—	checkpoint 복원, 파생 상태 제거, `MODE` 적용
`task dev:snapshots`	—	저장된 checkpoint 목록 표시

백엔드와 프런트엔드

명령	짧은 alias	용도
`task backend:shell`	`task shell`	`app`에서 Bash 열기
`task backend:artisan`	`task artisan`	Artisan 명령 실행
`task backend:composer`	`task composer`	로컬 package manifest로 Composer 실행
`task backend:test`	`task test`	Core와 발견된 package PHP test 실행
`task backend:format`	`task format`	Laravel Pint formatting 적용
`task backend:format-check`	—	파일을 쓰지 않고 Pint 검사
`task backend:php-compat`	—	PHP 호환성 규칙 검사
`task backend:cache-clear`	`task cache-clear`	Laravel application cache 제거
`task backend:runtime-warm`	`task runtime:warm`	App map 생성과 contribution·route cache 준비
`task backend:runtime-live`	`task runtime:live`	contribution discovery는 유지하고 route cache 제거
`task frontend:pnpm`	`task pnpm`	`app`에서 pnpm 실행
`task frontend:dev`	—	Vite 재시작 후 로그 추적
`task frontend:build`	—	SDK·client·SSR asset 빌드
`task frontend:test`	—	Vitest 실행
`task frontend:typecheck`	—	파일을 만들지 않고 frontend type 검사

데이터베이스

명령	용도
`task db:migrate` (`task migrate`)	central migration 실행
`task db:seed` (`task seed`)	현재 환경의 기준 데이터 seeding
`task db:tenant:migrate TENANT=<id>`	tenant 하나 migration
`task db:tenant:seed TENANT=<id>`	tenant 하나에 production-safe 기준 seeder 실행
`task db:tenants:migrate`	등록된 모든 tenant migration
`task db:tenants:seed`	확인 후 모든 tenant seeding
`task nexia-db:audit [TENANT=<id>]`	전체 또는 tenant 하나의 읽기 전용 schema 감사
`task db:test:reset`	확인 후 test database 재생성

품질과 테스트

명령	용도
`task qa:lint-changed` (`task lint-changed`)	변경 파일에 해당하는 governance 검사
`task qa:lint-all` (`task lint-all`)	저장소 전체 governance 검사
`task qa:translations`	application 번역 catalog 검증
`task lint`	쓰지 않는 전체 저장소 검사
`task check`	Core와 Composer로 발견한 App의 전체 gate 실행

개발 중에는 위험을 직접 반증하는 가장 작은 test를 실행합니다. task check는 모든 수정의 기본값이 아니라 로컬 promotion gate입니다.

패키지와 Agent, 부가 서비스

영역	명령
App Package	`task apps:list`, `task apps:add`, `task apps:remove`, `task apps:status`, `task apps:checkout`, `task apps:update`, `task apps:update-all`, `task apps:lock`, `task apps:lock:verify`, `task apps:coupling`
Agent Edge·Gateway	`task agent:restart`, `task agent:shell`, `task agent:logs`, `task agent:sync`, `task agent:test`
성능	`task perf:scenarios`, `task nexia-perf:provision-fixture`, `task perf:measure`, `task perf:scenario SCENARIO=<name>`
Langfuse	`task langfuse:up`, `task langfuse:down`, `task langfuse:logs`

task apps:list는 PACKAGES에 사용할 수 있는 key를 설치 전에 보여 줍니다.

최초 setup에서 PACKAGES=all은 SDK와 모든 App 소스, PACKAGES=none은 로컬 소스를 선택하지 않는다는 뜻입니다. setup 뒤에는 task apps:add PACKAGES=... 또는 task apps:remove PACKAGES=...로 key를 바꾸며, 교체 목록은 거부됩니다. apps:update와 apps:update-all은 작업 브랜치를 develop으로 바꾸지 않고 중단하므로, 작업을 마친 뒤 의도적으로 브랜치를 전환하고 동기화합니다.

Agent Edge·Gateway 시작은 task dev:up:agent가 담당합니다. Reverb가 설정돼 있으면 같은 수렴 과정이 Agent task와 Shell 무효화 event에 필요한 WebSocket 서버도 유지합니다. agent:restart와 agent:logs는 두 Agent 서비스를 함께 조작하고 shell·sync·test 명령은 Gateway의 Python workspace를 대상으로 합니다.

옵션과 안전

명령	영향
`task db:reset`	local central·tenant·test data 삭제 후 reseed; local `SCOUT_DRIVER=typesense`이면 Nexia Typesense 인덱스도 재구축
`task dev:reset [MODE=...]`	선택 profile을 rebuild하고 local application·test data 삭제
`task dev:destroy`	Compose가 관리하는 volume 전체 삭제
`task apps:status -- --offline`	remote fetch 없이 로컬 소스 패키지의 소스 폴더 상태 확인
`task apps:lock:verify -- [key...]`	커밋된 lock reference가 해당 원격 branch 또는 tag와 맞는지 읽기 전용 확인

reset·destroy 세 명령은 삭제 전에 확인을 받습니다. 프로필 전환과 task down, task logs는 volume이나 application data를 지우지 않습니다.

결과 또는 반환

Task는 내부 명령의 종료 상태를 반환합니다. task status는 Compose service 표를 출력하고, task logs는 중단할 때까지 연결된 채로 있으며, task help는 공개 recipe와 alias만 표시합니다. 프로필 명령은 Compose 시작·정지 결과와 해당 프로필에 필요한 Agent 화면 검색 또는 Resource Dataset Import Ollama 설정 검사를 출력합니다.

오류

증상	원인	해결
`task: Task "dev:up" does not exist`	예전의 모호한 시작 명령이 제거됨	core는 `task up`, 그 외에는 `task dev:up:<profile>` 사용
`task: Missing required variable: TENANT`	tenant 하나를 다루는 recipe에 대상이 없음	`TENANT=<id>` 추가
`service "app" is not running`	런타임보다 container wrapper를 먼저 실행	`task up`을 실행한 뒤 재시도
CLI에는 새 백엔드 코드가 보이지만 브라우저에는 이전 동작이 남음	실행 중인 Octane worker 또는 열린 Shell에 이전 상태가 남음	`task app:reload` 실행 후 브라우저 새로고침
모든 서비스 로그가 함께 나옴	`--` 뒤 서비스명을 생략함	`task logs -- app` 또는 다른 Compose 서비스명 사용

Task 명령어

Task 명령어

시그니처

최소 예시

인자

전달 인자

Task 변수

실행 프로필

환경과 상태 확인

백엔드와 프런트엔드

데이터베이스

품질과 테스트

패키지와 Agent, 부가 서비스

옵션과 안전

결과 또는 반환

오류

관련 문서