GEOFlow CLI完全指南：一行命令远程管理GEO实例的任务、素材与文章
【免费下载链接】GEOFlowOpen-source GEO content engineering and multi-site distribution platform with AI quality inspection, illustrated admin help, hosted sites, browser-assisted publishing, and signed updates.项目地址: https://gitcode.com/gh_mirrors/geof/GEOFlow
GEOFlow CLI 是 GEOFlow 开源项目内置的命令行工具，也是连接 GEO 实例的 API v1 客户端。它让你无需打开浏览器，就能用一行命令完成远程管理：创建和启动内容任务、批量维护关键词库/标题库/图片库等素材、创建与发布文章，还能对文章执行 AI 质检复查与 AI 优化。当前版本0.3.0-preview.1还支持多 profile、显式 scope 登录和任务收据等远程管理能力，适合把 GEOFlow 接入自己的自动化流程 🚀
GEOFlow CLI 是什么？为什么需要它？
简单说：GEOFlow CLI 是一个独立运行的geoflow可执行程序（独立 PHAR），负责配置文件、登录、HTTPS 策略、密钥脱敏、JSON 校验、删除确认和 API 错误提示。
和 Web 后台相比，它有 3 个突出优势：
- 📦无需 Core 源码：独立安装后可在没有 GEOFlow 源码的机器上连接实例
- 🔐密钥更安全：Token 自动脱敏、配置文件权限锁定为
0600，支持从 stdin 读取密码 - ⚙️可脚本化：输出标准 JSON、稳定退出码，天然适合 CI 和定时任务
CLI 源码位于 app/Console/GeoFlowCli/ 目录，API 路由定义在 routes/api.php。
GEOFlow CLI 安装步骤：两种方式任选
方式一：源码运行（适合开发者）
前提：PHP 8.3+、已安装 Composer 依赖、可访问一个启用/api/v1的 GEOFlow 实例。
git clone https://gitcode.com/gh_mirrors/geof/GEOFlow cd GEOFlow composer install --no-interaction --prefer-dist bin/geoflow --version # 返回 JSON 版本信息 bin/geoflow --help # 查看完整命令列表方式二：独立签名包（适合纯运维环境）
从可信渠道取得install.php安装器和信任公钥，用一条命令完成安装：
php /trusted/installer/install.php \ --bundle=/absolute/build-output \ --trusted-keys=/absolute/trusted-keys.json \ --bin-dir=/absolute/bin安装器会核验 Ed25519 签名、版本和 SHA-256 摘要，中断后可用--recover恢复安装。详细流程见 packages/geoflow-cli/README.md 与 packages/geoflow-cli/DISTRIBUTION.md。
💡 平台支持：macOS、Linux、WSL 为正式支持环境；原生 Windows 需手动限制配置文件权限。
3步完成登录与配置：profile、Token 与环境变量
第 1 步：初始化配置。已有 Token 的话，一条命令写入默认配置文件：
bin/geoflow config init --base-url https://geoflow.example.com自动化环境可用--token-stdin从 stdin 读取 Token，避免密钥出现在命令行参数里。
第 2 步：登录实例。交互登录会隐藏密码：
bin/geoflow login --base-url https://geoflow.example.com --username admin新版还支持--scopes显式申请权限（如--scopes sites:read,themes:read），并可用--profile staging把登录结果写入指定 profile，实现多实例一键切换：
geoflow whoami --profile staging # 核对当前身份 geoflow capabilities --profile staging # 查看实例支持的能力 geoflow doctor --profile staging # 检查连接健康状况 geoflow profile bind --instance-id UUID --admin-id ID # 固定旧 profile 身份第 3 步：核对配置来源。config show会显示脱敏 Token、endpoint 与凭据的来源和绑定状态。
CLI 支持的环境变量：
| 配置项 | 环境变量 |
|---|---|
| 系统地址 | GEOFLOW_BASE_URL |
| Token | GEOFLOW_TOKEN、GEOFLOW_API_TOKEN |
| 超时秒数 | GEOFLOW_TIMEOUT |
配置文件按优先级选择：--profile NAME→--config PATH→ 当前目录.geoflow.json→~/.config/geoflow/config.json。🔒 安全细节：CLI 会拒绝可能把 Token 发往错误主机的 endpoint/凭据组合，完整规则见 docs/GEOFLOW_CLI.md。
任务管理：从创建、启动到查看执行记录
任务（Task）是 GEOFlow 内容生产的引擎。用 CLI 管理任务，全程无需离开终端：
# 查看任务列表（支持分页、状态过滤、搜索） geoflow task list --status running --search "测试" # 从 JSON 文件创建任务（name、title_library_id、prompt_id、ai_model_id、need_review 必填） geoflow task create --json ./task.json --idempotency-key task-create-001 # 启动任务并立即入队，查看最近 20 条执行记录 geoflow task start 12 --enqueue-now --idempotency-key task-start-12 geoflow task jobs 12 --limit 20 geoflow job get 88⚠️ 创建任务时必须显式提供need_review：1表示每篇人工审核，0表示通过风险检查及已启用的 AI 质检后自动发布。CLI 会在请求前拒绝缺少审核策略的输入，帮你避免配置疏漏。
创建前建议先跑一次geoflow catalog，返回模型、提示词、关键词库、标题库、图片库、知识库、作者和分类，确认task.json中引用的 ID 都存在。
素材管理：关键词库、标题库、图片库与知识库批量操作
material命令族覆盖 6 种素材类型：categories（分类）、authors（作者）、keywords（关键词库）、titles（标题库）、images（图片库）、knowledge（知识库）。
geoflow material summary # 一眼看全各素材库总量 geoflow material list keywords --search CRM # 列出关键词库 geoflow material get titles 34 # 查看某个标题库 geoflow material item-create titles 34 --json ./items.json # 批量新增条目上传封面图只需一行（仅images类型支持）：
geoflow material item-upload images 9 --image ./cover.png --idempotency-key image-upload-001删除操作需要交互确认，非交互环境加--yes；支持--ids 101,102批量删除条目。注意：知识库条目是系统自动切块的只读资源，修改知识库正文后系统会重建切块。
文章全流程管理：创建、审核、AI 质检到发布
article命令族是 GEOFlow CLI 的重头戏，覆盖文章从创建到发布（含 AI 质检与 AI 优化）的完整生命周期：
| 命令 | 作用 |
|---|---|
article list | 按任务、状态、AI 质检状态、作者、关键词检索 |
article create | 支持--json或--title、--content-file等直接字段 |
article review | 记录人工审核，保留当前发布安排 |
article publish/schedule/hold | 立即发布 / 按任务间隔排队 / 保留人工发布意图 |
article ai-quality-status | 查看 AI 质检阶段、耗时与安全错误码 |
article ai-quality-recheck | 让旧质检结果失效并重新排队 |
article ai-optimize | 生成影子候选（不动正文），可再ai-optimization-apply应用 |
article trash | 移入回收站 |
一个典型的"创建 → 审核 → 发布"流程：
geoflow article create --title "CLI article" --content-file ./article.md \ --author-id 5 --category-id 2 --idempotency-key article-create-001 geoflow article review 101 --status approved --note "Reviewed" geoflow article publish 101 --idempotency-key article-publish-101💡 四个动作（review/schedule/publish/hold）都支持--workflow-version N乐观锁，版本冲突返回 409，刷新文章后重试即可。AI 优化默认生成"影子候选"，正式文章保持原状，应用候选时必须显式提交运行 ID 与候选哈希，防止误覆盖。
安全设计亮点：为什么敢在终端跑生产操作？
GEOFlow CLI 在安全性上做了不少"防御性"设计，值得了解：
- 🌐HTTPS 优先：无协议地址自动补
https://；仅回环地址允许 HTTP，远程 HTTP 必须显式--allow-insecure-http，且始终验证证书、不跟随重定向 - 🎭密钥脱敏：配置文件权限
0600、默认配置目录0700，输出中的 Token 自动脱敏 - 🔁幂等键与任务收据：创建、更新、发布等操作可用
--idempotency-key防重复；api tasks.enqueue使用--client-request-id续接，响应丢失后可查询收据而非盲目重发 - 📏响应上限：拒绝超过 5 MiB 的响应，要求 identity 编码，杜绝中间人压缩劫持
- 🗑️删除保护：
task delete、material delete等默认交互确认，--yes只确认当前命令的精确目标，服务端权限与资源锁仍然有效
Docker 环境中运行 GEOFlow CLI
如果你用 Compose 部署，一行exec即可进入应用容器执行：
docker compose exec app php bin/geoflow --version docker compose exec app php bin/geoflow --config /path/in/container/profile.json catalog生产环境显式指定 Compose 文件：
docker compose --env-file .env.prod -f docker-compose.prod.yml exec app php bin/geoflow --version建议通过只读 secret mount 提供 profile，避免把 Token 写进镜像层或可公开的环境文件。
常见问题快速排障
| 现象 | 处理建议 |
|---|---|
401 | Token 无效或过期，重新login或更新 Token |
403 | Token 缺少所需 scope，签发最小权限 Token |
409 | 幂等冲突或版本冲突，先读取资源当前状态 |
| 返回 HTML 而非 JSON | base_url应指向 Web 根地址，别带/api/v1或后台路径 |
429 | 按retry_after字段等待，勿重复登录 |
| 删除在非交互环境失败 | 先get确认 ID，再为精确删除命令加--yes |
进阶：远程管理预览版能力
0.3.0-preview 已新增多 profile、显式 scope、whoami/capabilities/doctor连接核对、当前令牌撤销（logout）、任务收据，以及主站主题草稿、原子文件修改与签名预览（通过api theme-workspaces.*系列操作）。注意：主题发布、统一回滚和完整后台管理尚未开放，边界与未开放项见 docs/api/remote-management-preview.md。
参考资料
- 📖 CLI 完整文档：docs/GEOFLOW_CLI.md（英文版 docs/GEOFLOW_CLI_en.md）
- 📦 独立 CLI 构建与安装：packages/geoflow-cli/README.md
- 🧾 远程管理覆盖说明：docs/api/remote-management-preview.md
- 🗂️ CLI 源码目录：app/Console/GeoFlowCli/
- 🚀 API v1 路由：routes/api.php
从"三行命令登录"到"一行命令发布文章"，GEOFlow CLI 让你把 GEO 内容生产的任务、素材与文章管理全部搬进终端。先在测试实例上跑一遍catalog → task list → article list的只读核对，再逐步启用写操作，是最稳妥的上手路径 🎯
【免费下载链接】GEOFlowOpen-source GEO content engineering and multi-site distribution platform with AI quality inspection, illustrated admin help, hosted sites, browser-assisted publishing, and signed updates.项目地址: https://gitcode.com/gh_mirrors/geof/GEOFlow
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
