Meshy CLI

터미널에서 Meshy 모델을 생성하고, 추적하고, 다운로드하세요. 명령어 하나로 prompt나 이미지를 텍스처가 적용된 모델로 변환할 수 있으며, 대부분의 API 엔드포인트는 각각의 명령어로 제공됩니다.

Meshy CLI(meshy)는 이 문서의 나머지 부분과 동일한 REST API를 동일한 가격으로 호출합니다. 브라우저에서 한 번 로그인하면 되므로 API 키가 필요하지 않습니다. 터미널에서는 사람이 읽기 쉬운 형태로 출력하고, 스크립트, 파이프, CI, 또는 AI 에이전트에서는 JSON을 출력합니다.

설치

CLI를 사용하려면 Node.js 22.12 이상이 필요합니다. macOS, Linux, Windows에서 실행됩니다.

npm install -g meshy-cli
meshy doctor    # checks your environment, without calling the API

이 패키지는 meshy와 meshy-cli 두 가지 명령어를 설치합니다. 동일한 빌드가 @meshy-ai/cli로도 배포됩니다. 두 패키지 모두 meshy 명령어를 제공하므로 둘 중 하나만 설치해야 합니다. 그렇지 않으면 npm이 두 번째 설치를 EEXIST 오류로 거부합니다.

CLI는 오픈 소스입니다. 소스 코드는 GitHub의 meshy-cli repository에 있습니다.

로그인

meshy auth login     # opens your browser
meshy auth status    # shows which account and credential are in use

meshy auth login은 브라우저에서 Meshy 로그인 페이지를 열고 자격 증명을 컴퓨터에 저장합니다. 브라우저가 열리지 않으면 CLI가 출력하는 URL을 복사하세요.

원격 머신, SSH 및 컨테이너

브라우저가 없는 머신에서는 meshy auth login이 링크와 짧은 코드를 대신 출력합니다. 노트북이나 휴대폰 등 아무 기기에서든 해당 링크를 열고 로그인한 다음 코드를 입력하세요. CLI가 알아서 로그인을 마무리합니다.

CLI는 SSH, 컨테이너, CI, 디스플레이가 없는 Linux, 또는 AI 에이전트가 명령을 실행할 때처럼 대화형 터미널이 없는 환경을 감지하면 이 방식을 선택합니다. MESHY_CLI_NO_BROWSER가 설정되어 있을 때도 이 방식을 선택합니다. 직접 선택하려면 meshy auth login --device를 실행하세요.

meshy auth login --device

API 키와 CI

CI 및 기타 자동화된(무인) 작업에는 브라우저 로그인 대신 API 키를 사용하세요. MESHY_API_KEY 환경 변수에 설정하면 됩니다. 이는 저장된 로그인 정보보다 우선순위를 가집니다.

export MESHY_API_KEY="msy_YOUR_API_KEY"
meshy balance

meshy auth login --with-key msy_YOUR_API_KEY 명령으로 키를 저장할 수도 있습니다.

CLI는 다음 순서로 처음 발견되는 인증 정보를 사용합니다: --api-key, MESHY_API_KEY, --api-key-file, 그다음 저장된 로그인 정보. CLI가 예상과 다른 계정을 사용하는 경우, meshy auth status를 실행하여 어떤 인증 정보가 적용되고 있는지 확인하세요.

중국 사이트

하나의 Meshy 계정으로 두 사이트를 모두 이용할 수 있습니다. meshy.cn을 사용하려면 meshy auth login --region cn으로 로그인하세요. CLI는 로그인 시 지역 정보를 저장하므로, 이후 명령어는 플래그 없이 api.meshy.cn을 호출합니다. 다시 전환하려면 --region global로 로그인하세요.

첫 번째 모델 만들기

meshy make는 전체 흐름을 한 번의 명령으로 실행합니다. 텍스트 prompt는 텍스트로 3D 미리보기를 실행한 뒤 refine을 진행합니다. 이미지는 텍스처가 적용된 이미지로 3D 작업 하나를 실행합니다.

먼저, 크레딧을 전혀 사용하지 않고 실행 결과와 소요될 크레딧 수를 확인해 보세요:

meshy make "a lovely baby husky" --dry-run

그런 다음 실행하고, -o로 모델을 폴더에 저장하세요:

meshy make "a lovely baby husky" -o out/husky/

✓ [1/2] text-to-3d preview (geometry)                 01a0c94c-…   1m 27s
✓ [2/2] text-to-3d refine (textures)                  01a0c94d-…   5m 36s

✓ SUCCEEDED  text-to-3d-refine
Task     01a0c94d-eaba-710e-b5b7-da5b2f620c95
Created  2026-11-13 10:02
Took     7m 03s
Credits  ~30 (estimate for the whole chain)
Assets   glb, fbx · textures: base_color, metallic, normal, roughness · thumbnail
Saved    out/husky/model.glb
         out/husky/thumbnail.png
         out/husky/meta.json

이제 이 폴더에는 모델과 썸네일, 그리고 meta.json 파일이 들어 있습니다. 사진으로 시작하려면 그 경로나 URL을 전달하세요: meshy make ./cat.png -o out/cat/.

명령어

대부분의 API 엔드포인트는 그 자체로 명령어이며, 각 작업 명령어는 동일한 동사인 create, get, list, wait, stream, delete를 사용합니다. 자체 명령어가 없는 엔드포인트의 경우 meshy api를 사용하세요.

다음 명령어는 일반적인 작업을 다룹니다:

meshy text-to-3d create --mode preview --prompt "a red sports car"
meshy image-to-3d create --image-url ./cat.png --async    # returns the task ID at once
meshy image-to-3d wait <task-id> -o out/cat/
meshy text-to-3d list
meshy download --resource text-to-3d --task-id <task-id> --list
meshy balance

명령어의 플래그를 확인하려면 meshy <resource> --help를 실행하세요. 각 엔드포인트의 파라미터와 크레딧 비용은 텍스트로 3D와 같이 이 문서의 해당 페이지를 참고하세요.

CLI에는 meshy inspect faces, meshy mesh prepare-print, meshy slicer와 같은 3D 프린팅을 위한 로컬 헬퍼도 있습니다. 이들은 사용자의 컴퓨터에서 실행되며 API를 호출하지 않습니다. 모든 명령어는 meshy-cli 사용하기를 참고하세요.

스크립트, 에이전트, CI

JSON 출력

출력이 파이프, 파일, 스크립트 또는 AI 에이전트로 전달될 때 CLI는 JSON을 출력합니다. 터미널에서는 읽기 쉬운 형태로 출력합니다. 항상 JSON을 받으려면 --format json(또는 --json)을 전달하세요.

모든 명령어는 stdout에 동일한 여섯 개의 키를 가진 JSON 문서를 정확히 하나만 출력합니다. progress와 메시지는 stderr로 전달됩니다.

meshy text-to-3d create --mode preview --prompt "a cactus" --async --format json \
  | jq -r .result.submission.task_id

{
  "schema_version": "meshy.cli/v1",
  "command": "image-to-3d.get",
  "ok": true,
  "result": { "task": { "task_id": "…", "status": "IN_PROGRESS", "progress": 52 } },
  "error": null,
  "warnings": []
}

ok는 CLI 명령어가 제대로 작동했는지를 나타냅니다. 작업 자체의 상태는 result.task.status에 있습니다. 예를 들어, 실패한 작업에 대한 get은 ok: true를 반환하는데, 이는 요청 자체는 제대로 작동했기 때문입니다.

CLI는 각 생성 요청을 한 번만 전송하며 스스로 재시도하지 않으므로, 네트워크 오류로 인해 작업이 중복 생성되고 비용이 이중으로 청구되는 일은 발생하지 않습니다.

종료 코드

종료 코드는 스크립트에 무슨 일이 일어났는지 알려줍니다:

11부터 14까지의 코드와 전체 출력 형식에 대해서는 스크립트와 에이전트를 참고하세요.

GitHub Actions

API 키를 MESHY_API_KEY라는 이름의 저장소 시크릿(repository secret)으로 저장한 다음, 작업(job)에서 CLI를 실행하세요:

name: Generate a model
on: workflow_dispatch

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g meshy-cli
      - run: meshy make "a low-poly treasure chest" -o assets/chest/ --format json
        env:
          MESHY_API_KEY: ${{ secrets.MESHY_API_KEY }}
      - uses: actions/upload-artifact@v4
        with:
          name: chest
          path: assets/chest/

CLI가 0이 아닌 코드로 종료되면 해당 단계는 실패합니다.

AI 에이전트

셸 명령을 실행할 수 있는 에이전트라면 Claude Code, Cursor, Codex를 포함하여 모두 CLI를 사용할 수 있습니다. 에이전트는 자동으로 JSON을 받습니다.

에이전트에게 Meshy 워크플로를 알려주려면 오픈소스 meshy-3d-agent 스킬 팩을 설치하세요. 이는 CLI에서 실행됩니다.

npx skills add meshy-dev/meshy-3d-agent

참조

전역 플래그

이 플래그들은 모든 명령에서 작동합니다:

환경 변수

CLI는 다음 변수를 읽습니다:

자격 증명 저장 위치

CLI는 ~/.config/meshy/credentials.v2.json에 자격 증명을 저장하며, 이 파일은 본인만 읽을 수 있습니다. 여기에 담긴 자격 증명은 OS 키링에 보관된 키로 암호화됩니다: macOS에서는 Keychain, Windows에서는 DPAPI, Linux에서는 Secret Service를 사용합니다. 컨테이너나 SSH 환경처럼 키링을 사용할 수 없는 경우에는 자격 증명 파일 옆에 있는 파일이 키 역할을 합니다.

업데이트 및 제거

CLI는 하루에 최대 한 번 npm에서 새 버전이 있는지 확인하고 이를 stderr로 알려줍니다. stdout은 절대 변경하지 않습니다. 각 API 요청에는 CLI 버전, 사용 중인 OS, 그리고 CLI를 실행 중인 AI 에이전트(감지된 경우)를 담은 User-Agent 헤더가 포함됩니다. 에이전트 정보를 제외하려면 MESHY_CLI_AGENT=none으로 설정하세요.

npm install -g meshy-cli@latest

meshy auth logout --all       # deletes the stored credentials
npm uninstall -g meshy-cli

각 버전에서 변경된 내용을 확인하려면 GitHub의 releases를 참고하세요.

Troubleshooting

먼저 meshy doctor를 실행하세요. 이 명령은 API를 호출하지 않고 설정을 점검합니다. 자주 발생하는 문제는 다음과 같습니다:

버그를 리포트하려면 meshy-cli 리포지토리에 이슈를 등록하세요.

다음 단계

• API 레퍼런스에서 각 엔드포인트의 매개변수와 비용을 확인하세요.
• AI 연동에서 CLI와 MCP server를 비교해 보세요.
• 모든 명령어와 플래그는 Using meshy-cli를 참고하세요.