CLI 레퍼런스

Wippy CLI를 사용해 프로젝트를 초기화하고, 런타임을 실행하고, 의존성을 관리하고, 레지스트리 엔트리를 검사하고, 모듈을 게시할 수 있습니다.

이 문서는 명령어 레퍼런스입니다. 소스, 잠금 파일, 레지스트리 엔트리 또는 게시 메타데이터를 다루는 예시는 기존 프로젝트나 모듈이 있다고 가정하며, 하나의 완결된 프로젝트를 순서대로 구성하는 예시가 아닙니다.

전역 플래그

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

메모리 제한 우선순위: --memory-limit 플래그 > GOMEMLIMIT 환경 변수 > 1GB 기본값.

전역 --config 옵션은 설정 파일을 합성하기 위해 여러 번 전달할 수 있습니다. 파일은 왼쪽에서 오른쪽으로 병합됩니다. 뒤의 파일이 일치하는 값을 재정의하고 나머지는 모두 유지합니다. 명시적으로 지정된 파일은 모두 존재해야 하며, --config가 없으면 기본 .wippy.yaml은 선택 사항입니다. 첫 번째 파일이 상대 경로 해석에 사용되는 디렉토리를 고정합니다. 설정은 파일 합성, --profile 선택, --set 오버라이드 순서로 적용됩니다. 설정을 참조하세요.

wippy publish는 전역 옵션 대신 명령어 로컬 --config <dir> 옵션을 사용합니다. 이 명령에서 값은 반복 가능한 런타임 설정 파일이 아니라 wippy.yaml이 있는 디렉토리입니다.

wippy init

wippy.lock을 생성하거나, 이미 있으면 소스 및 모듈 디렉토리 설정을 업데이트합니다. 이 명령은 애플리케이션 소스 파일이나 레지스트리 엔트리를 스캐폴딩하지 않습니다.

wippy init
wippy init --src-dir ./src --modules-dir .wippy

wippy run

런타임을 시작하거나 명령어를 실행합니다.

wippy run                                   # Start runtime
wippy run list                              # List available commands
wippy run migrate                           # Run a named custom command
wippy run snapshot.wapp                     # Run from pack file
wippy run acme/http                         # Run module from hub
wippy run acme/http@1.2.3                   # Run specific version
wippy run --exec app:worker                 # Start runtime and execute a single process

허브 모듈 실행(wippy run org/module)은 모듈을 한 번 해결하여 wippy.lock에 기록하고 검증된 팩을 로컬에 벤더링합니다. 같은 참조의 후속 실행은 잠금에서 시작합니다 — 네트워크가 필요 없습니다. 더 이상 잠금과 일치하지 않는 버전 셀렉터는 wippy update를 실행하라는 힌트와 함께 거부됩니다.

로컬 애플리케이션의 경우 wippy run은 런타임 서비스가 시작되기 전에 오래된 lock을 복구합니다. 소스의 의존성 선언을 로드하고, lock이 이미 그것을 충족하면 로컬 및 설치된 증거만으로(검증된 오프라인 접근, 네트워크 없음) 그래프를 재해결합니다. 이 오프라인 해결이 lock과 일치하면 부팅은 그대로 진행됩니다. 성공했지만 다르면 그 결과가 후보 그래프가 됩니다. 허브에 해결을 요청하는 것은 오프라인 해결이 실패하거나 lock이 더 이상 소스의 선언을 충족하지 않을 때뿐입니다. 후보 그래프에 없는 팩을 다운로드하고 검증한 뒤에야 wippy.lock을 다시 씁니다. 배포 루트를 선택한 lock은 권위를 가지며 절대 재해결되지 않습니다.

--exec는 시작된 프로세스가 결과를 낼 때까지 블록한 다음, 그 프로세스의 종료 코드를 CLI 종료 코드로 전파합니다. --exec 중의 Ctrl-C는 실행 중인 프로세스를 취소하며 런타임은 여전히 graceful하게 종료됩니다. 두 번째 시그널은 강제 종료합니다.

--set은 명령줄에서 임의의 런타임 설정 값을 작성하며, .wippy.yaml에 리프 단위로 병합됩니다:

wippy run --set cluster.enabled=true \
          --set cluster.membership.join_addrs=node-2:7946,node-3:7946 \
          --set cluster.raft.bootstrap_expect=3

값은 형태에 따라 변환됩니다. true와 false는 불리언, 정수와 부동소수점은 숫자, 그 외에는 문자열로 유지됩니다. 기간을 기대하는 필드는 5s 같은 값을 파싱합니다.

wippy test

