knock-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Knock CLI skill

Knock CLI 技能指南

This skill provides comprehensive guidelines for working with the Knock CLI to manage workflows, templates, and other notification resources.

本技能文档提供了使用Knock CLI管理工作流、模板及其他通知资源的全面指南。

Overview

概述

The Knock CLI skill includes detailed rule sets covering:

CLI installation and authentication - How to install and authenticate with the Knock CLI
Knock directory structure - Understanding the knock directory layout and configuration
CLI commands reference - Pull, push, and resource management commands
Workflow templates - Structures, patterns, and best practices for workflows and templates
Guides and message types - Working with in-app guides for lifecycle messaging and message types as their schema
Partials - Reusable template building blocks for email design systems

Knock CLI技能文档包含以下详细规则集：

CLI安装与身份验证 - 如何安装Knock CLI并完成身份验证
Knock目录结构 - 了解Knock目录布局与配置
CLI命令参考 - 拉取、推送及资源管理命令
工作流模板 - 工作流与模板的结构、模式及最佳实践
引导与消息类型 - 使用应用内引导实现生命周期消息传递，以及作为其 schema 的消息类型
局部组件（Partials） - 用于邮件设计系统的可复用模板构建块

How to use this skill

如何使用本技能文档

For initial setup

初始设置

When setting up a new project with Knock:

Start with installation and authentication (
```
rules/cli-installation-authentication.md
```
)
- Verify the CLI is installed
- Authenticate with a service token or dashboard account
- Initialize the project with
```
knock init
```
Understand the directory structure (
```
rules/knock-directory-structure.md
```
)
- Learn the knock.json configuration
- Understand resource organization

在使用Knock搭建新项目时：

从安装与身份验证开始（
```
rules/cli-installation-authentication.md
```
）
- 验证CLI是否已安装
- 使用服务令牌或控制台账户完成身份验证
- 执行
```
knock init
```
  初始化项目
了解目录结构（
```
rules/knock-directory-structure.md
```
）
- 学习knock.json配置文件
- 理解资源组织方式

For managing resources

资源管理

When working with Knock resources:

Use the CLI commands reference (
```
rules/cli-commands-reference.md
```
)
- Pull resources from Knock to your local project
- Push changes back to Knock
- Work with specific resource types
Follow workflow and template guidelines (
```
rules/workflow-templates.md
```
)
- Understand template modes and structures
- Avoid common mistakes with file paths and variables
- Follow best practices for workflow modifications

在操作Knock资源时：

参考CLI命令文档（
```
rules/cli-commands-reference.md
```
）
- 将Knock上的资源拉取到本地项目
- 将本地变更推送到Knock
- 操作特定类型的资源
遵循工作流与模板指南（
```
rules/workflow-templates.md
```
）
- 理解模板模式与结构
- 避免文件路径和变量相关的常见错误
- 遵循工作流修改的最佳实践

For managing guides and message types

引导与消息类型管理

When working with in-app guides (banners, modals, announcements):

Start with guides and message types (
```
rules/guides-and-message-types.md
```
)
- Understand that guides are separate from workflows (lifecycle messaging vs notifications)
- Message types define the schema; guides reference them via
```
schema_key
```
  and
```
schema_variant_key
```
- Use built-in types (banner, modal, card) when possible; create custom message types when needed
Discover before creating
- Run
```
knock message-type list
```
  to see available message type keys
- Run
```
knock guide list
```
  to see existing guides
- Use exact keys from output when creating new guides

在使用应用内引导（横幅、弹窗、公告）时：

从引导与消息类型开始（
```
rules/guides-and-message-types.md
```
）
- 理解引导与工作流的区别（生命周期消息传递 vs 通知）
- 消息类型定义schema；引导通过
```
schema_key
```
  和
```
schema_variant_key
```
  引用它们
- 尽可能使用内置类型（横幅、弹窗、卡片）；必要时创建自定义消息类型
先查询再创建
- 执行
```
knock message-type list
```
  查看可用的消息类型键
