Docs

Commits

Commands for managing commits in the Knock CLI.

Commit commands enable you to manage commits in your Knock account from the CLI.

knock commit list [flags]

List all commits in the 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.

--[no-]promotedboolean

Show only promoted or unpromoted changes between the given environment and the subsequent environment.

--limitnumber

The total number to fetch per page.

--afterstring

Fetches all entries after this cursor.

--beforestring

Fetches all entries before this cursor.

--branchstring

The branch to use. Defaults to the main branch.

--resource-typestring

Filter commits by resource type. One of: audience, email_layout, guide, message_type, partial, reusable_request, translation, workflow. Can be used alone or together with --resource-id. Goals publish on save and are not a commit resource type.

--resource-idstring

Filter commits by the given resource identifier. This is most typically the key of the resource. In the case of translations, this will be the locale code and namespace, separated by a /. Must be used together with --resource-type.

--promote-group-idstring

Filter commits by promote group. Only show commits created by one promote. A promote's commits live in the environment they were promoted to. If that isn't the default environment, you also need --environment, or you get an empty list.

--promoted-from-environmentstring

Filter commits by source environment. Only show promoted commits from this source environment or branch, by slug.

--sincestring

Filter commits by creation time. Only show commits created at or after this RFC 3339 timestamp, e.g. 2026-01-31T09:00:00Z.

--untilstring

Filter commits by creation time. Only show commits created at or before this RFC 3339 timestamp.

--jsonstring

Format output as json.

knock commit get <commit_id> [flags]

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

Flags

--jsonstring

Format output as json.

knock commit [flags]

You can commit all changes across all resources in an environment with the commit command. When you omit --environment, the command commits changes in your account's default environment. Use --resource-type to commit only changes for a specific resource type, and optionally --resource-id to scope it further to a single resource.

Use --allow-empty to create an empty commit for a single resource that is already published with no unpublished changes. This produces a new commit log entry with identical content, which you can promote downstream. See empty commits for more on when and why to use this.

Note:

--allow-empty requires both --resource-type and --resource-id. You cannot use --allow-empty without scoping to a single resource.
When the resource has unpublished changes, --allow-empty is ignored and a normal commit happens instead.
-m, --commit-message is optional and stored in commit audit metadata. Your account may require a commit message.

Flags

--environmentstring

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

-m, --commit-messagestring

The commit message to use for all changes.

--branchstring

The branch to use. Defaults to the main branch.

--forceboolean

Removes the confirmation prompt. Defaults to false.

--resource-typestring

Commit only changes for the given resource type. One of: audience, email_layout, guide, message_type, partial, reusable_request, translation, workflow. Can be used alone or together with --resource-id. Goals publish on save and are not a commit resource type.

--resource-idstring

Commit only changes for the given resource identifier. Must be used together with --resource-type.

--allow-emptyboolean

Create an empty commit for a single resource when it is already published with no unpublished changes. Requires both --resource-type and --resource-id. Defaults to false.

Error cases

Scenario	Result
`--allow-empty` without both `--resource-type` and `--resource-id`	422 — `allow_empty` must be used with a single `resource_type` and `resource_id`
Resource not found	404
Resource has no current version	Error — cannot create an empty commit without a current version
Commit message required by account	422 — message can't be blank when account has `control-commit-msg-required` enabled

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. Promotion only applies to accounts that have enabled environments.

The command prints the promote group ID after a successful promotion for both --to and --only. This is the ID you can pass to knock commit list --promote-group-id to see all commits created by that promote. When --to has nothing to promote, the ID line is not included.

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.
Promoting one single commit from staging using the --only flag, will result in that commit being promoted to production.
The --to and --only flags can't be used together.

Flags

--tostring

The destination environment.

--onlystring

The target commit id to promote to the subsequent environment.

--forceboolean

Removes the confirmation prompt. Defaults to false.