ludo: Ludo AI 명령어 라인
터미널이나 코딩 에이전트에서 Ludo AI를 사용하여 게임 에셋을 생성하세요:
스프라이트 및 스프라이트시트 애니메이션, 이미지, 3D 모델(리깅 및 애니메이션 포함), 비디오, 사운드 효과, 음악, 음성.
npm install -g @ludoai/cli
ludo login
...
CLI를 사용하는 이유
- 로컬 파일은 바로 작동합니다. 이미지, 오디오, 비디오 또는 모델 플래그의 경로만 전달하면 CLI가 자동으로 업로드합니다. base64나 호스팅 과정이 필요 없습니다.
- 결과물은 디스크에 저장됩니다. 생성 작업은 작업 완료를 기다린 후 모든 결과 파일을
./ludo-output (또는 --out <디렉토리>)에, 작업 및 운영 이름으로 명명하여 저장합니다 (예: sfx_pump.mp3; 절대 덮어쓰지 않습니다). 결과 URL은 7일 후에 만료되지만, 파일 자체는 그렇지 않습니다.
- 항상 최신 상태입니다. 명령어, 플래그, 열거형(enums), 기본값 및 가격은 실시간 API 사양을 기반으로 구축되므로, CLI를 업데이트하지 않아도 새로운 모델과 기능이 나타납니다.
- 에이전트에게 저렴합니다. 에이전트는 모든 도구 스키마를 미리 로드하는 대신,
--help를 통해 필요한 명령어만 학습합니다.
사용법
ludo <그룹> <명령어> [플래그]
ludo <그룹> <명령어> --help
| 그룹 | 명령어 |
|---|
image | create, generate-with-style, edit, remove-background |
| ... | |
이 표는 스냅샷입니다. ludo --help를 실행하면 항상 현재 목록이 표시됩니다. 모든 명령어는 API 작업 ID(예: ludo createImage ...)에도 응답하며, 이는 API 문서와 MCP 서버가 사용하는 이름과 동일합니다. | |
예시
ludo sprite animate --initial-image knight.png --motion-prompt "walk cycle" --out sprites
...
플래그
- API 필드는 kebab-case 플래그가 됩니다:
image_type은 --image-type입니다. 불리언(Boolean) 값은 스위치(--crop, --no-crop)를 사용합니다. 배열 필드는 반복됩니다 (--images a.png --images b.png).
--input body.json (또는 표준 입력(stdin)의 경우 --input -)은 전체 요청 본문(request body)을 제공하며, 플래그가 이를 덮어씁니다.
--no-wait은 작업을 제출하고 {id, status}를 출력합니다. 나중에 ludo jobs wait <id> 명령어로 해당 작업의 상태를 확인할 수 있습니다.
--json은 터미널에서도 JSON을 출력합니다. 표준 출력(stdout)이 터미널이 아닐 때 기본값으로 적용됩니다.
--timeout <초>는 대기(waiting)를 중지합니다 (작업은 계속 실행됩니다). --quiet는 표준 에러(stderr)의 진행 상황 메시지를 조용하게 만듭니다.
--open은 결과를 기본 애플리케이션(예: Aseprite)에서 엽니다. --play는 생성된 오디오를 재생하고, --copy는 저장된 파일 경로를 클립보드에 복사합니다.
- WebP 결과물도 PNG로 함께 저장됩니다 (엔진과 대부분의 도구는 PNG를 원하기 때문입니다).
--image-format png는 PNG만 유지하고, --image-format webp는 WebP만 유지합니다 (.ludo.json 파일의 `
이미 존재하는 .meta 파일은 고유 ID(guid)를 유지하므로, 해당 스프라이트를 사용하는 씬(scenes)과 프리팹(prefabs)이 여전히 이를 찾을 수 있습니다.
터미널에서 사용하기
터미널에서는 결과가 그 자리에 표시되며, 스프라이트 시트는 루핑 애니메이션으로 나타납니다. 실제 이미지를 그리는 터미널(iTerm2, Kitty, Ghostty, WezTerm)은 실제 그림을 보여줍니다. 다른 곳(tmux 내부 포함)에서는 노트와 함께 미리보기가 건너뛰어지며, 대신 --open 플래그를 사용하면 결과를 전체 크기로 엽니다.
ludo preview <파일명>은 저장된 모든 이미지를 다시 보여줍니다 (Ludo 스프라이트 시트는 그리드를 기억합니다. 다른 시트의 경우 --grid 8x4 --fps 12를 전달하세요). 기다리는 동안 스피너가 작업 상태를 표시하며, 각 결과는 다음 단계를 제안합니다.
이 모든 것은 스크립트나 AI 에이전트에게 도달하지 않습니다. 이는 표준 오류(stderr)에 그려지며, 두 출력 모두 터미널일 때만 가능합니다. --plain, NO_COLOR 또는 LUDO_PREVIEW=0을 사용하면 이를 끌 수 있습니다.
출력 형식
JSON 모드에서는 생성이 다음과 같이 출력됩니다:
{
"job_id": "…",
"status": "succeeded",
...
}
결과 내의 인라인 base64(예: 스프라이트 시트에서 생성된 사운드 효과)는 파일로 저장되고 해당 경로로 대체됩니다.
종료 코드
무료 도구
ludo toolbox는 사용자의 기기에서 실행되는 도구들을 담고 있습니다. 오프라인으로 작동하며 계정, API 키 또는 크레딧이 필요 없습니다. 이 도구들은 Ludo 전용이 아닌 모든 스프라이트 시트나 사운드에 적용됩니다.
ludo toolbox sprite slice knight-walk.png
...
파일은 ./ludo-output (또는 --out <디렉토리>)에 저장되며, 절대 덮어쓰지 않습니다.
프로젝트
ludo init은 폴더를 프로젝트로 설정합니다. 이 과정에서 .ludo.json 파일을 작성하고 코딩 에이전트(AGENTS.md의 섹션, .cursor가 존재할 때의 Cursor 규칙, 프로젝트가 Claude Code를 사용할 때의 Claude Code 스킬)에 대한 지침을 추가합니다. 해당 폴더 아래 어디서 실행되는 모든 명령어는 이를 사용합니다:
{
"out": "assets/ludo",
"engine": "godot",
...
}
out: 생성된 파일이 저장되는 위치입니다 (./ludo-output 대신).
engine: 모든 명령어에서 --engine으로 사용됩니다 (godot, texturepacker 또는 unity). ludo init은 Godot 프로젝트에서는 godot을, Unity 프로젝트에서는 unity(Assets/Ludo 아래에 저장됨)를, Phaser나 PixiJS에 의존하는 프로젝트에서는 texturepacker를 선택합니다.
max_credits: 선택적 지출 예산(spending budget)입니다 (아래 참조). ludo init에서 설정하지 않으면 제한이 없습니다.
style_image: style_image를 사용하는 작업에 사용됩니다 (image generate-with-style).
defaults: 명령어별 API 필드로, "그룹 명령어" 또는 API ID로 지정합니다.
경로는 .ludo.json을 기준으로 상대적이며 프로젝트 내에 있어야 합니다 (따라서 클론된 저장소는 ludo가 사용자의 다른 위치에 있는 파일들을 가리키게 할 수 없습니다); 플래그로 전달하는 경로는 제한되지 않습니다. 플래그가 항상 우선합니다.
비용 제어 (Cost control)
--dry-run: 명령어가 얼마의 비용이 들지 출력만 하고 실제 실행은 하지 않습니다.
--max-credits <n>: 더 많은 비용이 드는 명령어(모든 변형 포함)를 거부합니다.
- 지출 예산인
LUDO_MAX_CREDITS 또는 max_credits는 프로젝트 내에서 (또는 외부 기기에서) CLI가 지출하는 금액을 제한합니다. 이를 초과하면 모든 생성 작업은 종료 코드 11과 함께 거부됩니다. ludo spend로 집계액을 확인하고, ludo spend reset으로 새로 시작할 수 있습니다.
가격은 API가 공개한 가격 책정 기준에 따릅니다. 초당 비용이 부과되는 모델의 경우, 추정치는 해당 작업이 발생시킬 수 있는 최대 비용입니다. 소스 파일(예: 비디오 업스케일)에 따라 가격이 달라지는 명령어는 제한이 설정된 상태에서는 --force 플래그를 전달하지 않는 한 거부됩니다.
에셋 로그 (Asset log)
생성되는 모든 파일은 ludo-assets.json에 기록됩니다 (.ludo.json 옆 또는 출력 폴더 내): 명령어, 사용된 플래그, 작업 내용 및 비용이 포함됩니다. ludo assets로 목록을 확인하고, ludo assets redo <파일> --prompt "…in blue"를 사용하여 변경 사항을 적용하여 다시 만들 수 있습니다. ludo jobs wait에 의해 저장된 파일은 목록으로 표시되지만, 해당 요청이 알 수 없기 때문에 재생할 수는 없습니다. base64로 인라인 전달된 입력값은 로그 옆의 ludo-inputs/ 폴더에 한 번 보관되며 (git-ignored), 로그는 이 위치를 가리킵니다.
변형 및 배치 처리
--n 4는 하나의 요청에 대해 네 가지 변형을 만들고 이를 -v1부터 -v4까지 저장합니다(이때 --name 사용 시 <name>-v1부터 <name>-v4). 터미널에서 어떤 것을 유지할지 선택하면, 나머지는 <out>/.discarded/>로 이동합니다. API가 n(이미지)을 처리하는 경우 하나의 작업으로 모두 만듭니다. 다른 경우에는 작업들이 나란히 실행됩니다.
--save-normals는 각 노멀 맵(normal map)을 해당 이미지 또는 시트 옆에 <file>_n 형태로 저장합니다(crate-v1.png와 crate-v1_n.png). 이는 자체적인 변형은 아닙니다. JSON에서는 이 변형의 normal_maps 항목과 "normal_map": true가 포함된 files에서 목록화됩니다.
ludo batch jobs.json는 여러 다른 세대(generation)의 목록을 나란히 실행합니다(ludo batch --help에서 형식 확인 가능; 작업의 "name"이 파일 이름을 지정합니다). 전체 목록에 대한 비용이 먼저 확인됩니다. 하나의 항목이 실패하더라도 다른 항목의 진행을 멈추지 않습니다. 계정의 대기열(queue)이 가득 찬 경우(다른 세션 포함, 50개 생성물 대기 또는 실행 중), 배치 처리는 멈추는 대신 자리가 생길 때까지 기다리며, 하나의 폴링으로 모든 작업을 처리합니다. 각 작업에 "request_id"를 부여하면 파일을 다시 실행해도 동일한 작업들이 복구됩니다: 이미 저장된 파일은 재다운로드되지 않고 유지됩니다.
- 한 번에 50 크레딧(credits)을 초과하는 요청은 터미널에서 확인(confirmation)을 요구합니다(
--yes는 이 과정을 건너뜁니다).
최신 상태 유지하기
CLI는 최대 하루에 한 번, 더 새로운 버전이 출시되었는지 알려주며, ludo update 명령어로 설치할 수 있습니다.
만약 특정 버전이 지원되지 않게 되면, 명령어는 코드 10과 함께 업데이트 방법을 안내하며 종료됩니다.
Ludo의 서비스 공지(예: 장애 발생)는 stderr에 동일한 방식으로 표시됩니다.
로그인하기
ludo login을 실행하면 짧은 코드가 출력되고 브라우저에서 app.ludo.ai/cli가 열립니다. 거기서 로그인하거나 (만약 API 접근 권한이 없다면 계정을 만들고 해당 기능을 가진 플랜을 선택), 코드가 터미널의 코드와 일치하는지 확인하고 'Authorize'를 클릭합니다. CLI는 자체 키를 가지므로, 사용자의 주요 API 키 및 모든 MCP 설정은 계속 작동합니다. 각 CLI 로그인은 웹 앱의 API & MCP 섹션에 나열되며 여기서 취소(revoke)할 수 있습니다. ludo logout 역시 로그아웃을 처리하여 권한을 취소합니다.
브라우저가 없는 장치에서는 인쇄된 링크를 모든 기기에서 여십시오. CI 환경의 경우, LUDO_API_KEY를 설정하거나 ludo login --with-key로 키를 저장하십시오 (프롬프트 또는 표준 입력(stdin)에서 키를 읽습니다).
터미널에서 가입하기
웹 앱을 열면 됩니다. 이 기능은 코딩 에이전트가 Ludo를 설정하는 것을 위해 만들어졌으며, 일반 사용자에게도 동일하게 작동합니다.
- 해당 이메일 주소와 플랜에 대한 Stripe 결제 링크가 출력되며 대기합니다. 링크가 지불되기 전까지는 아무것도 생성되거나 청구되지 않습니다.
- 링크를 지불하십시오 (본인 또는 자체 지갑을 가진 에이전트). 카드만 가능합니다.
- 해당 주소로 연결 코드(connect code)와 웹 앱의 비밀번호 설정 링크가 이메일로 전송됩니다.
- CLI가 코드를 요청할 때 코드를 입력하거나, 나중에
ludo signup --continue --code <코드>를 사용하여 전달하십시오. 그러면 CLI에 로그인됩니다.
이 키는 메일함에서 받은 코드에 대해서만 발급되므로, 다른 사람의 주소로 가입을 시작하면 아무것도 얻지 못합니다. 순차적으로 작업하는 에이전트의 경우, --no-wait은 링크를 출력하고 반환하며, ludo signup --continue는 상태를 확인하고, --restart는 여전히 대기 중인 가입을 취소합니다. 여기서는 API 접근 권한이 있는 단일 사용자 플랜만 구매할 수 있으며, 팀 플랜은 웹 앱에서 구매해야 합니다.
브라우저 없이 Link로 결제하기
Link의 CLI(link-cli, Stripe 에이전트 지갑; 작동 방식)를 가진 에이전트는 결제 링크 대신 공유 결제 토큰(Shared Payment Token)으로 결제할 수 있습니다:
ludo signup --plan indie --email [email protected] --quote
link-cli spend-request retrieve <lsrq_id> --include shared_payment_token --format json
...
Ludo는 토큰을 충전하고, 계정을 생성하며, CLI(명령어 인터페이스)에 로그인하는 과정을 한 단계로 처리합니다: 결제 페이지나 이메일 코드가 필요 없습니다. 주소로는 여전히 비밀번호를 설정할 링크가 전송됩니다. --recurring-interval을 사용하여 생성된 토큰(인용된 명령어가 하는 것처럼)은 소유자가 승인한 한도 내에서 각 갱신 비용을 지불합니다. Link에서 이를 취소하면 그 기능이 중단되며, 웹 앱에서는 카드 정보를 요청하게 됩니다. 일회성 토큰은 하나의 기간을 구매하며, 이후 계획은 종료됩니다. 토큰은 하나의 계정을 구매하며, 소유자에게는 현금과 같습니다: 로그나 셸 히스토리에서 보관하지 마십시오 (--payment-token -는 표준 입력(stdin)에서 읽거나, LUDO_PAYMENT_TOKEN을 설정하십시오).
키는 다음 순서로 사용됩니다: --api-key, LUDO_API_KEY 환경 변수, 그리고 ludo login에 의해 저장된 키(사용자만 읽을 수 있는 ~/.config/ludo/config.json 내).
크레딧