- 执行
```
knock guide list
```
  查看现有引导
- 创建新引导时使用输出中的精确键值

For working with partials

局部组件（Partials）使用

When building reusable email components (callouts, quote blocks, comment cards):

Start with partials (
```
rules/partials.md
```
)
- Understand partial file structure and
```
partial.json
```
  schema
- Define
```
input_schema
```
  for block editor fields (same format as message type variant fields)
- Use
```
visual_block_enabled: true
```
  for partials that appear in the email visual block editor

Create and push

Run

knock partial new -k <key> -n "Name" -t html --force

to scaffold

Add
```
input_schema
```
and edit content; validate and push with
```
knock partial push <key>
```

在构建可复用邮件组件（提示框、引用块、评论卡片）时：

从局部组件开始（
```
rules/partials.md
```
）
- 理解局部组件的文件结构与
```
partial.json
```
  schema
- 为区块编辑器字段定义
```
input_schema
```
  （格式与消息类型变体字段一致）
- 对要在邮件可视化区块编辑器中显示的局部组件设置
```
visual_block_enabled: true
```

创建与推送

执行

knock partial new -k <key> -n "Name" -t html --force

生成脚手架

添加
```
input_schema
```
并编辑内容；验证后执行
```
knock partial push <key>
```
推送

For modifying workflows and templates

工作流与模板修改

When making changes to workflows or templates:

Always read before writing - Understand existing structure before modifying
Use visual blocks for new emails - Always default to visual blocks mode; only use HTML mode if explicitly requested
Use correct variable namespaces -
```
data
```
for trigger payload,
```
vars
```
for environment variables
Verify file path references - Paths are relative to the file containing the reference
Push after modifying - Local file changes are not synced to Knock until you push. Run
```
knock workflow push <key>
```
(or the equivalent for other resource types) for changes to take effect.

在修改工作流或模板时：

先阅读再修改 - 修改前先理解现有结构
新邮件使用可视化区块 - 始终默认使用可视化区块模式；仅在明确要求时使用HTML模式
使用正确的变量命名空间 -
```
data
```
用于触发负载，
```
vars
```
用于环境变量
验证文件路径引用 - 路径是相对于包含引用的文件的相对路径
修改后推送 - 本地文件变更不会自动同步到Knock，需手动推送。执行
```
knock workflow push <workflow-key>
```
（或其他资源类型的对应命令）使变更生效。

Rule files reference

规则文件参考

rules/cli-installation-authentication.md

- Installation and authentication setup

