跳转至

Griptape Nodes 命令行接口参考 (CLI Reference)

如果你对命令行接口 (CLI) 还不太熟悉，CLI 是一种通过在终端中输入文本命令（而非在图形界面中点击按钮）与底层软件进行直接交互的标准方式。Griptape Nodes 提供了名为 griptape-nodes（或其极简缩写别名 gtn）的专用命令行工具，让你能够在终端中对整个运行环境进行全面掌控。

griptape-nodes / gtn 专为管理和调度本地计算机上的 Griptape Nodes Engine 引擎而设计。它负责初始化工作区目录、持久化配置设置、管理外部模型缓存，并启动支撑 Web 画布编辑器的核心 WebSocket/HTTP 服务。真正的工作流连线与图计算则运行在引擎启动后弹出的浏览器图形界面中。

基础命令格式

griptape-nodes [options] [COMMAND]

如果运行时未指定任何具体子命令，CLI 将默认调用 engine 命令启动引擎服务。

核心命令与子命令目录

engine（默认启动命令）

启动本地 Griptape Nodes 执行引擎。

griptape-nodes engine

执行后将拉起底层 Python 引擎，并在默认浏览器中自动打开前端操作画布：https://nodes.griptape.ai。

init

初始化或重新配置 Griptape Nodes 工作区：交互式设置 API 密钥、工作区根目录、底层存储后端以及可选的扩展算子库。后续重复执行此命令将重新进入配置向导，以便随时变更设置。

griptape-nodes init [options]

常用可选参数 (Options)：

  • --api-key：直接传入 Griptape API 密钥，跳过终端交互式输入；
  • --workspace-directory：直接指定工作区在本地磁盘的绝对路径；
  • --storage-backend：指定存储后端类型（可选 local 本地磁盘或 gtc Griptape Cloud 云端托管）；
  • --bucket-name：当选择 --storage-backend gtc 时，指定使用的云端存储桶名称（新建或已有）；
  • --register-diffusers-library / --no-register-diffusers-library：安装（或跳过）官方 Diffusers 图像扩散算子库；
  • --register-griptape-cloud-library / --no-register-griptape-cloud-library：安装（或跳过）Griptape Cloud 官方托管算子库；
  • --no-interactive：以纯无头模式运行初始化，完全不提示任何交互提问，仅依赖传入参数与出厂默认值；
  • --hf-token：设置用于下载 Hugging Face 门控受限模型的访问令牌 (HF Token)；
  • --config key=value：设置任意引擎配置键值对；可多次重复使用（例如 --config log_level=DEBUG --config workspace_directory=/tmp）；
  • --secret key=value：设置任意系统密钥键值对；可多次重复使用（例如 --secret MY_API_KEY=abc123）。

config

管理并检查 Griptape Nodes 的当前系统配置。

griptape-nodes config SUBCOMMAND

子命令列表：

  • show [config_path]：打印当前生效的配置信息。不带参数时将整个合并后的配置以 JSON 格式打印输出；传入以点分隔的路径（如 workspace_directory）时，仅打印对应的单项配置；
  • list：按加载优先级从高到低列出所有参与配置计算的配置文件路径；
  • reset：将全局配置彻底重置为出厂初始默认状态。

有关全部支持的配置项详尽字典，请参阅 配置参考指南。

self

管理 CLI 工具本身的状态、版本与安装生命周期。

griptape-nodes self SUBCOMMAND

子命令列表：

  • uninstall：彻底卸载 CLI 工具，清除其配置目录、缓存数据并删除可执行文件；
  • version：打印当前安装的 CLI 与引擎版本号；
  • info：生成并打印专用于排错诊断的系统信息报告：包含引擎版本、安装源、操作系统与 Python 环境、各层配置文件的覆盖堆叠情况、当前生效设置、已注册的三方库清单及其版本等。该输出完全经过脱敏处理（敏感 API 密钥与凭据均被安全过滤，用户根目录自动替换为 ~，用户名自动替换为 <user>），可安全地直接粘贴到公开 Issue 或工单中；
    • --show-identity：保留真实的家目录路径与用户名，不作 ~ 和 <user> 替换（但敏感凭据依然会被强制移除）；
    • 若需将系统信息连同历史执行日志打包导出为单一文件，请使用下文介绍的 diagnostics collect。

libraries

管理本地已注册的算子库。关于算子库的体系化管理指引，请参阅 算子库指南。

griptape-nodes libraries SUBCOMMAND

子命令列表：

  • sync：将所有已注册的外部 Git 算子库批量拉取更新至最新版本；
    • --overwrite：更新前强制丢弃本地工作区中任何未提交的修改；
  • download <git_url>：从远程 Git 仓库 Clone 克隆算子库并自动完成注册；
    • --branch：指定检出的分支、Tag 标签或特定 Commit 哈希；
    • --target-dir：指定克隆后的目标子文件夹名称；
    • --download-dir：指定算子库克隆落盘的上级父目录；
    • --overwrite：如果本地已存在同名目录，强制覆盖。

