Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
gflow-cli는 Google Flow의 Python CLI 및 MCP 서버로, Veo(image-to-video, text-to-video)와 Imagen(text-to-image) 같은 주요 AI 모델 기능을 터미널에서 쉽게 사용할 수 있게 합니다. 이를 통해 스크립트화, 배치 처리, 파이프라인 통합 등 개발 워크플로우에 바로 활용할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기터미널에서 Google Flow의 Python CLI 및 MCP 서버입니다. Veo (image-to-video, text-to-video)와 Imagen (text-to-image)을 스크립트화하고, 배치 처리하며, 파이프라인에 바로 사용할 수 있도록 구동하세요.
PyPI version
CI
Release
Python versions
License: MIT
Status: alpha
Code style: ruff
Type checked: pyright
Tests: TDD
Quality Gate Status
Coverage
OpenSSF Scorecard
Listed on mcpservers.org
⚠️ 설치 전 필독 사항. gflow-cli는 알파 버전이며 리버스 엔지니어링된 도구로, Google과 관련이 없습니다. 이 도구는 사용자 본인의 Google Flow 세션에서 헤드드 브라우저를 구동하므로, 사용자 계정의 위험으로 간주해야 합니다. 자동화는 Google의 서비스 약관(ToS)을 따르며, 엔드포인트나 UI는 예고 없이 변경될 수 있습니다. 이 도구는 Flow 접근 권한이 있는 모든 Google 계정에서 작동하며, 모든 생성 작업은 사용자 계정의 Flow 크레딧 할당량으로 청구됩니다. 전체 면책 조항을 읽어보세요.
🛡️ "내 계정이 플래그 지정될까요?" 솔직하고 구체적인 답변 — 이 도구가 눈에 띄지 않게 유지하기 위해 무엇을 하는지(헤드드 실제 Chrome 사용, 무작위화된 상호 작용 타이밍, 간격 조절 제출), 무엇을 의도적으로 하지 않는지(프록시 사용 안 함, 지문 위변조 없음, 자동화임을 가장하지 않음), 사용자가 조정할 수 있는 부분과 우리가 보장할 수 없는 부분이 docs/ACCOUNT_SAFETY.md에 나와 있습니다.
💳 실패가 비용으로 이어지는 경우. 크레딧은 Veo 비디오 생성에만 사용됩니다 — 이미지 및 구성 작업은 무료이므로, 대부분의 오류는 비용이 들지 않습니다. Flow의 UI가 실행 도중 이탈할 경우, CLI는 재제출하는 대신 명확한 종료 코드(예: 셀렉터 드리프트 = exit 23)와 함께 빠르고 크게 실패하며, 배치 항목은 제출 전에 로컬에 기록되므로, 오류가 난 작업이 오래된 상태에서 크레딧을 조용히 소모하는 일이 없습니다. 현재 위험 목록은 KNOWN_ISSUES를 참조하세요.
🌐 오늘날의 헤드드 브라우저. gflow는 Google의 인증 및 reCAPTCHA 게이트가 필요하기 때문에, 지속적인 Playwright Chromium 프로필을 통해 Flow를 구동합니다. 어디서 도움을 줄 수 있는지에 대한 내용은 아키텍처 섹션을 참조하세요.
Flow 접근 권한이 있는 Google 계정을 가지고 있고, Veo 크레딧을 보유했으며, 실제 배치 작업을 실행하는 경우. gflow-cli는 다음을 제공합니다:
for p in $(cat prompts.txt); do gflow image t2i "$p"; done. 이미지 배치 처리와 더불어 gflow video t2v / i2v / r2v가 모두 오늘 출시되며, gflow video extend는 Flow의 8초 제한을 넘어 기존 클립을 이어 나갈 수 있습니다.gflow character create를 사용하면 Flow Character(얼굴 및 몸체 참조)가 생성되어 동일한 사람이 한 세대에서 다음 세대로 나타납니다.--tool creative-director는 간결한 프롬프트를 생성 전에 생생한 프롬프트로 재작성합니다 (Google의 5가지 구성 요소 공식). 어떤 명령에서도 사용할 수 있습니다. My Tools를 통해 직접 도구를 가져오세요.gflow auth login 후에는 쉘 안에 머무릅니다. 대화형 창을 클릭할 필요가 없습니다.동일한 Veo 및 Imagen 모델, 동일한 품질, 사용자의 Google 계정으로 청구되는 동일한 비용이 이제 프로그래밍 방식으로 가능합니다.
# 1 · 설치 (uv 권장; 또한: pip install gflow-cli)
uv tool install gflow-cli
uv tool run --from gflow-cli playwright install chromium # 일회성, ~150 MB
...
출력물은 $GFLOW_CLI_OUTPUT_DIR 아래에 저장되거나, GFLOW_CLI_STORAGE_URI를 사용하여 S3, MinIO 또는 Google Cloud Storage로 라우팅할 수 있습니다. 첫 번째 호출에는 Chromium이 준비되는 동안 30초에서 90초가 걸리며, 이후 호출은 준비된 세션을 재사용합니다.
왜
--browser chrome인가요? 이는 프로필을 실제 Chrome 프로필로 표시하는 유일한 방법이며, 나중에 생성되는 실행이 이를 열 때 사용합니다. 기본값인auto는 Chrome이 설치되어 있을 때마다 선택됩니다 — docs/AUTHENTICATION.md를 참조하세요.
로컬 체크아웃에서 설치하는 경우? uv tool install <path>는 uv.lock을 무시하고 pyproject.toml의 범위(range)로부터 종속성을 해결하므로, 이 프로젝트가 테스트한 적 없는 Playwright 빌드를 제공할 수 있습니다. Playwright는 브라우저 드라이버를 포함하며, 테스트되지 않은 마이너 업데이트 버전 하나만으로도 세션을 조용히 중단시킬 수 있습니다. 따라서 잠긴(locked) 버전을 명시적으로 사용하십시오:
uv tool install --force --with playwright==1.59.0 .
PyPI에서 설치하는 경우 (uv tool install gflow-cli)는 영향을 받지 않습니다. 게시된 범위는 상한선으로 제한되기 때문입니다. uv tool run --from gflow-cli python -c "import importlib.metadata as m; print(m.version('playwright'))"를 사용하여 실제로 어떤 버전이 설치되었는지 확인하십시오.
전체 10분짜리 워크스루 및 문제 해결, 다중 계정 설정에 대한 내용은 **USER_GUIDE: Journey 1**를 참조하십시오.
단 하나의 명령어로 실제 Flow 출력을 얻습니다. 왼쪽은 라이브러리에서 사진처럼 사실적인 장면을 생성하는 gflow image t2i입니다. 오른쪽은 프레임별 변환(frame-to-frame transform)입니다.
gflow-cli examples: text-to-image generation, and a before/after frame transform
로그인된 Flow 프로필에 대해 단일 gflow image t2i "..." --aspect 9:16 --model nano2 호출을 수행합니다. 터미널은 실행의 structlog JSON 스트림을 출력한 다음, 작성된 PNG 파일을 나열합니다. Chromium이 백그라운드에서 Flow 에디터를 조용히 구동합니다.
scripts/record_demo.ps1 (Windows, OBS, ffmpeg, gifski)를 사용하여 녹화된 내용을 재현하십시오. 측면 분할 화면을 포함하여 더 많은 포맷은 **docs/DEMOS.md**에서 확인할 수 있습니다.
**docs/INDEX.md**가 마스터 라우팅 레이어입니다. 빠른 링크:
gflow-cli는 네 가지 에이전트 진입점(agent entry points)을 제공합니다. 도구가 가장 먼저 읽는 것을 선택하십시오.
| File | Audience | Tools |
|---|---|---|
| AGENTS.md | 범용 코딩 에이전트 사양 | Cursor · Codex · Aider · Antigravity · Jules · Devin · Windsurf · Zed · Warp · opencode · Copilot |
| ... |
한 단계만 거치면 gflow-cli와 video-production 스킬, 그리고 MCP 서버를 얻을 수 있습니다:
/plugin marketplace add ffroliva/gflow-cli
/plugin install gflow@gflow-cli
이 플러그인은 비활성화된 상태로 배포됩니다. Claude Code는 플러그인이 활성화될 때 자체 프롬프트 없이 자동으로 해당 플러그인의 MCP 서버를 시작합니다. 이 서버는 사용자의 Google 계정을 구동하며, Veo 비디오 생성 시 크레딧이 청구되는 곳입니다. 따라서 설치만으로는 아무것도 시작되지 않으며, 활성화하는 것은 의도적인 행위입니다. 이미지와 구성은 무료이며, 오직 비디오에만 비용이 발생합니다. 확실한 보장을 원한다면 gflow mcp run --no-spend를 사용하여 서버를 직접 등록하세요. 이 명령어는 크레딧을 소모하는 도구를 전혀 등록하지 않습니다. 어떤 리비전(revision)을 /plugin marketplace add가 제공하는지 포함하여 자세한 내용은 docs/MCP.md를 참조하세요.
Codex 사용자: codex plugin marketplace add . 다음 codex plugin add gflow@gflow-cli를 실행합니다.
원하는 에이전트에 한 줄로 모든 것을 적용할 수 있습니다. 아래 내용을 복사하여 사용하세요:
"AGENTS.md와 docs/INDEX.md를 읽고, 내 Flow 배치 작업을 도와줘."
gflow CLI → Provider (교체 가능) → Flow (ui_automation) / Mock (테스트) / [계획 중: 공식 Veo]
↓
Playwright Chromium (헤드드 — 기본적으로 로그인 및 생성)
...
현재 전송 방식(Current transport): ui_automation은 지속적인 Playwright Chromium 프로필을 통해 Flow를 구동합니다. 이는 프로덕션 환경에서 안정적이며, 매 릴리스마다 엔드투엔드로 검증되었습니다 (개별 릴리스의 LIVE_VERIFICATION_* 증거 파일 참조).
두 가지 Flow 프론트엔드: Google은 labs.google에서 flow.google.com으로 계정을 이전하고 있습니다 (#639). 동일한 제품이지만, 다른 위젯 툴킷과 와이어 프로토콜(aisandbox-pa 대신 batchexecute)을 사용합니다. 마이그레이션된 드라이버는 로컬 시작 프레임에서의 텍스트-투-비디오(text-to-video), 로컬 파일에서의 이미지-투-비디오(image-to-video), 로컬 파일에서의 레퍼런스-투-비디오(reference-to-video), 텍스트-투-이미지(text-to-image), 그리고 로컬 파일에서의 이미지-투-이미지(image-to-image)를 지원합니다. 이미지 생성은 Nano Banana 2.1 (nano2, #958) / 2 Lite / Pro, 해당 호스트에서 측정된 다섯 가지 종횡비(16:9, 4:3, 1:1, 3:4, 9:16), 그리고 카운트 1–4를 지원하며; 전송 경계에는 기존 프로젝트가 필요합니다. 이미지는 @이름(#723)으로 캐릭터 태그를 지정할 수 있습니다. UUID 미디어 참조, 이름 없는 엔티티 ID, 지침(instructions), Imagen 4, 그리고 나머지 매트릭스는 포팅될 때까지 기존의 labs 드라이버를 유지합니다 (GFLOW_CLI_FLOW_HOST, CONFIGURATION 참조).**
막힌 부분: 비디오 생성을 위한 순수 HTTP 전송 방식입니다. 비디오 업로드 엔드포인트는 Chrome 브라우저가 아닌 경우 HTTP 401을 반환하며, 수동으로 재현할 수 없는 reCAPTCHA 팝업이 있습니다. 세 가지 이전의 HTTP 전략(evaluate_fetch, bearer, sapisidhash)은 연구 목적으로 src/gflow_cli/api/transports/experimental/ 아래에 있으며, 프로덕션 경로에는 없습니다.**
도움을 줄 수 있는 방법: 만약 실제 Chrome 세션 외부에서 aisandbox-pa.googleapis.com을 구동해 본 경험이 있거나, Google의 봇 방지 스택에 대해 이해하고 있다면 이슈를 열어주십시오. 작동하는 REST 전송 방식은 서버리스 배포, 진정한 수평적 동시성(horizontal concurrency), 그리고 프로젝트 도달 범위를 약 10배 확장할 것입니다. 상세 정보: docs/ARCHITECTURE.md § Headed-browser dependency.**
Alpha. 이미지(t2i, i2i, upload, upscale, batch) 및 비디오(t2v, i2v, r2v, chain, extend, upscale) 실행이 ui_automation에서 엔드투엔드로 작동하며, 5가지 모델 Veo 선택기와 --duration, --count 옵션을 제공합니다. 단일 생성물을 넘어: gflow movie는 다중 장면 매니페스트를 렌더링하고, gflow instructions는 영구적인 에이전트 모드 브리프 카드(크레딧 무료)를 관리하며, gflow character는 재사용 가능한 피사체를 처리하고, gflow scene은 크레딧 무료 서버 측 스티칭을 수행합니다. --tool은 프롬프트 재작성 도구를 적용하며, MCP 서버(gflow mcp run stdio / gflow serve Streamable HTTP)는 핵심 인터페이스를 AI 에이전트에게 CI가 강제하는 CLI↔MCP 동등성 계약과 함께 노출합니다.
전체 마일스톤 기록은 CHANGELOG.md에서 확인할 수 있습니다. 프로젝트의 향후 방향은 ROADMAP.md을 참고하세요.
gflow-cli는 한 명의 개발자가 구축하고 유지보수합니다. 모든 릴리스는 실제 Google Flow를 통해 검증되며, 이 과정에서 실제 AI 크레딧이 소모됩니다. 또한, 사용자들이 자신의 파이프라인에서 이를 실행하기 때문에 문제가 발생하면 빠르게 수정할 수 있습니다. 스폰서십은 이 두 가지 비용을 모두 충당합니다.