{{tag>[cli wasm webassembly wasi wasmtime]}}

====== wasmtime ======
WebAssembly, WASI, Component Model 코드를 로컬에서 실행, 사전 컴파일, 검사할 수 있는 Wasmtime CLI.

===== Summary =====
  * ''wasmtime'' 는 Bytecode Alliance의 WebAssembly runtime CLI이다.
  * subcommand를 생략하면 기본적으로 ''run'' 으로 처리되어 입력한 ''.wasm'' 또는 ''.wat'' 파일을 실행한다.
  * Wasmtime 자체 옵션은 반드시 WebAssembly 파일 ''앞'' 에 배치해야 하며, 파일 뒤 인수는 게스트 프로그램의 CLI 인수로 전달된다.
  * CLI 프로그램 실행, AOT compile, shell completion 생성, ''.cwasm'' 분석과 같은 작업을 한 도구에서 처리할 수 있다.

===== Usage =====
<code bash>
wasmtime [OPTIONS] <WASM-OR-SUBCOMMAND> [ARGS...]
wasmtime run [OPTIONS] module.wasm [ARGS...]
wasmtime serve [OPTIONS] component.wasm
wasmtime compile [OPTIONS] module.wasm
</code>

  * ''<color #c3c3c3>**wasmtime**</color> <color #22b14c>[OPTIONS]</color> <color #7092be>FILE</color> <color #7092be>[ARGS...]</color>''
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>run</color> <color #22b14c>[OPTIONS]</color> <color #7092be>MODULE.wasm</color> <color #7092be>[ARGS...]</color>''
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>serve</color> <color #22b14c>[OPTIONS]</color> <color #7092be>COMPONENT.wasm</color>''
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>compile</color> <color #22b14c>[OPTIONS]</color> <color #7092be>MODULE.wasm</color>''
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>objdump</color> <color #22b14c>[OPTIONS]</color> <color #7092be>MODULE.cwasm</color>''

===== Options =====
==== Common Behavior ====
  * subcommand 없이 ''wasmtime module.wasm'' 처럼 실행하면 ''wasmtime run module.wasm'' 과 동일하게 동작한다.
  * ''.wasm'' 바이너리뿐 아니라 ''.wat'' 텍스트 형식도 직접 실행할 수 있다.
  * Wasmtime 옵션은 모두 대상 파일보다 앞에 써야 한다. 파일 뒤 인수는 게스트 프로그램 인수로 전달된다.

==== Important Subcommands ====
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>help</color>'': 전체 도움말 또는 특정 subcommand 도움말 출력
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>run</color>'': WebAssembly module 또는 component 실행
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>serve</color>'': ''wasi:http/proxy'' world 기준으로 HTTP component 실행
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>wast</color>'': WebAssembly spec test 형식인 ''.wast'' 실행
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>config</color>'': 로컬 설정과 cache 설정 파일 생성 및 편집
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>completion</color>'': shell completion 스크립트 생성
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>compile</color>'': module을 Ahead-Of-Time compile 해서 ''.cwasm'' 생성
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>settings</color>'': host target 기준 Cranelift 설정 확인
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>explore</color>'': wasm을 compile하고 HTML 탐색 결과 생성
  * ''<color #c3c3c3>**wasmtime**</color> <color #ff7f27>objdump</color>'': ''.cwasm'' 내부 native instruction을 터미널에서 확인

==== Common Run-Specific Options ====
  * ''<color #22b14c>**--invoke**</color> <color #7092be>EXPORT</color>'': 기본 entrypoint 대신 특정 export 실행
  * ''<color #22b14c>**--dir**</color> <color #7092be>PATH</color>'': guest에 디렉터리 접근 권한 부여. 반드시 wasm 파일 앞에 둔다
  * ''<color #22b14c>**--env**</color> <color #7092be>KEY=VALUE</color>'': guest에 환경 변수 전달

===== Examples =====
==== Basic Execution ====
<code bash>
# 기본 run 동작
wasmtime hello.wasm

