CLI reference

This reference documents every command and flag available in Knock's command-line interface.

The Knock CLI helps you work with your Knock resources right from the terminal.

With the CLI, you can:

• Work with your Knock workflows and notification templates locally.
• Integrate Knock into your CI/CD environment to automatically promote changes.
• Map your translation files into Knock to localize your notifications.

Install with Homebrew

For macOS, you can install the Knock CLI using Homebrew. Once the CLI is installed you can call it by using the knock command in your terminal.

Install with npm

For other operating systems, you can install the Knock CLI using npm, a node package manager. Once the CLI is installed, you can call it by using the knock command in your terminal.

Requirements

The Knock CLI is built with Node.js and installable as a npm package. You must have node and npm installed already, with the following versions:

• Node.js: 16.14.0 or higher
• NPM: 7.18.1 or higher

You can find the Knock CLI npm package here.

Using your Knock account

You can authenticate your Knock account against the CLI by running knock login. This will open a browser window where you can sign in to your Knock account and authorize the CLI to access your account.

Once authenticated, you can verify it works by running knock whoami. If your account is valid and configured properly, you'll receive a 200 response that shows the account name and your user ID.

If you need to switch between accounts, you can run knock logout to log out of your current account and log in to a different one.

Using a service token

If you need to authenticate in a remote environment, or want complete control, you can generate a service token in the Knock dashboard. You can specify a service token in all CLI calls, or you can optionally use a configuration file to authenticate all requests.

Once you have generated a service token, you can verify it works by running knock whoami --service-token=YOUR_SERVICE_TOKEN. If your token is valid and configured properly, you'll receive a 200 response that shows the account name and the service token name.

Setting up a configuration file (optional)

A service token is required by the CLI for most commands. For convenience, Knock CLI supports a user configuration file, where you can store the service token for the CLI to read automatically rather than having to manually pass in with --service-token flag for every command.

To set up a user configuration file, create a config.json file in the Knock CLI's config directory at ~/.config/knock (macOS/Unix) or %LOCALAPPDATA%\knock (Windows), and add the following json:

When Knock CLI detects a user configuration file, it will use the service token provided in it automatically.

The following flags are supported for every command.

Flags

There is no required directory structure when working with Knock resources locally. However, if you use the knock pull or knock push commands, they will produce and expect the directory structure outlined below.

For forward compatibility, we recommend using this structure to ensure your local files work seamlessly with future CLI updates.

When you use knock pull --knock-dir=./knock, resources will be grouped by resource type within subdirectories. The following directory structure will be created:

./knock/
├── guides/
├── layouts/
├── message-types/
├── partials/
├── translations/
└── workflows/

Each resource type has its own directory structure, which is described in detail in the sections below for each resource type.

You can log in to your Knock account with the login command. This will open a browser window where you can sign in to your Knock account and authorize the CLI to access your account.

You can log out of your Knock account with the logout command. This will clear the authentication token for the CLI.

Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, and message-types) from Knock into your local file system.

Resources will be grouped by resource type within subdirectories of the target directory path set by the --knock-dir flag. See the Directory structure section for details on the directory structure used by push and pull commands.

Flags

Pushes all local resource files (workflows, partials, email layouts, and translations) back to Knock and upserts them. This command expects the directory structure to be the same as the one created by the knock pull command.

Flags

When workflows are pulled from Knock, they are stored in directories named by their workflow key. In addition to a workflow.json file that describes all of a given workflow's steps, each workflow directory also contains individual folders for each of the channel steps in the workflow that hold additional content and formatting data.

workflows/
└── my-workflow/
    ├── email_1/
    │   ├── visual_blocks/
    │   │   └── 1.content.md
    │   └── visual_blocks.json
    ├── in_app_feed_1/
    │   └── markdown_body.md
    └── workflow.json

If you're migrating your local workflow files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using knock workflow push --all. Each workflow.json file should follow the structure defined here.

You can see all your existing workflows in a given environment with the workflow list command.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can show more details about a given workflow with the workflow get command, followed by the target workflow key.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can pull and download workflows with its message templates from Knock to a local file system with the workflow pull command. Knock CLI will create a new workflow directory or update the existing workflow directory in the local file system.

Note: if pulling the target workflow for the first time (or all workflows), Knock CLI will ask to confirm before writing to the local file system.

See the Workflow file structure section for details on how workflow files are organized.

Flags

You can push and upload a workflow directory to Knock with the workflow push command. Knock will update an existing workflow by the matching workflow key, or create a new workflow if it does not exist yet.

Note:

