Docs

Guides

Commands for managing guides in the Knock CLI.

Guide commands enable you to manage guides in your Knock account from the CLI.

Guide file structure

When guides are pulled from Knock, they are stored in directories named by their guide key. Each guide directory contains a guide.json file that describes the guide's configuration.

guides/
└── conference-banner/
  └── guide.json

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

knock guide list [flags]

You can see all your existing guides in a given environment with the guide list command.

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.

--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 guide new [flags]

Create a new guide with a minimal configuration.

The command will create a new guide directory in your local file system. By default, this will be in the guides resource directory set by your knock.json file, or the current working directory if not configured.

Flags

--keystring

The key for the guide. If not provided, will be prompted or inferred from the guide directory name.

--namestring

The name for the guide. If not provided, will be generated from the key.

--message-typestring

The key of the message type to use for the guide. If not provided, you will be prompted to select a message type interactively.

--environmentstring

The environment to use. Defaults to development.

--branchstring

The branch to use. Defaults to the main branch.

--pushboolean

Push the guide to Knock after creating it locally. Defaults to false.

--forceboolean

Overwrites an existing guide directory without prompting for confirmation. Defaults to false.

knock guide get [flags]

You can show more details about a given guide with the guide 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.

Flags

--environmentstring

The environment to use. Defaults to development.

--hide-uncommitted-changesboolean

Should any uncommitted changes be hidden? Defaults to false.

--jsonstring

Format output as json.

knock guide pull [flags]

You can pull and download guides from Knock to a local file system with the guide pull command. Knock CLI will create a new guide directory or update the existing guide directory in the local file system.

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

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.

See the Guide file structure section for details on how guide files are organized.

Flags

--environmentstring

The environment to use. Defaults to development.

--allboolean

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

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

--guides-dirdirectory

Specifies which target directory path to pull all guides 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 guide push [flags]

You can push and upload a guide directory to Knock with the guide 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 guide push command only pushes guides into the development environment.
You must be directly above the target guide directory when running the guide push command, so the CLI can locate the guide.json file.
You can also pass in the --commit flag (with an optional --commit-message flag) to commit the upserted changes immediately.

See the Guide file structure section for details on how guide files are organized.

Flags

--commitboolean

Push and commit the guide(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 guides from the target directory path set by --guides-dir. Defaults to false.

--guides-dirdirectory

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 guide validate [flags]

You can validate a new or updated guide directory with the guide validate command. Knock will validate the given guide payload in the same way as it would with the guide push command, except without persisting those changes.

Note: Validating a guide is only done against the development environment.

Flags

--allboolean

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

--guides-dirdirectory

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 guide activate [flags]

You can activate or deactivate a guide in a given environment with the guide activate command. You can either set the active status immediately or schedule it.

Flags

--environmentstringRequired

The environment to activate the guide in.

--forceboolean

Removes the confirmation prompt. Defaults to false.

--statusboolean

The status to set. Cannot be used with --from/--until.

--fromutc_datetime

Activate the guide from this ISO8601 UTC datetime (e.g., '2024-01-15T10:30:00Z').

--untilutc_datetime

Deactivate the guide at this ISO8601 UTC datetime (e.g., '2024-01-15T10:30:00Z').