# 텍스트 형식(.wat)도 직접 실행
wasmtime hello.wat

# guest 프로그램 인수 전달
wasmtime app.wasm --mode prod --port 8080
</code>

==== WASI Options Placement ====
<note important>
Wasmtime 자체 옵션은 wasm 파일 앞에 둬야 한다. ''wasmtime foo.wasm --dir .'' 는 ''--dir .'' 을 Wasmtime이 아니라 guest 프로그램 인수로 넘긴다.
</note>

<code bash>
# 현재 디렉터리를 guest에 mount
wasmtime --dir . app.wasm

# 환경 변수 전달
wasmtime --env APP_ENV=dev app.wasm
</code>

==== Invoke Specific Export ====
<code bash>
# core wasm module의 특정 export 실행
wasmtime run --invoke initialize init.wasm

# 정수 인수를 받는 export 실행
wasmtime run --invoke add add.wasm 1 2

# component export 실행 시 WAVE 문법 사용
wasmtime run --invoke 'initialize("hello")' component.wasm
</code>

<note warning>
공식 문서는 ''--invoke'' 를 통한 일부 CLI 인수 구문이 아직 unstable 하며 향후 바뀔 수 있다고 안내한다.
</note>

==== HTTP Component ====
<code bash>
# wasi:http/proxy world 기반 component 실행
wasmtime serve proxy.wasm

# listen address 지정
wasmtime serve --addr=0.0.0.0:8081 proxy.wasm
</code>

==== AOT Compile and Inspect ====
<code bash>
# AOT compile
wasmtime compile app.wasm

# 생성된 .cwasm 실행
wasmtime app.cwasm

# shell completion 생성
wasmtime completion zsh

# compiled wasm의 native code 확인
wasmtime objdump app.cwasm
</code>

===== Config =====
  * ''wasmtime config new'' 으로 로컬 설정 파일을 생성할 수 있다.
  * 주된 목적 중 하나는 code cache 설정이며, 반복 실행 환경에서 compile 비용을 줄일 때 유용하다.
  * ''wasmtime settings'' 로 host target에 대해 Cranelift가 추론한 설정을 확인할 수 있다.

===== Troubleshooting =====
  * 옵션이 적용되지 않는다면 옵션 위치를 먼저 확인한다. Wasmtime 옵션은 항상 wasm 파일 앞이어야 한다.
  * module이 WASI 이외의 import를 요구하면 기본 CLI 실행에서는 instantiate에 실패할 수 있다.
  * ''serve'' 사용 시 target component가 ''wasi:http/proxy'' world를 따르는지 확인한다.
  * ''.cwasm'' 이 다른 환경에서 실행되지 않으면 AOT compile 시점의 target 환경과 실행 호스트 호환성을 점검한다.

===== Compatibility =====
  * Wasmtime는 WebAssembly module, WASI, Component Model 실행을 지원한다.
  * 공식 CLI 문서 기준으로 ''serve'' subcommand는 Wasmtime 18.0.0 이후의 WASI HTTP API를 전제로 한다.
  * ''.cwasm'' 파일은 target 환경 호환성이 필요하므로, 모든 호스트에서 이식적으로 실행되는 것은 아니다.

===== Help =====
+++ wasmtime --help |
<code text>
로컬 환경에 wasmtime binary가 없어 실제 ''wasmtime --help'' 출력은 수집하지 못했다.

참고:
  * https://wasmtime.dev/
  * https://docs.wasmtime.dev/cli-options.html
</code>
+++

===== See Also =====
  * [[https://wasmtime.dev/|wasmtime.dev]]
  * [[https://docs.wasmtime.dev/|Wasmtime Guide]]
  * [[https://docs.wasmtime.dev/cli-options.html|CLI Options]]

===== History =====
  * codex:: 2026-07-14 Added Wasmtime CLI reference page with run, serve, compile, and AOT inspection workflow notes.