```
rules/knock-directory-structure.md
```
- Directory structure and configuration
```
rules/cli-commands-reference.md
```
- CLI commands for resource management
```
rules/workflow-templates.md
```
- Workflow and template structures and best practices
```
rules/guides-and-message-types.md
```
- Guides and message types for lifecycle messaging
```
rules/partials.md
```
- Partials and reusable template building blocks

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
```
- 局部组件与可复用模板构建块

Quick reference

快速参考

Common commands

常用命令

bash

undefined

bash

undefined

Initialize a new project (interactive; use --knock-dir to skip prompts)

初始化新项目（交互式；使用--knock-dir跳过提示）

knock init --knock-dir=./knock

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

从Knock拉取所有资源（--force跳过确认提示）

knock pull --all --force

Pull a specific workflow

拉取特定工作流

knock workflow pull <workflow-key> --force

Push all resources to Knock (push never prompts)

推送所有资源到Knock（推送操作不会弹出提示）

knock push --all

Push a specific workflow

推送特定工作流

knock workflow push <workflow-key>

Push a specific email layout

推送特定邮件布局

knock email-layout push <layout-key>

List channels (discover valid channel_key values before creating workflows)

列出渠道（创建工作流前查询有效的channel_key值）

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

knock message-type list # 创建引导前查询消息类型键 knock guide list # 列出现有引导 knock guide push <guide-key> # 修改后推送引导 knock message-type push <key> # 修改后推送消息类型

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

undefined

knock partial list # 列出现有局部组件 knock partial new -k <key> -n "Name" -t html --force # 创建新局部组件 knock partial pull <key> --force # 从Knock拉取局部组件 knock partial push <key> # 修改后推送局部组件 knock partial validate <key> # 本地验证局部组件

undefined

Key concepts

核心概念

knockDir: The directory where Knock resources are stored (configured in knock.json)
Resource types: workflows, email-layouts, guides, message-types, translations, partials, commits
Guides vs workflows: Guides are for lifecycle messaging (banners, modals); workflows are for notifications
Template modes: Visual blocks (default for new emails) vs HTML (only when explicitly requested)
Variable namespaces:
```
data
```
(trigger payload),
```
vars
```
(environment variables),
```
recipient
```
,
```
actor
```
,
```
tenant
```

knockDir: 存储Knock资源的目录（在knock.json中配置）
资源类型: workflows（工作流）、email-layouts（邮件布局）、guides（引导）、message-types（消息类型）、translations（翻译）、partials（局部组件）、commits（提交）
引导 vs 工作流: 引导用于生命周期消息传递（横幅、弹窗）；工作流用于通知
模板模式: 可视化区块（新邮件默认模式） vs HTML（仅在明确要求时使用）
变量命名空间:
```
data
```
（触发负载）、
```
vars
```
（环境变量）、
```
recipient
```
（接收者）、
```
actor
```
（操作者）、
```
tenant
```
（租户）

Important patterns

重要模式

Use
--force
on commands with prompts - Many CLI commands (pull, commit, promote, activate) display interactive confirmation prompts. Always pass
```
--force
```
to skip them in automated/agent contexts.
Push after every change - Local edits stay local until pushed. No push = no update in Knock.

File path references use
@
suffix:

"content@": "visual_blocks/1.content.md"

Paths are relative to containing file: Don't double the step directory
Always use
data.
for trigger payload values, not
```
vars.
```
Read existing files before modifying to preserve structure
Discover channel keys before creating workflows - Run
```
knock channel list
```
to get valid
```
channel_key
```
values
Discover message type keys before creating guides - Run
```
knock message-type list
```
to get valid message type keys

带提示的命令使用
--force
- 许多CLI命令（拉取、提交、升级、激活）会显示交互式确认提示。在自动化/代理环境中，始终添加
```
--force
```
跳过提示。
每次修改后推送 - 本地编辑仅保存在本地，需推送后才会同步到Knock。不推送则Knock不会更新。

文件路径引用使用
@
后缀:

"content@": "visual_blocks/1.content.md"

路径是相对于当前文件的相对路径: 不要重复步骤目录
触发负载值始终使用
data.
前缀，而非
```
vars.
```
修改前先阅读现有文件以保留结构
创建工作流前查询渠道键 - 执行
```
knock channel list
```
获取有效的
```
channel_key
```
值
创建引导前查询消息类型键 - 执行
```
knock message-type list
```
获取有效的消息类型键

Best practices summary

最佳实践总结

Pull before editing - Sync latest changes before making modifications
Push after modifying - Local changes are not persisted to Knock until explicitly pushed
Read before writing - Understand existing structure to avoid data loss
Use correct namespaces -
```
data
```
for dynamic payload,
```
vars
```
for environment constants
Visual blocks by default - Use visual blocks for new emails; preserve existing mode when editing
Verify paths - File references are relative to the containing file
Test changes - Validate workflows after pushing changes

编辑前拉取 - 修改前同步最新变更
修改后推送 - 本地变更需显式推送才会在Knock中持久化
先阅读再修改 - 理解现有结构以避免数据丢失
使用正确的命名空间 -
```
data
```
用于动态负载，
```
vars
```
用于环境常量
默认使用可视化区块 - 新邮件使用可视化区块；编辑时保留原有模式
验证路径 - 文件引用是相对于当前文件的相对路径
测试变更 - 推送后验证工作流