Docs
/
/

Broadcasts

Commands for managing broadcasts in the Knock CLI.

#

Broadcast commands enable you to manage broadcasts in your Knock account from the CLI.

Broadcasts aren't versioned. knock broadcast push writes the broadcast straight to the target environment. There's no --commit flag and no commit or promote step. See Broadcasts and the environment model for more details.

knock pull and knock push don't include broadcasts. Use knock broadcast pull and knock broadcast push instead.

Broadcast file structure

#

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

Broadcast steps can only be channel, branch, or delay steps.

Pulled files include a $schema property that points to https://schemas.knock.app/cli/broadcast.json.

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

knock broadcast list [flags]

#

Display all broadcasts for an environment. Use an --environment flag to specify the target environment; if omitted, the Knock CLI uses the account's default environment.

Flags

--environmentstring

The environment to use. When omitted, the account's default environment is used.

--limitnumber

The total number of entries to fetch per page.

--afterstring

The cursor after which to fetch the next page.

--beforestring

The cursor before which to fetch the previous page.

--jsonstring

Format output as json.

knock broadcast get <broadcast_key> [flags]

#

Display a single broadcast from an environment.

Use an --environment flag to specify the target environment; if omitted, the Knock CLI uses the account's default environment.

Flags

--environmentstring

The environment to use. When omitted, the account's default environment is used.

--jsonstring

Format output as json.

knock broadcast new [flags]

#

Create a new broadcast with a minimal configuration.

The broadcast key must use only lowercase letters, numbers, dashes, or underscores.

The command prompts for the broadcast name, key, and channel steps unless you provide them via flags. A broadcast needs at least one channel step. Without --steps, the command asks for them. Each step uses the account's first channel of that type. The command fails if no email, in-app feed, SMS, push, or chat channel is set up.

The command cannot be run inside an existing resource directory. By default, the command writes into the broadcasts resource directory set by your knock.json file, or the current working directory if not configured.

Flags

--name, -nstring

The name of the broadcast.

--key, -kstring

The key of the broadcast.

--steps, -sstring

Comma-separated list of channel step types to include in the broadcast (e.g. email,in_app_feed). Broadcasts need at least one channel step.

--forceboolean

Force the creation of the broadcast directory without confirmation. Defaults to false.

knock broadcast pull [broadcast_key] [flags]

#

Pull one or more broadcasts from an environment into a local file system. Knock CLI will create a new broadcast directory or update the existing broadcast directory in the local file system.

By default this command will resolve to the broadcasts resource directory via your knock.json file. When not set, will use the current working directory as the default. In the case of the --all flag, the target directory path will be resolved via your knock.json file or the --broadcasts-dir flag.

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

See the Broadcast file structure section for details on how broadcast files are organized.

Flags

--environmentstring

The environment to use. When omitted, the account's default environment is used.

--allboolean

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

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

--broadcasts-dirdirectory

Specifies which target directory path to pull all broadcasts into. Only available to be used with --all, and defaults to the current working directory.

--forceboolean

Removes the confirmation prompt. Defaults to false.

knock broadcast push [broadcast_key] [flags]

#

Push one or more broadcasts from a local file system to Knock. Knock will update an existing broadcast by the matching broadcast key, or create a new broadcast if it does not exist yet. The command validates before it pushes. The push publishes the broadcast in the target environment. There is no --commit flag.

By default this command will resolve to the broadcasts resource directory via your knock.json file. When not set, will use the current working directory as the default. In the case of the --all flag, the target directory path will be resolved via your knock.json file or the --broadcasts-dir flag.

Note: you must be directly above the target broadcast directory when running the broadcast push command, so the CLI can locate the broadcast.json file.

See the Broadcast file structure section for details on how broadcast files are organized.

Flags

--environmentstring

The environment to use. When omitted, the account's default environment is used.

--allboolean

Whether to push all broadcasts from the target directory path set by --broadcasts-dir. Defaults to false.

--broadcasts-dirdirectory

Specifies the target directory path to find and push all broadcasts from. Only available to be used with --all, and defaults to the current working directory.

knock broadcast validate [broadcast_key] [flags]

#

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

Flags

--environmentstring

The environment to use. When omitted, the account's default environment is used.

--allboolean

Whether to validate all broadcasts from the target directory path set by --broadcasts-dir. Defaults to false.

--broadcasts-dirdirectory

Specifies the target directory path to find and validate all broadcasts from. Only available to be used with --all, and defaults to the current working directory.

knock broadcast run <broadcast_key> [flags]

#

Test run a broadcast for one recipient without publishing it.

Runs the current version of a broadcast for a single recipient. This does not publish the broadcast or message its target audience. Use --sandbox-mode to generate messages without sending them to the downstream provider.

This is the CLI version of "Run test" in the dashboard.

Flags

--recipientstring

(required) The user id to run this broadcast for.

--environmentstring

The environment to use. When omitted, the account's default environment is used.

--tenantstring

A tenant id for the broadcast run.

--sandbox-modeboolean

When enabled, channels generate messages but don't send them to the downstream provider. Defaults to false.

--skip-delayboolean

When enabled, delay steps in this broadcast will be skipped. Defaults to false.

--jsonstring

Format output as json.

knock broadcast send <broadcast_key> [flags]

#

Send or schedule a broadcast in a given environment.

Sends a broadcast immediately or schedules it for a future time. Use the --send-at flag to schedule the broadcast for a specific time.

The --environment flag is required for this command. There is no default environment. The command asks for confirmation unless you pass --force. With --json you must also pass --force.

Flags

--environmentstring

(required) The environment to use.

--send-atstring

ISO 8601 datetime to schedule the broadcast. Omit to send immediately.

--forceboolean

Remove the confirmation prompt. Defaults to false.

--jsonstring

Format output as json.

knock broadcast open <broadcast_key> [flags]

#

Open a broadcast in the Knock dashboard. This command opens the broadcast page in your default browser.

Flags

--environmentstring

The environment to use. When omitted, the account's default environment is used.

New chat