Welcome to Command ghostwriter

このアプリケーションは、IaCをはじめ自動化ツール導入が困難なインフラ運用現場において、CLIによる形式的な運用作業を効率化するソリューションです。

繰り返しが多くなりがちなCLI実行コマンドを、設定定義ファイル(csv/yaml/toml)とJinjaテンプレートファイルの2つに分けて記述することで、設定定義ファイルの変更のみでCLIコマンドが生成できます。また、コマンドに留まらず、Markdownによる作業手順書の生成にも対応しています。

目次

1. Quick Start
2. 使い方の流れ
3. テンプレート化の手順
4. 入力ファイルのフォーマット
5. 機能モード
6. デバッグ機能
7. ユースケース例
8. 制限事項と注意点
9. 高度な機能
10. 開発者向けドキュメント

Quick start

アプリを使う（インストール不要）

ブラウザで https://command-ghostwriter.vercel.app/ を開いてください。インストール不要でそのまま利用できます。

まずは「サンプルで試す」を選んでください。設定定義ファイルとJinjaテンプレートがエディタに読み込まれ、生成結果がライブプレビューに表示されます（生成ボタンの操作は不要で、編集に追従して自動生成されます）。「テンプレートライブラリ」から選ぶ、または自分の設定定義ファイルとJinjaテンプレートを読み込むこともできます。

ローカルで開発する

Web UI（React + Pyodide）をローカルで動かす場合:

git clone https://github.com/tvna/command-ghostwriter.git
cd command-ghostwriter
cd web
bun install
bun run dev   # Vite 開発サーバー (デフォルト: http://localhost:5173)

Pythonコア（features/ 配下）のテストを実行する場合:

uv sync
uv run pytest -k 'not e2e'

使い方の流れ

---
config:
  theme: neo-dark
  look: neo
---
sequenceDiagram
    participant senior as テンプレート<br>作成者
    participant colabolation as ファイル<br>サーバ
    participant junior as 利用者
    participant ghostwriter as Command<br>ghostwriter
    colabolation->>senior: 過去のコマンド履歴<br>または手順書を用意
    senior->>senior: 変数部分の特定と抽出
    senior->>colabolation: 設定定義ファイル<br>フォーマットの作成<br>(toml/yaml/csv)
    senior->>colabolation: Jinjaテンプレート作成
    senior->>colabolation: 利用時のルール整備
    junior-->>colabolation: 設定定義ファイル<br>フォーマットと<br>Jinjaテンプレートの取得
    junior->>junior: 設定定義ファイルに<br>シナリオに基づく<br>パラメーターを記入
    junior->>ghostwriter: 設定定義ファイルの<br>アップロード
    junior->>ghostwriter: Jinjaテンプレートの<br>アップロード
    ghostwriter-->>junior: 実行可能な<br>CLIコマンドを提供

Loading

テンプレート化の手順

既存のコマンドやMarkdownをテンプレート化する手順は以下の通りです：

1. 変数部分の特定

   # 変数化前のコマンド例
   ssh 192.168.1.101 "df -h"
   ssh 192.168.1.102 "df -h"

2. 設定定義ファイルの作成

   servers:
     - ip: 192.168.1.101
     - ip: 192.168.1.102
   commands:
     disk_check: df -h

3. Jinjaテンプレートの作成

   {% for server in servers %}
   ssh {{ server.ip }} "{{ commands.disk_check }}"
   {% endfor %}

4. 動作確認

   • Visual Debugモードで変数の展開を確認
   • エラーがある場合は設定定義ファイルまたはテンプレートを修正

入力ファイルのフォーマット

設定定義ファイル

設定定義ファイルは、CSV/YAML/TOMLのいずれかの形式で記述できます。これらのファイルには、コマンドやドキュメントの生成に必要な変数を定義します。

YAML形式の例

servers:
  - hostname: web01
    ip: 192.168.1.101
    role: web
  - hostname: db01
    ip: 192.168.1.102
    role: database