models

管理从 Hugging Face Hub 下载的本地 AI 深度学习模型权重（例如本地 Diffusers 扩散模型或端侧轻量 LLM 模型）。

griptape-nodes models SUBCOMMAND

子命令列表：

  • download <model_id>：从 Hugging Face Hub 下载模型（例如 microsoft/DialoGPT-medium）；
    • --local-dir：指定模型下载落盘的本地缓存路径；
    • --revision：指定下载的模型 Git 版本（默认 main）；
  • list：列出当前本地缓存中已下载的所有模型权重文件及其磁盘占用空间；
  • delete <model_id>：从本地缓存中彻底删除指定的模型文件；
  • search [query]：在终端中直接检索 Hugging Face Hub 上的模型；
    • --task：按模型任务类型进行过滤（如 text-generation）；
    • --limit：最大返回结果条数（默认 20，上限 100）；
    • --sort：排序字段（默认按下载量 downloads 排序）；
    • --direction：排序方向（默认降序 desc）；
  • downloads status [model_id]：实时查看单个模型（或所有正在下载模型）的后台拉取进度；
  • downloads list：列出所有受追踪的模型下载任务状态；
  • downloads delete <model_id>：清除模型的下载状态追踪记录（仅清除追踪日志，不删除实际文件）。

doctor

对 Griptape Nodes 本地运行环境进行全方位深度“体检”，以结构化表格形式呈现检查结论并给出修复建议。

griptape-nodes doctor

各项体检结果严格评定为以下三类状态之一：PASS（通过）、WARN（警告，虽然能跑但后续可能会踩坑） 或 FAIL（失败，当前环境存在硬性故障）。涵盖的核心检查项包括：

  • Workspace（工作区）：工作区根目录是否存在，且当前用户是否拥有读写权限；
  • Disk Space（磁盘空间）：工作区所在物理驱动器是否有充足空间容纳工作流资产与三方依赖；
  • Libraries（算子库）：检查所有登记的算子库是否能正常装载，有无因缺少依赖而节点丢失；
  • Secrets（环境变量与密钥）：各算子库所声明的必需 API 密钥是否均已配置赋值；
  • Log Capture（日志捕获）：后台引擎日志是否正常记录落盘；
  • Cloud Connection（云端连接）：本机与 Griptape Cloud 服务通信链路是否畅通。

当存在任何一项检查为 FAIL 时，命令将退出并返回非零错误码（适合集成进 CI/CD 自动化流水线）；纯警告项则以状态码 0 正常退出。

体检结果还会自动保存为 doctor.json 归档在诊断包中，便于他人协助分析。

diagnostics

一键采集系统排错所需的全量核心数据并打包为标准化 .zip 压缩包，方便在反馈 Bug 时附送。

griptape-nodes diagnostics SUBCOMMAND

子命令列表：

  • collect：生成诊断数据包：囊括系统日志、当前生效配置、所有已装载算子库状态以及 doctor 健康体检报告；
    • --output，-o：指定诊断包生成的输出路径；
    • --skip-logs：从诊断包中剔除详细日志；
    • --skip-libraries：跳过加载算子库。速度更快，但无法诊断三方算子库装载失败的细节；
    • --show-identity：保留真实的家目录绝对路径与用户名。

安全承诺：该命令生成的诊断包仅保存在你的本地计算机上，绝对不会自动上传到公网。诊断包由引擎在本地生成，引擎会自动扫描并剔除所有识别出的 API 密钥与密码凭证。压缩包内附带的 manifest.json 会列明所有被脱敏的项，README.md 则用通俗语言解释了每个文件的用途。

配置文件物理存储路径

Griptape Nodes 在本地操作系统中的标准配置存储路径如下：

  • 配置根目录 (Config Directory)：
    • macOS / Linux：~/.config/griptape_nodes
    • Windows：%USERPROFILE%\.config\griptape_nodes
  • 数据根目录 (Data Directory)：
    • macOS / Linux：~/.local/share/griptape_nodes
    • Windows：%USERPROFILE%\.local\share\griptape_nodes
  • 主配置文件：配置根目录下的 griptape_nodes_config.json
  • 环境变量配置：配置根目录下的 .env

注：Griptape Nodes Desktop 客户端会将上述配置目录存放在独立的桌面客户端数据目录中，与独立运行的 CLI 引擎互不干扰。详见 卸载指南。

推荐标准工作流

日常标准开发上手流程：

  1. 运行 griptape-nodes init 初始化本地工作区并配置基础密钥；
  2. 运行 griptape-nodes 拉起引擎与前端编辑器；
  3. 在弹出的浏览器图形界面中进行工作流搭建与自动化调度。