コンテンツにスキップ

Griptape Nodes コマンドラインインターフェース (CLI)

コマンドラインインターフェース（CLI: Command Line Interface）は、グラフィカルな UI ボタンをクリックする代わりに、ターミナル上でテキストコマンドを入力してソフトウェアを操作する仕組みです。Griptape Nodes は griptape-nodes（またはその短縮エイリアス gtn）コマンドによる CLI を提供しており、ターミナルから Griptape Nodes を直接制御・管理できます。

griptape-nodes（または gtn）は、お使いのコンピュータ上で Griptape Nodes Engine のインストール環境を起動・管理するために特別に設計されたコマンドラインツールです。このツールは、ワークスペースの初期化、設定パラメータの管理、Web ベースの Griptape Nodes エディタを支えるエンジンの起動などを処理します。実際のワークフローの作成や編集は、エンジン起動時に開く Web/デスクトップインターフェース上で行われます。

基本的な使い方 (Basic Usage)

griptape-nodes [options] [COMMAND]

コマンドを省略した場合、デフォルトで engine コマンドが実行されます。

利用可能なコマンド (Commands)

engine（デフォルトコマンド）

Griptape Nodes エンジンを起動します。

griptape-nodes engine

これにより Griptape Nodes エンジンが起動し、Web インターフェース（https://nodes.griptape.ai）が開きます。

init

Griptape Nodes の新しいワークスペースを初期化します：API キー、ワークスペースディレクトリ、ストレージバックエンド、および追加ライブラリ（任意）を設定します。再度実行すると同じ対話型プロンプトが表示され、後からいつでも設定値を変更できます。

griptape-nodes init [options]

主なオプション：

  • --api-key - プロンプトを表示せず、直接 Griptape API キーを指定
  • --workspace-directory - プロンプトを表示せず、直接ワークスペースディレクトリを指定
  • --storage-backend - プロンプトを表示せず、ストレージバックエンド（local または gtc）を設定
  • --bucket-name - --storage-backend gtc 指定時に使用するバケット名（既存または新規）
  • --register-diffusers-library / --no-register-diffusers-library - Griptape Nodes Diffusers Library をインストール（またはスキップ）
  • --register-griptape-cloud-library / --no-register-griptape-cloud-library - Griptape Cloud Library をインストール（またはスキップ）
  • --no-interactive - 対話型プロンプトをスキップし、指定されたフラグとデフォルト値のみで初期化を実行
  • --hf-token - ゲート付きモデルのダウンロードに使用する Hugging Face トークンを設定
  • --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 - 設定をデフォルト値にリセットします。

この方法で読み取りまたは設定できる全パラメータの一覧については、設定リファレンス (Configuration Reference) を参照してください。

self

CLI 自体のインストール状態を管理します。

griptape-nodes self SUBCOMMAND

サブコマンド：

  • uninstall - CLI をアンインストールし、設定ディレクトリ、データディレクトリ、およびインストールされた実行可能ファイルを削除します。
  • version - CLI の現在のバージョンを表示します。
  • info - デバッグ用のシステム情報レポートを出力します：エンジンのバージョンとインストール元、プラットフォームと Python の詳細、設定ファイルのパス、各レイヤーのファイルとパースエラーを含む設定レイヤースタック、有効な設定値、設定されている API キー、登録されているすべてのライブラリとそのバージョン、およびプロジェクトテンプレート。バグレポートにそのまま貼り付けられるよう安全に設計されています — API キーや認証情報は削除され、ホームディレクトリは ~ に、ユーザー名は <user> にマスキングされます。末尾には削除・マスキングされた項目数が表示されるため、空の設定値と非表示にされた設定値を判別できます。
    • env レイヤーと runtime レイヤーは専用のファイルを持ちません：env は設定されている GTN_CONFIG_* 変数の名前を一覧表示し（マージされた設定で解決後の値が確認できるため値は省略）、runtime はアクティブなプロジェクトによって固定されたワークスペースディレクトリを表示します。
    • --show-identity - ~ や <user> に置き換えずに、実際のホームディレクトリパスとユーザー名をそのまま出力します（認証情報は引き続き削除されます）。
    • 同じシステム情報とログを共有可能な 1 つのファイルとして収集するには、diagnostics collect を使用してください。

libraries

ローカルライブラリを管理します。ライブラリのインストールと管理に関する完全なガイドについては、ライブラリ (Libraries) を参照してください。

griptape-nodes libraries SUBCOMMAND

