Branches are a way to isolate changes to your Knock resources. It's like a sandbox for your changes, allowing you to make changes to your resources without affecting the main branch (your development environment), or other branches in your account.

knock branch list [flags]

Lists all branches within your Knock account. You can paginate the results using the --after and --before flags.

Flags

--afterstring

Fetches all entries after this cursor.

--beforestring

Fetches all entries before this cursor.

--limitnumber

The total number to fetch per page.

knock branch create <branch_name> [flags]

Creates a new branch with the given slug. If the branch already exists, the command will return an error.

Flags

--jsonstring

Format output as json.

knock branch delete <branch_name> [flags]

Deletes the branch with the given slug.

Flags

--forceboolean

Force delete the branch without confirmation.

knock branch switch <branch_name> [flags]

Switches to an existing branch with the given slug.

Switching to the branch will persist until you exit the branch with the knock branch exit command by updating the .knockbranch file in your directory.

Flags

--forceboolean

Force switch the branch without confirmation.

--createboolean

Create the branch if it doesn't exist before switching to it.

knock branch exit

Exits the current branch by updating the .knockbranch file in your directory to the main branch.

knock branch rebase <branch_name> [flags]

Rebases a branch onto the development environment (main), bringing in the latest changes from main while preserving your branch's commits. See Rebase a branch for how rebasing works, including resource-level behavior and prerequisites.

The command prompts for confirmation before rebasing. Branch slugs are normalized automatically (for example, Mixed Case becomes mixed-case).

On success, the command prints the rebased branch slug and its updated_at timestamp. With --json, it returns the updated branch object.

Flags

--forceboolean

Rebase the branch without confirmation.

--jsonboolean

Format output as json.

Errors

The command surfaces API errors from the Management API, including:

branch_rebase_blocked. You have unpublished changes on shared resources where main has moved ahead. Commit or discard the blocking drafts and try again. The error message lists the affected resources.
branch_not_found. The branch slug does not exist in your project.

knock branch merge <branch_name> [flags]

Merges a branch into the development environment. By default, the branch will be deleted after merging.

Flags

--forceboolean

Removes the confirmation prompt. Defaults to false.

--[no-]deleteboolean

Delete the branch after merging. Defaults to true.