테스트 엔트리포인트를 실행합니다: test 사용 사례를 선언한 프로세스 엔트리입니다. 런타임이 부팅되어 해당 엔트리를 실행하고 종료합니다. wippy run은 테스트 엔트리포인트를 자동 실행하지 않습니다; 테스트는 항상 wippy test를 통해 실행합니다.

wippy test                     # Run tests from the local project
wippy test snapshot.wapp       # Run tests from a pack file
wippy test acme/module@1.2.3   # Run tests from a hub module

wippy lint

Lua 코드의 타입 오류 및 경고를 검사합니다.

wippy lint
wippy lint --level warning
wippy lint --json
wippy lint --rules

소스를 포함하는 function.lua, library.lua, process.lua, workflow.lua 엔트리를 검증합니다. 미리 컴파일된 .bc 엔트리에는 파싱 가능한 소스가 없으므로 건너뜁니다.

wippy add

모듈 의존성을 추가합니다.

wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest

wippy install

Lock 파일에서 의존성을 설치합니다.

wippy install                            # Install all
wippy install acme/http                  # Install specific module
wippy install --refresh acme/http        # Re-fetch a specific module

wippy update

의존성을 업데이트하고 lock 파일을 재생성합니다.

wippy update                      # Update all
wippy update acme/http            # Update specific module
wippy update acme/http demo/sql   # Update multiple

wippy artifacts

빌드 타임 파일시스템 아티팩트를 다룹니다.

wippy artifacts materialize

기존 팩에서 아티팩트 파일시스템 하나를 검증하고 구체화합니다.

wippy artifacts materialize snapshot.wapp app:package_fs
wippy artifacts materialize snapshot.wapp app:package_fs --root build

리소스는 전체 namespace:name으로 지정하며, meta.artifact.format을 선언해야 하고 그 포맷이 CLI에 등록되어 있어야 합니다. 이 명령어는 모듈 의존성을 해결하지 않고, wippy.lock을 변경하지 않으며, 패키지 매니저를 호출하지 않고, 런타임 구성에 관여하지 않습니다. 빌드 타임 아티팩트를 참조하세요.

wippy pack

스냅샷 팩(.wapp 파일)을 생성합니다.

wippy pack snapshot.wapp
wippy pack release.wapp --description "Release 1.0"
wippy pack app.wapp --embed app:assets --bytecode "**"

--embed나 --embed-all이 없으면 임베드 패턴은 모듈 매니페스트 wippy.yaml의 embed: 섹션으로 폴백합니다. 애플리케이션을 팩할 때는 의존성 팩의 임베드된 리소스도 함께 포함되며, 결과 팩은 메인 모듈의 명령어만 노출합니다.

출력 파일은 원자적으로 기록됩니다: 팩은 대상 디렉토리의 임시 파일로 빌드되어 sync되고 검증된 다음에야 대상 위로 rename되며, 기존 파일이 있으면 그 권한을 물려받습니다. 팩이 실패하면 이전 파일은 그대로 남습니다. 팩의 입력 중 하나이기도 한 출력 — 동일한 경로이거나, 같은 파일로 해석되는 하드 링크 또는 심볼릭 링크 — 을 지정하면 읽는 도중 입력을 잘라내는 대신 거부됩니다.

--meta는 예약된 메타데이터를 작성할 수 없습니다. registry 키와 wippy. 또는 system. 접두사 아래의 모든 것은 팩 포맷이 소유하며 거부됩니다.

meta.artifact.format을 선언한 리소스는 팩 과정에서 검증되므로, 잘못된 아티팩트는 소비자 쪽이 아니라 여기서 실패합니다. 빌드 타임 아티팩트를 참조하세요.

wippy publish

모듈을 허브에 퍼블리시합니다.

wippy publish
wippy publish --version 1.0.0
wippy publish --dry-run

현재 디렉토리의 wippy.yaml을 읽습니다.

모듈 타입은 일반적으로 wippy.yaml에 type:으로 선언합니다 (게시 참조). --module-type은 단일 게시에 한해 이를 재정의합니다. 둘 다 설정되지 않으면 새로 생성되는 모듈은 사용 중단 경고와 함께 application을 기본값으로 사용합니다.

wippy search

허브에서 모듈을 검색합니다.

검색은 사용 가능한 경우 선택한 레지스트리에 저장된 인증 토큰을 사용합니다. wippy auth login으로 인증하면 레지스트리 ID로 검색할 수 있으며, --registry로 사용할 레지스트리 자격 증명을 선택합니다.

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json

wippy auth

레지스트리 인증을 관리합니다.

wippy auth login

wippy auth login
wippy auth login --token YOUR_TOKEN

wippy auth logout

wippy auth logout

wippy auth status

wippy auth status
wippy auth status --json

wippy readme

허브에서 모듈의 README를 가져옵니다.

