Knock CLI skill

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

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

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

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

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

For working with 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>
```

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.

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

Quick reference

Common commands

bash

# Initialize a new project (interactive; use --knock-dir to skip prompts)
knock init --knock-dir=./knock

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

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

# Push all resources to Knock (push never prompts)
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)
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

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
```

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

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-cli

NPX Install

Tags

SKILL.md Content