Docs

Audiences

Commands for managing audiences in the Knock CLI.

Audience commands enable you to manage audiences in your Knock account from the CLI.

Audience file structure

When audiences are pulled from Knock, they are stored in directories named by their audience key. Each audience directory contains an audience.json file that describes the audience's configuration (name, type, and for dynamic audiences, segments).

audiences/
└── new-signups/
  └── audience.json

If you're migrating your local audience 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 audience push --all.

knock audience list [flags]

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

Flags

--environmentstring

The environment to use. Defaults to development.

--branchstring

The branch to use. Defaults to the main branch.

--hide-uncommitted-changesboolean

Should any uncommitted changes be hidden? Defaults to false.

--limitnumber

The total number to fetch per page.

--afterstring

Fetches all entries after this cursor.

--beforestring

Fetches all entries before this cursor.

--jsonstring

Format output as json.

knock audience get <audience_key> [flags]

Display a single audience from an environment.

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

Flags

--environmentstring

The environment to use. Defaults to development.

--branchstring

The branch to use. Defaults to the main branch.

--hide-uncommitted-changesboolean

Should any uncommitted changes be hidden? Defaults to false.

--jsonstring

Format output as json.

knock audience pull <audience_key> [flags]

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

By default this command will resolve to the audiences 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 --audiences-dir flag.

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

See the Audience file structure section for details on how audience files are organized.

Flags

--environmentstring

The environment to use. Defaults to development.

--branchstring

The branch to use. Defaults to the main branch.

--allboolean

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

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

--audiences-dirdirectory

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

--hide-uncommitted-changesboolean

Should any uncommitted changes be hidden? Defaults to false.

--forceboolean

Removes the confirmation prompt. Defaults to false.

knock audience push <audience_key> [flags]

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

Note:

You must be directly above the target audience directory when running the audience push command, so the CLI can locate the audience.json file.
You can also pass in the --commit flag (with an optional --commit-message flag) to commit the upserted changes immediately.
Use --force to bypass environment restrictions and overwrite content in any environment. If you're using this on a non-development environment, you should also ensure you commit the changes.

See the Audience file structure section for details on how audience files are organized.

Flags

--environmentstring

The environment to push the audience to. Defaults to development.

--branchstring

The branch to use. Defaults to the main branch.

--commitboolean

Push and commit the audience(s) at the same time. Defaults to false.

-m, --commit-messagestring

The commit message to pass when using the --commit flag.

--allboolean

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

--audiences-dirdirectory

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

--forceboolean

Force pushes the resource or resources to Knock, overwriting whatever is currently stored. If you're using this on a non-development environment, you should also ensure you commit the changes. Defaults to false.

knock audience validate <audience_key> [flags]

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

Note: Validating an audience is only done against the development environment.

Flags

--allboolean

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

--audiences-dirdirectory

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

knock audience archive <audience_key> [flags]

Archive an audience across all environments. Archiving removes the audience from use but preserves its configuration.

Flags

--environmentstringRequired

The environment in which the audience exists.

--branchstring

The branch to use. Defaults to the main branch.

--forceboolean

Removes the confirmation prompt. Defaults to false.