knock-cli

Knock CLI スキル

このスキルでは、Knock CLI を使用してワークフロー、テンプレート、その他の通知リソースを管理するための包括的なガイドラインを紹介します。

概要

Knock CLI スキルには、次の項目を網羅した詳細なルールセットが含まれています。

1. CLI のインストールと認証 - Knock CLI のインストール方法と認証方法
2. Knock のディレクトリ構造 - knock ディレクトリの構成と設定について
3. CLI コマンドリファレンス - pull、push、リソース管理の各コマンド
4. ワークフローテンプレート - ワークフローとテンプレートの構造、パターン、ベストプラクティス
5. ガイドとメッセージタイプ - ライフサイクルメッセージ用のアプリ内ガイドと、そのスキーマとしてのメッセージタイプについて
6. パーシャル - メールデザインシステムで再利用できるテンプレートの構成要素

このスキルの使い方

初期設定の場合

Knock を使用して新しいプロジェクトを設定する場合：

1. まずインストールと認証を行います（rules/cli-installation-authentication.md）

   • CLI がインストールされていることを確認します
   • サービストークンまたはダッシュボードアカウントで認証します
   • knock init でプロジェクトを初期化します

2. ディレクトリ構造を理解します（rules/knock-directory-structure.md）

   • knock.json の設定について確認します
   • リソースの構成を理解します

リソースを管理する場合

Knock のリソースを操作する場合：

1. CLI コマンドリファレンスを使用します（rules/cli-commands-reference.md）

   • Knock からリソースをローカルプロジェクトに pull します
   • 変更を Knock に push します
   • 特定のリソースタイプを操作します

2. ワークフローとテンプレートのガイドラインに従います（rules/workflow-templates.md）

   • テンプレートのモードと構造を理解します
   • ファイルパスや変数に関するよくある間違いを避けます
   • ワークフローを変更する際のベストプラクティスに従います

ガイドとメッセージタイプを管理する場合

アプリ内ガイド（バナー、モーダル、お知らせ）を操作する場合：

1. まずガイドとメッセージタイプについて確認します（rules/guides-and-message-types.md）

   • ガイドはワークフローとは別のものであることを理解します（ライフサイクルメッセージと通知の違い）
   • メッセージタイプがスキーマを定義し、ガイドは schema_key と schema_variant_key を介して参照します
   • 可能な場合は組み込みタイプ（banner、modal、card）を使用し、必要に応じてカスタムメッセージタイプを作成します

2. 作成する前に確認します

   • knock message-type list を実行して、利用可能なメッセージタイプのキーを確認します
   • knock guide list を実行して、既存のガイドを確認します
   • 新しいガイドを作成する際は、出力されたキーをそのまま使用します

パーシャルを使用する場合

再利用可能なメールコンポーネント（コールアウト、引用ブロック、コメントカード）を作成する場合：

1. まずパーシャルについて確認します（rules/partials.md）

   • パーシャルファイルの構造と partial.json のスキーマを理解します
   • ブロックエディターのフィールドに input_schema を定義します（メッセージタイプのバリアントフィールドと同じ形式）
   • メールのビジュアルブロックエディターに表示するパーシャルには visual_block_enabled: true を使用します

2. 作成して push します

   • knock partial new -k <key> -n "Name" -t html --force を実行してひな形を作成します
   • input_schema を追加してコンテンツを編集し、knock partial push <key> で検証して push します

ワークフローとテンプレートを変更する場合

ワークフローやテンプレートに変更を加える場合：

1. 書き換える前に必ず読みます - 変更前に既存の構造を理解します
2. 新しいメールではビジュアルブロックを使用します - ビジュアルブロックモードを常にデフォルトとし、明示的に求められた場合のみ HTML モードを使用します
3. 正しい変数名前空間を使用します - トリガーペイロードには data、環境変数には vars を使用します
4. ファイルパスの参照を確認します - パスは参照元のファイルからの相対パスです
5. 変更後に push します - ローカルファイルの変更は、push するまで Knock に同期されません。変更を反映するには、knock workflow push <key>（または他のリソースタイプに対応するコマンド）を実行します。

ルールファイルのリファレンス

• rules/cli-installation-authentication.md - インストールと認証の設定
• rules/knock-directory-structure.md - ディレクトリ構造と設定
• rules/cli-commands-reference.md - リソース管理用の CLI コマンド
• rules/workflow-templates.md - ワークフローとテンプレートの構造およびベストプラクティス
• rules/guides-and-message-types.md - ライフサイクルメッセージ用のガイドとメッセージタイプ
• rules/partials.md - パーシャルと再利用可能なテンプレート構成要素