commands:
  check_disk: df -h
  check_memory: free -m

TOML形式の例

[servers.web01]
hostname = "web01"
ip = "192.168.1.101"
role = "web"

[servers.db01]
hostname = "db01"
ip = "192.168.1.102"
role = "database"

[commands]
check_disk = "df -h"
check_memory = "free -m"

CSV形式の例

hostname,ip,role,command
web01,192.168.1.101,web,df -h
db01,192.168.1.102,database,free -m

Jinjaテンプレートファイル

Jinjaテンプレートファイルは、設定定義ファイルの変数を参照してコマンドや文書を生成するためのテンプレートです。

コマンド生成用テンプレートの例

{% for server in servers %}
# {{ server.hostname }} ({{ server.role }})
ssh {{ server.ip }} "{{ commands.check_disk }}"
ssh {{ server.ip }} "{{ commands.check_memory }}"
{% endfor %}

Markdown生成用テンプレートの例

# サーバー監視手順書

{% for server in servers %}
## {{ server.hostname }}

### 基本情報
- ホスト名: {{ server.hostname }}
- IP アドレス: {{ server.ip }}
- 役割: {{ server.role }}

### CLIコマンド
{{ commands.check_disk }}
{{ commands.check_memory }}

{% endfor %}

機能モード

CLIコマンド生成モード

設定定義ファイルとJinjaテンプレートから、実行可能なCLIコマンドを生成します。

• 変数は {{ 変数名 }} の形式で参照
• 制御構文（for, if等）は {% %} で囲んで記述
• 生成されたコマンドはそのままコピー＆ペーストで実行可能

Markdown生成モード

設定定義ファイルとJinjaテンプレートから、Markdown形式の文書を生成します。

• 標準的なMarkdown記法をサポート
• コードブロックの言語指定が可能
• テーブル形式での出力に対応
• 画像の参照にも対応

デバッグ機能

Visual Debug

テンプレートの解析結果を視覚的に確認できます。

• 変数の展開結果の確認
• テンプレート構文のエラーチェック
• 制御構文の実行フローの確認

TOML/YAML Debug

設定定義ファイルの解析結果を確認できます。

• パース結果の構造化表示
• データ型の確認
• 構文エラーの詳細表示

ユースケース例

PowerShellコマンド生成

{% for service in services %}
Get-Service -Name "{{ service.name }}" | Select-Object Name, Status
{% endfor %}

Linuxコマンド生成

{% for file in backup_files %}
tar -czf {{ file.name }}.tar.gz {{ file.path }}
{% endfor %}

制限事項と注意点

入力ファイル

• ファイルサイズ: 最大30MB
• 文字エンコーディング: UTF-8,Shift_JIS,EUC-JPのみテスト済み
• 改行コード: LF/CRLF両対応

セキュリティ

• 生成されたコマンドは実行前に必ず内容を確認してください

既知の制限事項

• 一部の特殊文字はエスケープが必要
• テンプレートにおけるネストされたループは非推奨

高度な機能

カスタムテンプレート

独自のテンプレートを作成して利用できます。

• Jinjaの標準フィルターをサポート
• カスタムフィルターの追加も可能
• 複数テンプレートの組み合わせに対応

開発者向けドキュメント

開発に必要なコマンド集はこちらを参照してください。

Dev Containers (エージェント開発環境)

Claude / Codex の各エージェント向けに、ツールチェーンを nix flake で固定した build-on-open 方式の開発コンテナを用意しています。

• VS Code の「Dev Containers: Reopen in Container」で、.devcontainer/claude（Claude 用）または .devcontainer/codex（Codex 用）を選択して起動します。
• 初回起動時はベースイメージへの nix 導入とツールチェーンのビルドが走るため、起動完了まで時間がかかります。
• Web UI は自動起動しません。コンテナ内で cd web && bun run dev を実行し、フォワードされた Vite ポート（デフォルト: 5173）で確認してください。