Goals

Goal commands enable you to manage goals in your Knock account from the CLI.

A goal publishes when you save it. knock goal push writes the goal to the target environment, and Knock does not create a commit for the goal. Goals cannot be created, updated, or attached on a branch. To copy a goal into another environment, use knock goal clone.

knock pull and knock push include goals. If goals are not enabled for the account, those commands skip the goals directory and continue with the other resources.

When goals are pulled from Knock, they are stored in directories named by their goal key. Each goal directory contains a goal.json file that describes the goal's name, description, and condition. The goal key is the directory name.

goals/
└── trial-conversion/
  └── goal.json

goal.json has three fields you can edit:

• name. The human-readable name for the goal.
• description. Optional context about what the goal means.
• condition. The event that completes the goal. See goal conditions.

An integration source condition sets event.event_type to integration_source and includes event_key, integration_source_key, and recipient_path. An audience condition sets event.event_type to audience, event_key to enter or exit, and audience_key to a dynamic audience. Optional match_conditions refine an integration source event.

Pulled files also include __readonly.key and a $schema property that points at https://schemas.knock.app/cli/goal.json.

To attach a goal to a workflow or guide, set goal_attachment on that resource's JSON file. The attachment is committed with the workflow or guide, not with the goal. See the workflow and guide file structures.

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

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

Flags

Display a single goal from an environment.

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

Flags

Scaffold a new goal in the local file system. The command writes a goal.json file whose name is the goal key and whose condition is an empty integration source event with recipient_path set to body.userId.

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

By default, the command writes into the goals resource directory set by your knock.json file, or the current working directory if not configured. It does not prompt, and it errors if a goal directory with that key already exists. It does not push the goal to Knock.

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

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

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

See the Goal file structure section for details on how goal files are organized.

Flags

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

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

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

See the Goal file structure section for details on how goal files are organized.

Flags

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

Flags

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

Flags

Clone a goal to a new goal key. Cloning copies the goal definition into the destination environment. It does not copy which workflows, broadcasts, or guides reference the goal.

The new goal key must use only lowercase letters, numbers, dashes, or underscores. --name defaults to the new goal key. --dest-environment defaults to --environment, which defaults to the account's default environment.

Goals are not promoted between environments. Clone a goal when you need the same definition in another environment, and keep the key the same across environments when a workflow or guide references it. See cloning a goal.

Flags

Archive a goal across all environments. Archiving stops new completions and attributions. Knock keeps historical goal versions and completions.

Detach the goal from every workflow, guide, and broadcast before you archive it. Knock refuses the archive while the goal is still attached.

The --environment flag selects the environment to issue the request against. When omitted, the Knock CLI uses the account's default environment. The archive still applies to every environment.

Flags