• The workflow push command only pushes workflows into the development environment.
• You must be directly above the target workflow directory when running the workflow push command, so the CLI can locate the workflow.json file.
• You can also pass in the --commit flag (with an optional --commit-message flag) to commit the upserted changes immediately.

See the Workflow file structure section for details on how workflow files are organized.

Flags

You can run a workflow with the workflow run command. Knock will execute a run for the latest saved version of the workflow it finds with the given key and parameters you send it.

Note:

• Changes to the local version of the workflow in your file system will not be reflected in a workflow run; it will use the current version that is stored in Knock.

Flags

You can validate a new or updated workflow directory with the workflow validate command. Knock will validate the given workflow payload in the same way as it would with the workflow push command, except without persisting those changes.

Note: Validating a workflow is only done against the development environment.

Flags

You can activate or deactivate a workflow in a given environment with the workflow activate command.

Note:

• This immediately enables or disables a workflow in a given environment without needing to go through environment promotion.
• By default, this command activates a given workflow. Pass in the --status flag with false in order to deactivate it.

Flags

Generate type definitions for workflow trigger data from your workflow schemas. This command fetches workflows with trigger data schemas and generates type-safe definitions for TypeScript, Python, Ruby, and Go.

The generated types enable compile-time safety when triggering workflows in your application code, helping catch integration errors before runtime. The target language is inferred from the output file extension.

Learn more about type safety with workflows.

Flags

When email layouts are pulled from Knock, they are stored in directories named by their layout key.

layouts/
├── default/
│   ├── html_layout.html
│   ├── layout.json
│   └── text_layout.txt
└── custom-layout/
    ├── html_layout.html
    ├── layout.json
    └── text_layout.txt

If you're migrating your local layout files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using knock layout push --all. Each layout.json file should follow the example shown below; additional information on the Layout structure is defined here.

List all email layouts in the environment. Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

Fetches a single email layout, using the key of the email layout.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

Pulls the contents of one or all email layouts from Knock into your local file system. Using <layout_key> you can pull a single email layout specified by the key, or use the --all flag to pull all email layouts from Knock at once.

See the Layout file structure section for details on how layout files are organized.

Flags

Pushes local email layouts back to Knock and upserts them. Using <layout_key> you can push a single email layout specified by the key, or use the --all flag to push all email layouts from Knock at once.

See the Layout file structure section for details on how layout files are organized.

Flags

Validates one or more email layouts. Useful for checking if the layout is valid before running the email_layout push command.

The <layout_key> can be provided to validate a single email layout, or your can use the --all flag to validate all email layouts.

Can only be validated against the development environment.

Flags

When translations are pulled from Knock, they are stored in directories named by their locale codes. Their filename will be their locale code. Any namespaced translations will prepend the namespace to the filename, with . used as a separator.

translations/
├── en/
│  ├── en.json
│  └── admin.en.json
└── en-GB/
   ├── en-GB.json
   └── tasks.en-GB.json

If you're migrating your local translation files into Knock, you can arrange them using the file structure above and then push them into Knock with a single command using knock translation push --all. Each <locale>.json or <namespace>.<locale>.json file should follow the structure defined here.

List all translations in the environment. Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can show the content of a given translation with the translation get command, followed by the target translation ref.

The <translation_ref> is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. en. If namespaced, it is formatted as namespace.locale, i.e. admin.en.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can pull and download translation files from Knock to a local file system with the translation pull command. Knock CLI will create a new translation file or update the existing file in the local file system.

The <translation_ref> is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. en. If namespaced, it is formatted as namespace.locale, i.e. admin.en.

When <translation_ref> is a locale code and specified with the --all flag, all translations for that locale are pulled.

See the Translation file structure section for details on how translation files are organized.

Flags

Pushes local translation files back to Knock and upserts them.

The <translation_ref> is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. en. If namespaced, it is formatted as namespace.locale, i.e. admin.en.

When <translation_ref> is a locale code and specified with the --all flag, all translations for that locale are pushed.

See the Translation file structure section for details on how translation files are organized.

Flags

Validates one or more translation files. Useful for checking if the file is valid before running the translation push method.

The <translation_ref> is a identifier string that refers to a unique translation file. If a translation has no namespace, it is the same as the locale, i.e. en. If namespaced, it is formatted as namespace.locale, i.e. admin.en.

Can only be validated against the development environment.

Flags

When partials are pulled from Knock, they are stored in directories named by their partial key. Each partial directory contains a partial.json file that describes the partial's properties, and a content file based on the partial's type (HTML, markdown, plaintext, or JSON).

partials/
└── author-block/
    ├── content.html
    └── partial.json

The content file name depends on the partial's type:

• HTML partials: content.html
• Markdown partials: content.md
• Plaintext partials: content.txt
• JSON partials: content.json

If you're migrating your local partial files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using knock partial push --all.

List all partials in the environment. Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can show more details about a given partial with the partial get command, followed by the target partial key.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can pull and download partial files from Knock to a local file system with the partial pull command. Knock CLI will create a new partial directory or update the existing partial directory in the local file system.

Note: if pulling the target partial for the first time (or all partials), Knock CLI will ask to confirm before writing to the local file system.

See the Partial file structure section for details on how partial files are organized.

Flags

You can push and upload a partial directory to Knock with the partial push command. Knock will update an existing partial by the matching partial key, or create a new partial if it does not exist yet.

Note:

• The partial push command only pushes partials into the development environment.
• You must be directly above the target partial directory when running the partial push command, so the CLI can locate the partial.json file.
• You can also pass in the --commit flag (with an optional --commit-message flag) to commit the upserted changes immediately.

Flags

Validates one or more partial files. Useful for checking if the file is valid before running the partial push method.

Can only be validated against the development environment.

Flags

List all commits in the environment. Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

Shows the details of a given commit, using the id of the commit.

Flags

You can commit all changes across all resources in the development environment with the commit command.

Flags

You can promote one change to the subsequent environment, or all changes across all resources to the target environment from its directly preceding environment, using the commit promote command.

Note:

• For example, if you have three environments "development", "staging", and "production" (in that order), setting the --to flag to production will promote all new changes from the staging environment to the production environment.
• Promoting one single commit from staging using the --only flag, will result in that commit being promoted to production.
• The --to environment must be a non-development environment.
• The --to and --only flags can't be used together.

Flags

When guides are pulled from Knock, they are stored in directories named by their guide key. Each guide directory contains a guide.json file that describes the guide's configuration.

guides/
└── conference-banner/
    └── guide.json

If you're migrating your local guide files into Knock, you can arrange them using the example file structure above and then push them into Knock with a single command using knock guide push --all.

You can see all your existing guides in a given environment with the guide list command.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can show more details about a given guide with the guide get command, followed by the target guide key.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

You can pull and download guides from Knock to a local file system with the guide pull command. Knock CLI will create a new guide directory or update the existing guide directory in the local file system.

Note: if pulling the target guide for the first time (or all guides), Knock CLI will ask to confirm before writing to the local file system.

See the Guide file structure section for details on how guide files are organized.

Flags

You can push and upload a guide directory to Knock with the guide push command. Knock will update an existing guide by the matching guide key, or create a new guide if it does not exist yet.

Note:

• The guide push command only pushes guides into the development environment.
• You must be directly above the target guide directory when running the guide push command, so the CLI can locate the guide.json file.
• You can also pass in the --commit flag (with an optional --commit-message flag) to commit the upserted changes immediately.

See the Guide file structure section for details on how guide files are organized.

Flags

You can validate a new or updated guide directory with the guide validate command. Knock will validate the given guide payload in the same way as it would with the guide push command, except without persisting those changes.

Note: Validating a guide is only done against the development environment.

Flags

You can activate or deactivate a guide in a given environment with the guide activate command. You can either set the active status immediately or schedule it.

Flags

When message types are pulled from Knock, they are stored in directories named by their message type key. Each message type directory contains a message_type.json file that describes the message type's schema and configuration, and a preview.html file that contains the HTML preview template.

message-types/
└── alert-banner/
    ├── message_type.json
    └── preview.html

If you're migrating your local message type files into Knock, you can arrange them using the example file structure above.

Display all in-app message types for an environment. Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

Display a single in-app message type from an environment.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI defaults to the development environment.

Flags

Pull one or more in-app message types from an environment into a local file system. Knock CLI will create a new message type directory or update the existing message type directory in the local file system.

Note: if pulling the target message type for the first time (or all message types), Knock CLI will ask to confirm before writing to the local file system.

See the Message type file structure section for details on how message type files are organized.

Flags

Push one or more message types from a local file system to Knock. Knock will update an existing message type by the matching message type key, or create a new message type if it does not exist yet.

Note:

• The message-type push command only pushes message types into the development environment.
• You must be directly above the target message type directory when running the message-type push command, so the CLI can locate the message_type.json file.
• You can also pass in the --commit flag (with an optional --commit-message flag) to commit the upserted changes immediately.

See the Message type file structure section for details on how message type files are organized.

Flags

Validate one or more message types from a local file system. Knock will validate the given message type payload in the same way as it would with the message-type push command, except without persisting those changes.

Note: Validating a message type is only done against the development environment.

Flags