クイックリファレンス

よく使うコマンド

# Initialize a new project (interactive; prompts for the resources directory)
knock init

# Pull all resources from Knock (--force skips confirmation prompts)
knock pull --force

# Pull a specific workflow
knock workflow pull <workflow-key> --force

# Push all resources to Knock (push never prompts)
knock push

# Push a specific workflow
knock workflow push <workflow-key>

# Push a specific email layout
knock layout push <layout-key>

# List channels (discover valid channel_key values before creating workflows)
knock channel list

# Guide and message type commands
knock message-type list          # Discover message type keys before creating guides
knock guide list                 # List existing guides
knock guide push <guide-key>     # Push a guide after modifying
knock message-type push <key>    # Push a message type after modifying

# Partial commands (email design system building blocks)
knock partial list               # List existing partials
knock partial new -k <key> -n "Name" -t html --force   # Create a new partial
knock partial pull <key> --force # Pull a partial from Knock
knock partial push <key>         # Push a partial after modifying
knock partial validate <key>     # Validate a partial locally

# Commit and promote a specific resource only (safe when other resources have pending changes)
knock commit -m "message" --resource-type=workflow --resource-id=<key> --force
knock commit list --resource-type=workflow --resource-id=<key>   # get the commit ID
knock commit promote --only=<commit-id> --force

主な概念

• knockDir：Knock リソースを保存するディレクトリ（knock.json で設定）
• リソースタイプ：workflows、layouts、guides、message-types、translations、partials、audiences、schemas
• ガイドとワークフローの違い：ガイドはライフサイクルメッセージ（バナー、モーダル）用で、ワークフローは通知用です
• テンプレートモード：ビジュアルブロック（新規メールのデフォルト）と HTML（明示的に要求された場合のみ）
• 変数の名前空間：data（トリガーペイロード）、vars（環境変数）、recipient、actor、tenant

重要なパターン

1. プロンプトが表示されるコマンドでは --force を使用する - 多くの CLI コマンド（pull、commit、promote、activate）では、対話型の確認プロンプトが表示されます。自動化またはエージェントのコンテキストでは、必ず --force を渡してプロンプトをスキップしてください。
2. 変更のたびにプッシュする - ローカルでの編集は、プッシュするまでローカルにとどまります。プッシュしないと、Knock に変更が反映されません。
3. ファイルパスの参照には @ サフィックスを使用する：「"content@": "visual_blocks/1.content.md"」
4. パスは格納先ファイルからの相対パスです - ステップのディレクトリを重複させないでください
5. トリガーペイロードの値には必ず data. を使用し、vars. は使用しない
6. 構造を維持するため、変更前に既存のファイルを読む
7. ワークフローの作成前にチャネルキーを確認する - knock channel list を実行して、有効な channel_key の値を確認します
8. ガイドの作成前にメッセージタイプのキーを確認する - knock message-type list を実行して、有効なメッセージタイプのキーを確認します
9. 単一のリソースを扱う場合は、コミットとプロモートの対象を絞る - knock commit promote --to=<env> は、すべてのリソースにわたる未プロモートのコミットをすべてプロモートします。単一のリソースを扱う場合は、--resource-type と --resource-id を使ってそのリソースだけをコミットし、続いて knock commit promote --only=<commit-id> を使ってそのコミットだけをプロモートしてください。以下の「特定のリソースのみをプロモートする」ワークフローを参照してください。

ベストプラクティスのまとめ

1. 編集前にプルする - 変更を加える前に最新の変更を同期します
2. 変更後にプッシュする - 明示的にプッシュするまで、ローカルの変更は Knock に反映されません
3. 書き込む前に読む - データの損失を避けるため、既存の構造を把握します
4. 適切な名前空間を使用する - 動的なペイロードには data、環境定数には vars を使用します
5. デフォルトではビジュアルブロックを使用する - 新規メールではビジュアルブロックを使用し、編集時には既存のモードを維持します
6. パスを確認する - ファイル参照は格納先ファイルからの相対パスです
7. 変更をテストする - 変更をプッシュした後、ワークフローを検証します
8. コミットとプロモートの対象を絞る - 単一のリソースを扱う場合は、コミットでは --resource-type／--resource-id、プロモートでは --only をデフォルトで使用します。すべてのリソースにわたる保留中の変更をすべてプロモートする場合に限り、knock commit promote --to=<env> を使用してください。