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

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, and translations) 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. For example, invoking knock pull --knock-dir=./knock will create the following directory structure:

./knock/
├── layouts/
├── partials/
├── translations/
└── workflows/

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.

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.

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.

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 how workflow files are structured in your system here.

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 how workflow files are structured in your system here.

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.

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.

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.

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.

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.

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.

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 how layout files are structured in your system here.

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 how layout files are structured in your system here.

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.

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.

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.

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 how translation files are structured in your system here.

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 how translation files are structured in your system here.

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.

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.

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.

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 how partial files are structured in your system here.

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.

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.

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.

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

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

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.

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

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

You can show more details about a given guide with the guides 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.

You can pull and download guides from Knock to a local file system with the guides 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.

You can push and upload a guide directory to Knock with the guides 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 guides push command only pushes guides into the development environment.
• You must be directly above the target guide directory when running the guides 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.

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

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

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