wippy readme wippy/terminal
wippy readme wippy/terminal@1.2.3
wippy readme --json wippy/terminal@latest

wippy registry

레지스트리 엔트리를 조회하고 검사합니다. 두 하위 명령어 모두 --profile과 --set을 받아, 엔트리가 로드되는 병합된 런타임 설정을 조정할 수 있습니다.

wippy registry list

wippy registry list
wippy registry list --kind "function.lua.*"
wippy registry list --ns "app.*" --json
wippy registry list --meta "type=api" --meta "enabled=true"

--meta의 메타데이터 연산자:

wippy registry show

wippy registry show app:http:handler
wippy registry show app:config --yaml

wippy version

버전 정보를 출력합니다.

wippy version
wippy version --short

커스텀 명령어

모든 process.lua 또는 process.wasm 엔트리는 command 메타데이터를 추가하여 이름이 있는 명령어로 등록할 수 있습니다:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: app:migrations
          policies:
            - app.security:migrations
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

다음과 같이 실행합니다:

wippy run migrate

사용 가능한 모든 명령어를 나열합니다:

wippy run list

wippy run list는 --profile과 --set을 받으므로, 목록은 wippy run이 사용하는 것과 동일한 병합된 런타임 설정을 반영합니다.

명령어 메타데이터 필드

모든 프로세스 엔트리 종류(process.lua, process.wasm)를 사용할 수 있습니다. 명령어 이름의 고유성은 검사하지 않습니다. 로드된 여러 엔트리가 같은 이름을 선언하면 레지스트리 순서상 처음 일치하는 것이 실행됩니다. 명령어 이름 뒤의 인수는 문자열 페이로드로 프로세스에 전달됩니다.

명령어 보안

명령어 엔트리는 CLI 실행이 어떤 액터와 정책 스코프로 동작할지 선언합니다:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: system.migrations
            meta:
              role: operator
          policies:
            - app.security:migrations_policy
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main

이 블록이 meta.command 안에 있는 이유는 CLI 실행 경로에만 적용되기 때문입니다 — 운영자가 자신의 배포에서 명령어를 시작했다는 것이 신뢰의 앵커입니다. 동일한 프로세스 엔트리의 일반적인 스폰에는 영향을 주지 않으며, 그런 경우는 엔트리 자체의 security: 블록을 따릅니다.

선언은 fail-closed이며 프로세스가 시작되기 전에 검증됩니다:

• security 안의 알 수 없는 필드는 거부됩니다.
• 비어 있는 security 블록(액터도, 정책도, 그룹도 없음)은 거부됩니다.
• name 없는 security는 거부됩니다 — 명령어는 시작될 수 있으려면 이름을 가져야 합니다.
• 해석되지 않는 정책이나 그룹은 실행을 거부시킵니다. 해석은 원자적이므로 부분적인 스코프가 설치되는 일은 없습니다.

블록이 actor를 생략하면 호출자의 액터가 상속됩니다. policies와 groups를 모두 생략하면 호출자의 스코프가 상속됩니다.

예제

개발 워크플로우

# Initialize dependency lock metadata
wippy init
wippy add wippy/test
wippy add wippy/llm
wippy install

# Check for errors
wippy lint

# Run with debug output
wippy run -c -v

# Override config for local dev
wippy run -o app:db:host=localhost -o app:db:port=5432

프로덕션 배포

# Create release pack with bytecode
wippy pack release.wapp --bytecode "**" --exclude-ns "test.**"

# Run from pack with memory limit
wippy run release.wapp -m 2G

디버깅

# Execute single process
wippy run --exec app:worker

# With profiler enabled
wippy run -p -v
# Then: go tool pprof http://localhost:6060/debug/pprof/heap

의존성 관리

# Add new dependency
wippy add acme/http@latest

# Force re-download
wippy install --force

# Update specific module
wippy update acme/http

퍼블리싱

# Login to hub
wippy auth login

# Validate module
wippy publish --dry-run

# Publish
wippy publish --version 1.0.0 --release-notes "Initial release"

환경 변수

.wippy.yaml의 값은 ${env:NAME}으로 OS 환경 변수를 참조할 수 있으며, 파일 로드 시 해석됩니다; 누락된 변수는 설정 로드를 실패시킵니다. 단독 ${name} 참조는 대신 설정의 vars: 섹션에서 해석됩니다.

설정 파일

영구적인 설정을 위해 .wippy.yaml을 생성합니다:

logger:
  encoding: console

logmanager:
  stream_to_events: true

profiler:
  enabled: true
  address: localhost:6060

override:
  app:gateway:addr: ":9090"
  app:db:host: "localhost"

참고

• 설정 - 설정 파일 레퍼런스
• 관측성 - 모니터링 및 로깅