From 968aaab2cf115dd61bf0be820956120752282d46 Mon Sep 17 00:00:00 2001 From: Chris Bell Date: Wed, 18 Mar 2026 15:14:26 -0400 Subject: [PATCH] feat: add force push to CLI --- content/cli/audience.mdx | 342 ++++++++++++++++++ content/cli/email-layout.mdx | 5 + content/cli/guide.mdx | 7 +- content/cli/message-type.mdx | 7 +- content/cli/partial.mdx | 7 +- content/cli/resources.mdx | 11 +- content/cli/translation.mdx | 5 + content/cli/workflow.mdx | 7 +- .../developer-tools/integrating-into-cicd.mdx | 2 + content/version-control/branches.mdx | 2 + data/sidebars/cliSidebar.ts | 14 + 11 files changed, 402 insertions(+), 7 deletions(-) create mode 100644 content/cli/audience.mdx diff --git a/content/cli/audience.mdx b/content/cli/audience.mdx new file mode 100644 index 000000000..67a804045 --- /dev/null +++ b/content/cli/audience.mdx @@ -0,0 +1,342 @@ +--- +title: Audiences +description: Commands for managing audiences in the Knock CLI. +--- + +
+ + +Audience commands enable you to manage audiences in your Knock account from the CLI. + + +
+ +
+ + +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). + +{/* prettier-ignore */} + +{`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`](/cli/audience/push). + + +
+ +
+ + +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 + + + + + + + + + + + + + + +```bash title="Basic usage" +knock audience list +``` + +```bash title="Pagination example" +knock audience list --after=xxx +``` + + +
+ +
+ + +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 + + + + + + + + + + + +```bash title="Basic usage" +knock audience get new-signups +``` + +```bash title="Get audience in a different environment" +knock audience get new-signups --environment=production +``` + + +
+ +
+ + +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](/cli/audience/file-structure) section for details on how audience files are organized. + +### Flags + + + + + + + + + + + + + + +```bash title="Basic usage" +knock audience pull new-signups +``` + +```bash title="Pulling an audience in a different environment" +knock audience pull new-signups --environment=production +``` + +```bash title="Pulling all audiences into ./audiences directory" +knock audience pull --all --audiences-dir=./audiences +``` + + +
+ +
+ + +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. + +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: + +- 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](/cli/audience/file-structure) section for details on how audience files are organized. + +### Flags + + + + + + + + + + + + + + +```bash title="Basic usage" +knock audience push new-signups +``` + +```bash title="Pushing an audience and committing with a message" +knock audience push new-signups \ + --commit \ + -m "Commit message" +``` + +```bash title="Pushing all audiences from ./audiences directory" +knock audience push --all --audiences-dir=./audiences +``` + + +
+ +
+ + +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 + + + + + + + + + +```bash title="Basic usage" +knock audience validate new-signups +``` + + +
+ +
+ + +Archive an audience across all environments. Archiving removes the audience from use but preserves its configuration. + + + +### Flags + + + + + + + + + + +```bash title="Basic usage" +knock audience archive old-audience --environment=development +``` + + +
diff --git a/content/cli/email-layout.mdx b/content/cli/email-layout.mdx index a8f75c5ce..07298fa02 100644 --- a/content/cli/email-layout.mdx +++ b/content/cli/email-layout.mdx @@ -265,6 +265,11 @@ See the [Layout file structure](/cli/email-layout/file-structure) section for de type="directory" description="Specifies the target directory path to find and push all email layouts from. Only available to be used with --all, and defaults to the current working directory." /> + diff --git a/content/cli/guide.mdx b/content/cli/guide.mdx index 66f169472..4cf55cefb 100644 --- a/content/cli/guide.mdx +++ b/content/cli/guide.mdx @@ -253,7 +253,7 @@ By default this command will resolve to the guides resource directory via your ` Note: -- The `guide push` command only pushes guides into the `development` environment. +- The `guide push` command only pushes guides into the `development` environment by default. Use `--force` to bypass this restriction and overwrite content in any 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. @@ -282,6 +282,11 @@ See the [Guide file structure](/cli/guide/file-structure) section for details on type="directory" description="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." /> + diff --git a/content/cli/message-type.mdx b/content/cli/message-type.mdx index ff003332e..5b74468a3 100644 --- a/content/cli/message-type.mdx +++ b/content/cli/message-type.mdx @@ -247,7 +247,7 @@ By default this command will resolve to the message types resource directory via Note: -- The `message-type push` command only pushes message types into the `development` environment. +- The `message-type push` command only pushes message types into the `development` environment by default. Use `--force` to bypass this restriction and overwrite content in any environment. - You must be directly above the target message type directory when running the `message-type push` command, so the CLI can locate the `message_type.json` file. - You can also pass in the `--commit` flag (with an optional `--commit-message` flag) to commit the upserted changes immediately. @@ -276,6 +276,11 @@ See the [Message type file structure](/cli/message-type/file-structure) section type="directory" description="Specifies the target directory path to find and push all message types from. Only available to be used with --all, and defaults to the current working directory." /> + diff --git a/content/cli/partial.mdx b/content/cli/partial.mdx index b319fd75f..afa48d756 100644 --- a/content/cli/partial.mdx +++ b/content/cli/partial.mdx @@ -251,7 +251,7 @@ By default this command will resolve to the partial resource directory via your Note: -- The `partial push` command only pushes partials into the `development` environment. +- The `partial push` command only pushes partials into the `development` environment by default. Use `--force` to bypass this restriction and overwrite content in any environment. - You must be directly above the target partial directory when running the `partial push` command, so the CLI can locate the `partial.json` file. - You can also pass in the `--commit` flag (with an optional `--commit-message` flag) to commit the upserted changes immediately. @@ -278,6 +278,11 @@ Note: type="directory" description="Specifies the target directory path to find and push all partials from. Only available to be used with --all, and defaults to the current working directory." /> + diff --git a/content/cli/resources.mdx b/content/cli/resources.mdx index b6e5e0cc5..e79f15ff4 100644 --- a/content/cli/resources.mdx +++ b/content/cli/resources.mdx @@ -6,7 +6,7 @@ description: Commands for managing all Knock resources at once.
-These commands enable you to manage all Knock resources (workflows, partials, email layouts, translations, guides, and message-types) at once. +These commands enable you to manage all Knock resources (workflows, partials, email layouts, translations, guides, message-types, and audiences) at once.
@@ -39,7 +39,7 @@ knock init
-Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, and message-types) from Knock into your local file system. +Pulls the contents of all Knock resources (workflows, partials, email layouts, translations, guides, message-types, and audiences) from Knock into your local file system. Resources will be grouped by resource type within subdirectories of the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands. @@ -86,7 +86,7 @@ knock pull --knock-dir=./knock
-Pushes all local resource files (workflows, partials, email layouts, and translations) back to Knock and upserts them. +Pushes all local resource files (workflows, partials, email layouts, translations, guides, message-types, and audiences) back to Knock and upserts them. Resources will be pushed to the target directory path set either by your `knock.json` file or by the `--knock-dir` flag. See the [Directory structure](/cli/overview/directory-structure) section for details on the directory structure used by `push` and `pull` commands. @@ -108,6 +108,11 @@ Resources will be pushed to the target directory path set either by your `knock. type="string" description="The commit message to pass when using the `--commit` flag." /> + diff --git a/content/cli/translation.mdx b/content/cli/translation.mdx index a3a975aa2..325732d2b 100644 --- a/content/cli/translation.mdx +++ b/content/cli/translation.mdx @@ -231,6 +231,11 @@ See the [Translation file structure](/cli/translation/file-structure) section fo type="directory" description="Specifies the target directory path to find and push all translations from. Only available to be used with --all, and defaults to the current working directory." /> + diff --git a/content/cli/workflow.mdx b/content/cli/workflow.mdx index 853a9c92b..8023c6f42 100644 --- a/content/cli/workflow.mdx +++ b/content/cli/workflow.mdx @@ -272,7 +272,7 @@ By default this command will resolve to the workflows resource directory via you Note: -- The `workflow push` command only pushes workflows into the `development` environment. +- The `workflow push` command only pushes workflows into the `development` environment by default. Use `--force` to bypass this restriction and overwrite content in any environment. - You must be directly above the target workflow directory when running the `workflow push` command, so the CLI can locate the `workflow.json` file. - You can also pass in the `--commit` flag (with an optional `--commit-message` flag) to commit the upserted changes immediately. @@ -301,6 +301,11 @@ See the [Workflow file structure](/cli/workflow/file-structure) section for deta type="directory" description="Specifies the target directory path to find and push all workflows from. Only available to be used with --all, and defaults to the current working directory." /> + diff --git a/content/developer-tools/integrating-into-cicd.mdx b/content/developer-tools/integrating-into-cicd.mdx index ebec48ce2..a21b7f225 100644 --- a/content/developer-tools/integrating-into-cicd.mdx +++ b/content/developer-tools/integrating-into-cicd.mdx @@ -32,6 +32,8 @@ You can also work with specific resources by providing a `key` rather than using Once you’re ready to send your updates back to Knock’s Development environment, you can push ([`knock push`](/cli/push)) and commit ([`knock commit`](/cli/commit/all)) changes directly from the command line in the same way that you would save and commit them in your dashboard. You can also perform both of these actions at once by using the `--commit` flag on any `push` command. +As an alternative to the push, commit, and promote workflow, you can use the `--force` flag on push commands to bypass environment restrictions and push directly to non-development environments (for example, staging or production). When using `--force` in this way, you should also pass `--commit` so that your changes are persisted. See the [push command reference](/cli/resources/push) for details. +