サブコマンド：

  • sync - 登録されているすべてのライブラリを最新バージョンに更新します。
    • --overwrite - 更新前にライブラリのクローン内のコミットされていないローカル変更を破棄します。
  • download <git_url> - Git からライブラリをクローンして登録します。
    • --branch - チェックアウトするブランチ、タグ、またはコミット。
    • --target-dir - クローン先のディレクトリ名。
    • --download-dir - ライブラリがクローンされる親ディレクトリ。
    • --overwrite - ディレクトリが既に存在する場合に上書きします。

models

Hugging Face Hub からダウンロードされた AI モデルを管理します — ワークフロー実行時にローカル拡散モデルや 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> - モデルのダウンロード進捗追跡レコードを削除します（モデルファイル自体は削除されません。ファイルの削除には models delete を使用してください）。

doctor

Griptape Nodes のインストール環境を診断し、検出結果のテーブルと修正が必要な場合の対処法を出力します。

griptape-nodes doctor

各診断項目は PASS（合格）、WARN（警告: 現在は動くが後で問題になる可能性がある）、または FAIL（失敗: 現在破損している）として返されます。診断対象：

  • Workspace - ワークスペースディレクトリが存在し、書き込み権限があるか
  • Disk Space - ワークスペースのドライブにワークフローの保存やライブラリのインストールに十分な空き容量があるか
  • Libraries - 登録されているすべてのライブラリが正常に読み込まれ、欠落しているノードがないか
  • Secrets - ライブラリが必要とするすべての API キーに値が設定されているか
  • Log Capture - 後から収集できるようにエンジンログが正しく書き出されているか
  • Cloud Connection - エディタがエンジンと通信するために必要な Griptape Cloud へのネットワーク疎通が可能か

いずれかのチェックが 失敗（FAIL） した場合、終了ステータスが 0 以外（非ゼロ）で終了するため、自動化スクリプト内でも安全に利用できます。単なる警告（WARN）のみの場合は終了ステータス 0 で終了します。

同じ診断結果は診断バンドル内の doctor.json にも保存されるため、バグレポートを受け取った開発者も全く同じ診断結果を確認できます。

diagnostics

このインストールのトラブルシューティングに必要なすべての情報を、バグレポートに添付できる 1 つの ZIP ファイルに収集します。

griptape-nodes diagnostics SUBCOMMAND

サブコマンド：

  • collect - 診断バンドルを作成します：ログファイル、有効な設定値、すべてのライブラリとプロジェクトの読み込み状態、および doctor による健全性チェック結果。
    • --output, -o - バンドルの出力先。ディレクトリを指定した場合は自動生成されたファイル名が使用されます（デフォルトはカレントディレクトリ）。
    • --skip-logs - エンジンのログファイルをバンドルから除外します。
    • --skip-libraries - 事前のライブラリ読み込みをスキップします（高速化されますが、どのライブラリが読み込みに失敗したかの情報は含まれなくなります）。
    • --show-identity - ~ や <user> に置き換えずに、実際のホームディレクトリパスとユーザー名をそのまま含めます。

収集されたデータが外部に自動アップロードされることは一切ありません。ファイルはローカルマシンにのみ書き出され、共有するかどうかは完全にユーザーの判断に委ねられます。

バンドルはエンジン自体によって生成され、エンジンは自身の API キーを認識しているため、収集するすべてのファイルから API キーやその他の認証情報に類似する文字列を検知して自動的にマスキング・削除します。バンドル内の manifest.json にはマスキングされた全件数が記録され、README.md には各ファイルの内容が平易な言葉で説明されています。

エディタやデスクトップアプリでの同等の機能については、エンジンログのエクスポート を参照してください。

設定ファイルの保存場所 (Configuration)

Griptape Nodes は設定を以下の場所に保存します：

  • 設定ディレクトリ: ~/.config/griptape_nodes（macOS/Linux）または %USERPROFILE%\.config\griptape_nodes（Windows）
  • データディレクトリ: ~/.local/share/griptape_nodes（macOS/Linux）または %USERPROFILE%\.local\share\griptape_nodes（Windows）
  • 設定ファイル: 設定ディレクトリ内の griptape_nodes_config.json
  • 環境変数ファイル: 設定ディレクトリ内の .env

Griptape Nodes Desktop は、手動インストールされたエンジンと競合しないよう、これら 2 つのディレクトリを独自のアプリケーションデータフォルダ内に保持します。それらのパスについては Griptape Nodes のアンインストール を参照してください。

一般的なワークフロー (Workflow)

標準的な利用の流れ：

  1. griptape-nodes init を実行して、ワークスペースと API キーを設定します。
  2. griptape-nodes を実行してエンジンを起動します。
  3. 開いた Web/デスクトップインターフェースを使用して、ワークフローを作成・管理します。