CLI reference
Learn more about the commands and flags available in the Knock CLI.
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 the CLI
#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.
Authentication
#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.
knock {cmd} <arguments> [flags]
#The following flags are supported for every command.
Flags
The service token for a Knock account to issue the commands against. Required when not using a personal account, or a configuration file.
knock login
#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.
knock logout
#You can log out of your Knock account with the logout
command. This will clear the authentication token for the CLI.
knock pull [flags]
#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/
The environment to use. Defaults to development.
The target directory path to pull all resources into.
Should any uncommitted changes be hidden? Defaults to false.
Removes the confirmation prompt. Defaults to false.
knock push [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.
The target directory path to push all resources from.
Push and commit at the same time. Defaults to false.
The commit message to pass when using the --commit
flag.
knock workflow list [flags]
#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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
The total number to fetch per page.
Fetches all entries after this cursor.
Fetches all entries before this cursor.
Format output as json.
knock workflow get [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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
Format output as json.
knock workflow pull [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 how workflow files are structured in your system here.
The environment to use. Defaults to development.
Specifies which target directory path to pull all workflows into. Only available to be used with --all, and defaults to the current working directory.
Should any uncommitted changes be hidden? Defaults to false.
Removes the confirmation prompt. Defaults to false.
knock workflow push [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 thedevelopment
environment. - You must be directly above the target workflow directory when running the
workflow push
command, so the CLI can locate theworkflow.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.
Push and commit the workflow(s) at the same time. Defaults to false.
The commit message to pass when using the --commit
flag.
Whether to push all workflows from the target directory path set by --workflows-dir
. Defaults to false.
Specifies the target directory path to find and push all workflows from. Only available to be used with --all, and defaults to the current working directory.
knock workflow run <workflow_key> [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.
The slug of the environment in which to run this workflow. Defaults to development.
One or more recipient ids for this workflow run, maximum limit 5.
A JSON string of the data with which this workflow will run.
An optional actor id for this workflow run.
An optional tenant id for this workflow run.
knock workflow validate <workflow_key> [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.
Whether to validate all workflows from the target directory path set by --workflows-dir
. Defaults to false.
Specifies the target directory path to find and validate all workflows from. Only available to be used with --all, and defaults to the current working directory.
knock workflow activate [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 withfalse
in order to deactivate it.
The environment to activate the workflow in.
Removes the confirmation prompt. Defaults to false.
The status to set. Defaults to true
.
knock workflow generate-types [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.
The environment to fetch workflows from. Defaults to development.
Specifies the file to generate types into. The language is inferred from the file suffix.
knock layout list [flags]
#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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
The total number to fetch per page.
Fetches all entries after this cursor.
Fetches all entries before this cursor.
Format output as json.
knock layout get <layout_key> [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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
Format output as json.
knock layout pull <layout_key> [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 how layout files are structured in your system here.
The environment to use. Defaults to development.
Specifies which target directory path to pull all email layouts into. Only available to be used with --all, and defaults to the current working directory.
knock layout push <layout_key> [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 how layout files are structured in your system here.
Push and commit at the same time. Defaults to false.
The commit message to pass when using the --commit
flag.
Whether to push all email layouts to the target environment. Defaults to false.
Specifies the target directory path to find and push all email layouts from. Only available to be used with --all, and defaults to the current working directory.
knock layout validate <layout_key> [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.
Whether to validate all email layouts. Defaults to false.
Specifies the target directory path to find and validate all email layouts from. Only available to be used with --all, and defaults to the current working directory.
knock translation list [flags]
#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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
The total number to fetch per page.
Fetches all entries after this cursor.
Fetches all entries before this cursor.
Format output as json.
knock translation get <translation_ref> [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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
Specify the output format of the returned translations. Supports 'json' and 'po'. Defaults to 'json'.
Format output as json.
knock translation pull <translation_ref> [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 how translation files are structured in your system here.
The environment to use. Defaults to development.
Specify the output format of the returned translations. Supports 'json' and 'po'. Defaults to 'json'.
Specifies which target directory path to pull all translations into. Only available to be used with --all, and defaults to the current working directory.
knock translation push <translation_ref> [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 how translation files are structured in your system here.
Push and commit at the same time. Defaults to false.
The commit message to pass when using the --commit
flag.
Whether to push all translation files to the target environment. Defaults to false.
Specifies the target directory path to find and push all translations from. Only available to be used with --all, and defaults to the current working directory.
knock translation validate <translation_ref> [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.
Whether to validate all translation files. Defaults to false.
Specifies the target directory path to find and validate all translation files from. Only available to be used with --all, and defaults to the current working directory.
knock partial list [flags]
#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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
The total number to fetch per page.
Fetches all entries after this cursor.
Fetches all entries before this cursor.
Format output as json.
knock partial get <partial_key> [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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
Format output as json.
knock partial pull <partial_key> [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 how partial files are structured in your system here.
The environment to use. Defaults to development.
Specifies which target directory path to pull all partials into. Only available to be used with --all, and defaults to the current working directory.
Should any uncommitted changes be hidden? Defaults to false.
Removes the confirmation prompt. Defaults to false.
knock partial push <partial_key> [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 thedevelopment
environment. - You must be directly above the target partial directory when running the
partial push
command, so the CLI can locate thepartial.json
file. - You can also pass in the
--commit
flag (with an optional--commit-message
flag) to commit the upserted changes immediately.
Push and commit at the same time. Defaults to false.
The commit message to pass when using the --commit
flag.
Whether to push all partial files to the target environment. Defaults to false.
Specifies the target directory path to find and push all partials from. Only available to be used with --all, and defaults to the current working directory.
knock partial validate <partial_key> [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.
Whether to validate all partial files. Defaults to false.
Specifies the target directory path to find and validate all partial files from. Only available to be used with --all, and defaults to the current working directory.
knock commit list [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.
The environment to use. Defaults to development.
Show only promoted or unpromoted changes between the given environment and the subsequent environment.
The total number to fetch per page.
Fetches all entries after this cursor.
Fetches all entries before this cursor.
Filter commits by resource type. One of: email_layout
, workflow
, guide
, partial
, translation
. Must be used with --resource-id.
Filter commits by the given resource id. This is most typically the key
of the resource. In the case of translations, this will be the locale code and namespace, separated by a /
. Must be used with --resource-type.
Format output as json.
knock commit get <commit_id> [flags]
#knock commit [flags]
#knock commit promote [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 toproduction
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.
The destination environment.
The target commit id to promote to the subsequent environment.
Removes the confirmation prompt. Defaults to false.
knock guides list [flags]
#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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
The total number to fetch per page.
Fetches all entries after this cursor.
Fetches all entries before this cursor.
Format output as json.
knock guides get [flags]
#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.
The environment to use. Defaults to development.
Should any uncommitted changes be hidden? Defaults to false.
Format output as json.
knock guides pull [flags]
#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.
The environment to use. Defaults to development.
Specifies which target directory path to pull all guides into. Only available to be used with --all, and defaults to the current working directory.
Should any uncommitted changes be hidden? Defaults to false.
Removes the confirmation prompt. Defaults to false.
knock guides push [flags]
#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 thedevelopment
environment. - You must be directly above the target guide directory when running the
guides push
command, so the CLI can locate theguide.json
file. - You can also pass in the
--commit
flag (with an optional--commit-message
flag) to commit the upserted changes immediately.
Push and commit the guide(s) at the same time. Defaults to false.
The commit message to pass when using the --commit
flag.
Whether to push all guides from the target directory path set by --guides-dir
. Defaults to false.
Specifies the target directory path to find and push all guides from. Only available to be used with --all, and defaults to the current working directory.
knock guides validate [flags]
#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.
Whether to validate all guides from the target directory path set by --guides-dir
. Defaults to false.
Specifies the target directory path to find and validate all guides from. Only available to be used with --all, and defaults to the current working directory.
knock guides activate [flags]
#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.
The environment to activate the guide in.
Removes the confirmation prompt. Defaults to false.
The status to set. Cannot be used with --from/--until.
Activate the guide from this ISO8601 UTC datetime (e.g., '2024-01-15T10:30:00Z').
Deactivate the guide at this ISO8601 UTC datetime (e.g., '2024-01-15T10:30:00Z').