35개 이상의 이미지·비디오 생성 모델을 셸 명령 한 줄로 호출하고, Claude Code나 Cursor 같은 에이전트가 그대로 가져다 쓰도록 만들어진 단일 바이너리 CLI. 왜 별 3개짜리 신생 레포가 TrendShift 11위에 올랐는지를 본다.
웹 UI가 차고 넘치는데 굳이 터미널?
이미지·비디오 생성 AI는 보통 화려한 웹 UI에 갇혀 있다. Midjourney도, Runway도, Higgsfield 본체도 그렇다. 마우스로 드롭다운을 열고, 슬라이더를 움직이고, 미리보기를 본 다음 "생성" 버튼을 누른다. 한 장 만들 때는 좋지만, 스무 장을 같은 조건으로 일관되게 뽑거나, 다른 코드에 끼워 자동화하려는 순간 갑자기 막힌다.
CLI(Command-Line Interface, 명령줄 인터페이스)는 정반대다. 입력값을 텍스트로 받고, 결과를 파일로 떨군다. 다른 스크립트가 그 출력을 받아 다음 단계로 보낼 수 있다. 1990년대 ImageMagick부터 2020년대 ffmpeg까지, "미디어를 다루는 좋은 도구는 결국 CLI를 갖는다"는 흐름이 있다. Higgsfield CLI는 거기에 생성형 AI 모델 35개를 한 번에 끼워 넣은 셈이다.
ls, git commit. 자동화와 스크립트 연결이 강점.여기서 한 발 더 나아간 것이 Higgsfield CLI다. 단순히 "터미널에서도 쓸 수 있게" 만든 게 아니라, Claude Code·Cursor·Codex 같은 AI 코딩 에이전트가 도구처럼 호출할 수 있게 설계되었다. 사람이 직접 치는 것도 되고, 에이전트가 자동으로 부르는 것도 된다 — 같은 한 줄짜리 인터페이스로.
한 문장으로 압축하면.
핵심은 모델 다양성(텍스트→이미지, 이미지→비디오, 페이스 일관성 학습)을 한 인터페이스로 통일했다는 점. higgsfield generate create <모델명> --prompt "…" 같은 형식 하나로 Veo·Kling·Soul·Nano Banana를 동일하게 호출한다. 게다가 npx skills add higgsfield-ai/skills 한 줄로 Claude Code의 도구 카탈로그에 그대로 꽂힌다.
스타 수와 트렌드 점수의 괴리.
이 레포는 GitHub 별이 단 3개다. 그런데 TrendShift 일간 11위(11점)에 올라 있다. 트렌딩 점수는 별 수가 아니라 X(트위터)·해커뉴스 같은 외부 멘션의 속도로 계산된다. 즉, 별을 누른 사람은 적지만 "오, 이거 나왔네" 하고 SNS에 공유하는 개발자가 많다는 뜻이다.
왜 공유되는가? 세 가지를 동시에 친다.
Sora 2, Veo 3.1, Kling 3.0, Seedance 2.0 같은 최고급 영상 모델들을 지금까지는 각자의 웹 사이트에서 따로 결제하고 따로 써야 했다. Higgsfield CLI는 이걸 하나의 크레딧·하나의 명령으로 묶었다. 모델 비교가 "탭 5개 띄우고 같은 프롬프트 5번 입력"에서 "스크립트 1개로 한 번에 5개 호출"로 줄어든다.
2026년 트렌드는 Claude Code·Cursor·Codex 같은 에이전트가 도구를 호출하는 방식. 그런데 영상·이미지 생성은 아직 에이전트 도구 카탈로그에 정착한 게 없다. Higgsfield는 CLI + MCP 서버 + Skill을 동시에 내놓아, 어떤 에이전트라도 "고양이 사진 생성해줘" 한 마디로 Soul 모델을 호출하게 만들었다. 트렌딩에 같이 오른 nano_banana_2, higgsfield-ai/skills 등 동반 레포들이 같은 흐름을 보여준다.
레포 자체보다 호스트인 Higgsfield 공식 사이트의 캐치프레이즈가 강하다 — "One prompt replaces your entire agency". UGC·TV 광고·Wild Card 포맷의 영상을 한 브리프로 뽑고, 인플루언서 아웃리치 메일까지 생성한다는 주장. 과장 여부는 차치하고, "터미널 한 줄로 광고 캠페인"이라는 픽업 라인이 트위터 알고리즘에 잘 먹힌다.
CLI 본체·인증·배포·연동까지.
레포 자체는 100% Shell로 분류되지만, 이건 install.sh 하나만 공개되어 있어서 그렇다. 실제 본체 바이너리(hf)는 Go로 짠 듯한 정적 컴파일 결과물이 릴리즈로만 배포된다(macOS/Linux × amd64/arm64 조합). 풀스택 관점에서 보면 다음 4개 층이 맞물려 있다.
hf (별칭 higgsfield, higgs)릴리즈 패키지 이름이 hf_${VERSION}_${OS}_${ARCH}.tar.gz 형식. 의존성 없이 한 파일만 받아 $PATH에 놓으면 끝난다. macOS·Linux의 amd64·arm64 4종 빌드만 제공. 이런 패턴은 보통 Go나 Rust로 만든다 — 의존성 묶어 단일 바이너리로 떨구기 쉽기 때문.
higgsfield auth login을 치면 브라우저가 열리고, CLI는 백그라운드에서 짧은 코드를 폴링한다. 로그인이 끝나면 토큰을 로컬에 저장한다. API 키를 직접 복사·붙여넣을 필요가 없다. 스마트 TV에서 넷플릭스 로그인할 때 휴대폰으로 코드 치는 그 방식과 같은 패턴.
CLI는 결국 https://higgsfield.ai의 REST/gRPC API를 호출한다. 생성 요청은 비동기 잡으로 큐에 들어가고, generate wait가 폴링하다 결과 URL을 받아온다. model list로 35+ 모델의 파라미터 스키마를 받아 자동완성·검증에 쓴다 — "live catalog"라는 표현은 모델 추가 시 클라이언트 재배포 없이 즉시 반영된다는 뜻.
같은 백엔드를 두 가지 추가 인터페이스로도 노출한다. MCP(Model Context Protocol) 서버는 Claude·Cursor·Codex가 도구를 발견·호출하는 표준 프로토콜. npx skills add higgsfield-ai/skills는 Claude Code의 스킬 카탈로그에 정의를 꽂는다. CLI·MCP·Skill 셋이 같은 API를 다른 옷으로 감싸고 있는 구조.
| 채널 | 명령어 | 특징 |
|---|---|---|
| curl 스크립트 | curl -fsSL …/install.sh | sh | GitHub API로 최신 릴리즈 자동 감지, tarball 직접 다운로드 |
| Homebrew | brew install higgsfield-ai/tap/higgsfield | macOS·Linux. 업데이트는 brew upgrade |
| npm | npm install -g @higgsfield/cli | 공식 사이트에서 안내하는 빠른 길 |
| 수동 다운로드 | Releases 페이지에서 tarball | OS·아키텍처 맞춰 바이너리 직접 배치 |
사람·에이전트·다중 모델이 만나는 깔때기.
Higgsfield CLI는 자체로 완결된 도구가 아니라 3방향 깔때기다. 입력은 사람의 키보드 + AI 에이전트의 도구 호출에서 들어오고, 출력은 35+ 모델 각각이 흩어져 있는 GPU 클러스터로 흘러간다.
[사람: 터미널] [에이전트: Claude Code/Cursor]
│ │
│ higgsfield generate │ MCP 도구 호출
│ create veo3_1 --prompt "…" │ "generate cinematic video"
▼ ▼
┌────────────────────────────────────────────────┐
│ hf 바이너리 (CLI 본체) │
│ · auth: device-code OAuth → ~/.higgsfield │
│ · model list/get: 35+ 모델 스키마 캐시 │
│ · upload: 로컬 파일 → UUID │
│ · generate create/wait/get: 비동기 잡 │
│ · soul-id: 3~5장 사진 → 얼굴 일관성 모델 │
│ · marketing-studio: 바이럴 점수 계산 │
└────────────────────────────────────────────────┘
│
│ HTTPS (토큰 인증)
▼
┌────────────────────────────────────────────────┐
│ Higgsfield Cloud API (서버) │
│ · 모델 카탈로그(라이브) │
│ · 비동기 잡 큐 + 폴링 엔드포인트 │
│ · 워크스페이스/크레딧/팀 │
│ · 결과물 CDN (cdn.higgsfield.ai) │
└────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
[Veo 3.1 GPU] [Kling 3.0 GPU] [Soul ID 학습 GPU]
[Grok Video GPU] [Seedance 2.0] [Nano Banana Pro]
… 총 35+ 모델 분산 실행 …
비슷한 도구는 보통 모델마다 다른 명령을 만든다(cli sora, cli veo). Higgsfield는 generate create <모델명> --prompt …로 통일했다. 새 모델이 추가돼도 CLI 재설치 없이 model list로 바로 나타난다. 모델 카탈로그가 서버에 산다는 결정이 이걸 가능하게 한다.
참조 이미지가 필요할 때 --image ./photo.png 같은 로컬 경로도, --image <UUID> 같은 이전 잡의 결과 ID도 똑같이 받는다. 로컬 경로면 CLI가 알아서 upload image 호출 후 UUID로 치환. "파일이냐 ID냐"를 사용자가 구분하지 않아도 되는 인터페이스.
generate create는 잡을 제출만 하고 즉시 반환. generate wait는 폴링, generate get은 끝난 잡의 결과 조회. 영상 생성처럼 1~5분 걸리는 작업에 적합한 패턴. 스크립트에서는 제출 후 다른 작업을 하고 마지막에 한꺼번에 회수할 수 있다.
generate cost는 같은 파라미터로 실제 호출 없이 크레딧 소비량만 미리 계산한다. 4K 15초 비디오를 잘못 눌러 크레딧을 날리는 사고를 막는다. 스크립트가 자동으로 비용 임계치를 체크하고 confirm 받게 짤 수 있다.
같은 API를 (1) 사람용 CLI, (2) 에이전트용 MCP 서버, (3) Claude Code용 Skill로 세 번 감쌌다. 어느 입구로 들어와도 결국 같은 잡 큐로 모인다. "AI 에이전트가 도구를 호출하는 미래"에 베팅한 회사가 모든 입구를 다 만들어두는 전형적인 전략.
레포에는 사실 파일이 5개뿐.
처음 레포를 열면 놀랄 만큼 비어 있다. 본체 소스는 다른 곳(아마 비공개 모노레포)에 있고, 공개 레포는 "설치 + 문서"만 담는 얇은 껍데기다.
higgsfield-ai/cli/ ├── README.md # 설치·인증·생성 예시 ├── LICENSE # MIT ├── MODELS.md # 44개 모델 파라미터 스키마 (higgsfield model list 결과) ├── install.sh # 운영체제/아키텍처 감지 + 릴리즈 다운로드 + 심볼릭 링크 ├── demo.png # CLI 데모 스크린샷 └── (Releases 탭) # 버전별 OS/ARCH 조합 tarball
이런 "껍데기 레포" 전략은 다음 회사들에서 종종 본다 — Vercel CLI, Supabase CLI, Anthropic Claude CLI. 본체 코드는 공개하지 않으면서 "설치 경로는 오픈"으로 두는 절충안. 보안 검증을 원하는 개발자가 install.sh를 미리 읽을 수 있고, 회사는 본체 IP를 보호한다.
겉보기엔 단순한 다운로드 스크립트지만, 디테일이 알차다. 짚어볼 부분:
uname -s, uname -m으로 darwin/linux × amd64/arm64 결정. 미지원 조합이면 즉시 에러.curl)로 최신 릴리즈 TAG를 조회한 뒤 tarball URL을 직접 다운로드. gh CLI는 사용하지 않음.xattr -d com.apple.quarantine로 다운로드 격리 속성 제거. 안 하면 "악성 소프트웨어 의심" 경고 뜸.higgsfield(원본) + higgs(별칭) + hf(짧은 별칭, huggingface CLI와 충돌 시 자동 건너뜀). 충돌 회피 로직이 정중하다.$PREFIX/bin이 쓰기 가능하면 그냥, 아니면 sudo. 사용자가 --prefix=$HOME/.local로 sudo 회피 가능.install.sh를 보면 그 도구의 운영 철학이 드러난다. 5KB짜리 스크립트에 sudo 회피, 별칭 충돌 처리, OS별 quarantine 해제까지 들어 있다는 건 — "초보가 처음 깔아도 안 막힌다"를 진지하게 챙겼다는 신호. CLI 본체 품질도 비슷할 가능성이 높다.
이 레포에서 훔쳐 쓸 수 있는 패턴들.
install.sh를 그대로 읽고 따라 써보면 좋다. 핵심: set -e로 실패 전파, trap으로 임시 디렉토리 정리, command -v로 의존성 체크, case로 OS·아키텍처 분기. 실습 아이디어: 본인 사이드 프로젝트(예: 작업일보 도구)의 단일 바이너리 인스톨러를 같은 패턴으로 작성.
스마트 TV·CLI에서 자주 쓰는 인증 패턴. RFC 8628(OAuth 2.0 Device Authorization Grant) 사양. 클라이언트가 짧은 코드를 받아 사용자에게 보여주고, 사용자가 다른 디바이스 브라우저에서 그 코드를 인증하면 클라이언트가 토큰을 폴링해 받아온다. 실습 아이디어: GitHub의 device-code 엔드포인트(POST /login/device/code)로 본인의 CLI에서 GitHub 인증 흐름을 구현해보기.
create → wait → get의 분리 패턴은 영상 처리·동영상 인코딩·LLM 추론처럼 시간이 오래 걸리는 모든 작업에 적용된다. 동기 응답으로 끝내면 타임아웃·재시도가 복잡해진다. 실습 아이디어: FastAPI나 Express로 "긴 작업 큐" 패턴을 직접 짜보기. 잡 ID 발급 → Redis 큐 → 워커가 처리 → 클라이언트가 폴링하는 최소 구조.
오늘날 어떤 백엔드 도구를 만들든, "사람용 UI"만 만드는 시대는 끝났다. 같은 기능을 사람용 CLI, AI 에이전트용 MCP 서버, Claude Skill의 세 가지 옷으로 감싸 두면 사용자 표면적이 몇 배가 된다. 실습 아이디어: 본인의 작은 REST API에 MCP 서버 어댑터(예: @modelcontextprotocol/sdk)를 얇게 붙여 Claude Code에서 호출해보기.
"새 모델 추가될 때 CLI 재배포 안 해도 된다"라는 한 줄짜리 결정이, 사실 클라이언트 자동완성·검증·문서 생성 전체를 바꾼다. model get <name>이 파라미터 스키마(타입·기본값·enum)를 통째로 내려주고, CLI는 그걸로 검증한다. 실습 아이디어: 본인의 도구 옵션 구조를 JSON Schema로 분리해서, 클라이언트가 그 스키마를 받아 자동완성에 쓰도록 짜보기.
실제 추론은 클라우드에서.
로컬에서 도는 건 단일 바이너리 + 네트워크 호출이 전부라 요구사항이 거의 없다. 진짜 무거운 GPU 일은 Higgsfield의 서버가 한다. 그래서 노트북이든 라즈베리파이든 셸만 돌면 OK.
| 항목 | 요구사항 | 참고 |
|---|---|---|
| 운영체제 | macOS, Linux, Windows | npm으로 크로스플랫폼 설치 가능; curl·Homebrew는 macOS·Linux 한정 |
| 아키텍처 | x86_64(amd64), arm64 | Apple Silicon, AWS Graviton, Raspberry Pi 4/5 등 포함 |
| 디스크 | 바이너리 단일 파일(수 MB) | 업로드 임시파일은 생성 후 정리됨 |
| 네트워크 | HTTPS 아웃바운드(higgsfield.ai, cdn.higgsfield.ai) | 방화벽 환경에서 차단 시 동작 불가 |
| 의존성 | curl 또는 gh(설치 시), tar | 대부분의 유닉스 시스템에 기본 탑재 |
| 계정 | Higgsfield 계정 + 크레딧 | 모델·해상도·길이에 따라 크레딧 차감 |
4K 이미지·15초 영상은 한 번 호출에 수십~수백 크레딧이 빠진다. 스크립트로 자동화할 때 generate cost로 사전 추정 후, 누적 예산 초과 시 중단하는 가드를 반드시 두자. CI 워크플로우에서 무한 루프로 호출되는 사고를 막는 게 가장 흔한 함정.
난이도 ★~★★★★.
install.sh로 설치하고 higgsfield auth login 후, Nano Banana로 "fox in snowy forest"를 생성한다. 결과 파일이 어디에 떨어지는지(보통 작업 디렉토리), 잡 ID가 어떻게 출력되는지 관찰하기.
같은 프롬프트를 Nano Banana, Soul, Flux, Seedream, GPT Image 2로 동시에 던지고 결과를 한 폴더에 모으는 Bash 스크립트 작성. generate create가 잡 ID만 반환하고 즉시 끝난다는 점을 활용해 병렬화. 끝나면 generate wait로 한꺼번에 회수.
본인 사진 3~5장으로 soul-id create를 호출해 face-faithful identity 모델을 학습시키고, 그 ID를 참조로 10장의 다른 스타일 사진을 생성한다(아마추어 작가의 일러스트 / 르네상스 유화 / 픽사 3D 등). 매번 같은 인물로 인식되는지 확인.
npx skills add higgsfield-ai/skills로 스킬을 추가한 뒤, Claude Code에게 "이 블로그 글에 어울리는 헤더 이미지를 만들어줘"라고 한국어로 요청. 에이전트가 어떤 모델을 선택하고 어떤 파라미터를 채우는지 추적해보기. 직접 CLI 쳤을 때와 결과·비용 비교.
매일 아침 RSS 5개를 읽고 핫뉴스 1개를 골라 Veo 3.1로 15초 영상을 만드는 cron 파이프라인. 핵심은 가드 3중 안전망 — (1) generate cost로 사전 추정 후 일일 예산 초과 시 중단, (2) account로 잔여 크레딧 확인, (3) 잡 큐가 30분 이상 안 끝나면 알림 + 취소. CI에서 무한 비용 사고를 막는 패턴을 직접 짜본다.
4주 코스로 짜본 동선.
이 레포의 README와 install.sh를 정독. Command Line Interface Guidelines(clig.dev)을 같이 읽고 본인 사이드 프로젝트에 적용할 수 있는 5개 원칙을 골라본다. 명령 동사·옵션 네이밍·exit code 컨벤션·도움말 형식.
RFC 8628 사양 정독. GitHub·Google·Atlassian이 device flow를 어떻게 구현했는지 비교. 로컬 토큰을 어디에 어떻게 저장하는가 — keychain, 평문 파일, 환경 변수의 트레이드오프. 본인 CLI에 GitHub device flow를 직접 구현.
Celery / BullMQ / RabbitMQ 중 하나를 골라 "긴 작업 + 폴링 API"를 직접 구축. 결과 캐싱(같은 입력 → 같은 출력), 잡 우선순위, 실패 재시도, 데드 레터 큐(DLQ)의 4가지를 모두 다뤄본다. 이 패턴을 알면 AI 추론 백엔드는 다 짤 수 있다.
본인이 만든 작은 API(예: 날씨, RSS 요약기)를 (1) CLI, (2) MCP 서버, (3) Claude Skill의 세 입구로 다 노출해본다. Anthropic의 @modelcontextprotocol/sdk와 Skill 작성 가이드를 참조. "같은 백엔드, 세 클라이언트" 패턴이 몸에 익는다.
이 글과 레포에 등장하는 용어들.
virality_predictor 명령은 생성한 영상의 engagement·후크 강도·이탈 위험을 점수로 매긴다. "퍼블리시 전 시사회" 비유.fe66ba5d-4db6-42e0-9ae3-a7e8d735b7a5). Higgsfield CLI는 업로드한 파일, 이전 잡의 결과를 모두 UUID로 참조한다.더 깊이 파고들 자료들.
GET /capabilities 같은 엔드포인트 하나로 클라이언트가 자동 확장된다.POST /login/device/code로 본인 CLI에서 짧은 코드를 받아 보여주고 토큰을 폴링하는 흐름을 30분 안에 짤 수 있다. 한 번 만들어두면 다음 모든 CLI에서 재사용.cost 사전 추정 + 일일 예산 + 실패 시 즉시 중단 — 이 3중 가드를 자동화보다 먼저 만들자.