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

The Knock CLI relies on a service token to authenticate and make requests to your Knock account. You can specify a service token in all CLI calls, or you can optionally use a configuration file to authenticate all requests.

Learn how to create a service token.

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

--service-tokenstringThe service token for a Knock account to issue the commands against. Required when not using a configuration file.

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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--limitnumberThe total number to fetch per page.
--afterstringFetches all entries after this cursor.
--beforestringFetches all entries before this cursor.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--allboolean

Whether to pull all workflows from the specified environment into the target directory path set by `--workflows-dir`. Defaults to false.

When used, all contents in the target directory will be erased and replaced with all workflows from the specified environment.

--workflows-dirdirectorySpecifies which target directory path to pull all workflows into. Only available to be used with --all, and defaults to the current working directory.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--forcebooleanRemoves 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 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.

Flags

--commitbooleanPush and commit the workflow(s) at the same time. Defaults to false.
-m, --commit-messagestringThe commit message to pass when using the `--commit` flag.
--allbooleanWhether to push all workflows from the target directory path set by `--workflows-dir`. Defaults to false.
--workflows-dirdirectorySpecifies 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.

Flags

--environmentstringThe slug of the environment in which to run this workflow. Defaults to development.
--recipientsstring[]One or more recipient ids for this workflow run, maximum limit 5.
--datastringA JSON string of the data with which this workflow will run.
--actorstringAn optional actor id for this workflow run.
--tenantstringAn 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.

Flags

--allbooleanWhether to validate all workflows from the target directory path set by `--workflows-dir`. Defaults to false.
--workflows-dirdirectorySpecifies 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 with false in order to deactivate it.

Flags

--environmentstring (required)The environment to activate the workflow in.
--forcebooleanRemoves the confirmation prompt. Defaults to false.
--statusbooleanThe status to set. Defaults to `true`.

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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--limitnumberThe total number to fetch per page.
--afterstringFetches all entries after this cursor.
--beforestringFetches all entries before this cursor.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--allboolean

Whether to pull all email layouts from the specified environment into the target directory path set by `--email-layouts-dir`. Defaults to false.

When used, all contents in the target directory will be erased and replaced with all email layouts from the specified environment.

--email-layouts-dirdirectorySpecifies 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.

Flags

--commitbooleanPush and commit at the same time. Defaults to false.
-m, --commit-messagestringThe commit message to pass when using the `--commit` flag.
--allbooleanWhether to push all email layouts to the target environment. Defaults to false.
--email-layouts-dirdirectorySpecifies 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.

Flags

--allbooleanWhether to validate all email layouts. Defaults to false.
--email-layouts-dirdirectorySpecifies 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--limitnumberThe total number to fetch per page.
--afterstringFetches all entries after this cursor.
--beforestringFetches all entries before this cursor.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--formatstringSpecify the output format of the returned translations. Supports 'json' and 'po'. Defaults to 'json'.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--formatstringSpecify the output format of the returned translations. Supports 'json' and 'po'. Defaults to 'json'.
--allboolean

Whether to pull all translations from the specified environment into the target directory path set by `--translations-dir`. Defaults to false.

When used with a locale code, will pull all translations for that locale only.

Note: all contents in the target directory will be erased and replaced with all translations from the specified environment.

--translations-dirdirectorySpecifies 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.

Flags

--commitbooleanPush and commit at the same time. Defaults to false.
-m, --commit-messagestringThe commit message to pass when using the `--commit` flag.
--allbooleanWhether to push all translation files to the target environment. Defaults to false.
--translations-dirdirectorySpecifies 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.

Flags

--allbooleanWhether to validate all translation files. Defaults to false.
--translations-dirdirectorySpecifies 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--limitnumberThe total number to fetch per page.
--afterstringFetches all entries after this cursor.
--beforestringFetches all entries before this cursor.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--jsonstringFormat 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--allboolean

Whether to pull all partials from the specified environment into the target directory path set by `--partials-dir`. Defaults to false.

Note: all contents in the target directory will be erased and replaced with all partials from the specified environment.

--partials-dirdirectorySpecifies which target directory path to pull all partials into. Only available to be used with --all, and defaults to the current working directory.
--hide-uncommitted-changesbooleanShould any uncommitted changes be hidden? Defaults to false.
--forcebooleanRemoves 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 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

--commitbooleanPush and commit at the same time. Defaults to false.
-m, --commit-messagestringThe commit message to pass when using the `--commit` flag.
--allbooleanWhether to push all partial files to the target environment. Defaults to false.
--partials-dirdirectorySpecifies 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.

Flags

--allbooleanWhether to validate all partial files. Defaults to false.
--partials-dirdirectorySpecifies 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.

Flags

--environmentstringThe environment to use. Defaults to development.
--[no-]promotedbooleanShow only promoted or unpromoted changes between the given environment and the subsequent environment.
--limitnumberThe total number to fetch per page.
--afterstringFetches all entries after this cursor.
--beforestringFetches all entries before this cursor.
--jsonstringFormat output as json.

knock commit get <commit_id> [flags]

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

Flags

--jsonstringFormat output as json.

knock commit [flags]

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

Flags

-m, --commit-messagestringThe commit message to use for all changes.
--forcebooleanRemoves the confirmation prompt. Defaults to false.

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 to production will promote all new changes from the staging environment to the production environment
  • Following the same example, 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

--tostringThe destination environment.
--onlystringThe target commit id to promote to the subsequent environment.
--forcebooleanRemoves the confirmation prompt. Defaults to false.