Docs

Reusable requests

Commands for managing reusable requests in the Knock CLI.

Reusable request commands enable you to manage reusable requests in your Knock account from the CLI.

A reusable request is a versioned resource. Pushing one upserts it in the target environment, and you commit and promote that change the same way you do for a workflow. knock pull and knock push include reusable requests, and they push reusable requests before workflows that reference them.

Reusable request file structure

When reusable requests are pulled from Knock, they are stored in directories named by their reusable request key. Each directory contains a reusable_request.json file. The key is the directory name. Pulled files store it under __readonly.key.

reusable-requests/
└── fetch-user/
  └── reusable_request.json

reusable_request.json describes the request:

name. The human-readable name.
description. Optional context about what the request does.
type. http_fetch. This is the only supported type.
settings. The HTTP configuration: method (get, post, put, delete, or patch), url, and optional body, headers, query_params, response_path, and signing_key.
settings.data_input_schema. Optional JSON Schema for request inputs.
settings.data_input_values_str. Optional preview input values, as a JSON string.
conditions. Optional conditions that decide whether the request runs.

A reusable request key must be 3 to 255 characters and use only lowercase letters, numbers, dashes, or underscores.

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

knock reusable-request list [flags]

Display all reusable requests for an 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.

--branchstring

The branch to use. Defaults to the main branch.

--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 reusable-request get <reusable_request_key> [flags]

Display a single reusable request from an 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.

--branchstring

The branch to use. Defaults to the main branch.

--hide-uncommitted-changesboolean

Should any uncommitted changes be hidden? Defaults to false.

--jsonstring

Format output as json.

knock reusable-request new [flags]

Create a new reusable request with a minimal configuration.

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

When --name or --key is omitted, the command prompts for them. --type defaults to http_fetch, --method defaults to get, and --url defaults to https://example.com.

Flags

-n, --namestring

The name of the reusable request. If not provided, will be prompted.

-k, --keystring

The key of the reusable request. If not provided, will be prompted and defaults to a slug of the name.

-t, --typestring

The reusable request type. Only http_fetch is supported. Defaults to http_fetch.

-d, --descriptionstring

The description of the reusable request.

--methodstring

The HTTP method of the request. One of: get, post, put, delete, patch. Defaults to get.

--urlstring

The URL of the request. Defaults to https://example.com.

--environmentstring

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

--branchstring

The branch to use. Defaults to the main branch.

-p, --pushboolean

Push the reusable request to Knock after creating it locally. Defaults to false.

--forceboolean

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

knock reusable-request pull <reusable_request_key> [flags]

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

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

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

See the Reusable request file structure section for details on how reusable request files are organized.

Flags

--environmentstring

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

--branchstring

The branch to use. Defaults to the main branch.

--allboolean

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

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

--reusable-requests-dirdirectory

Specifies which target directory path to pull all reusable requests 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.

--jsonstring

Format output as json.

knock reusable-request push <reusable_request_key> [flags]

Push one or more reusable requests from a local file system to Knock. Knock will update an existing reusable request by the matching key, or create a new reusable request if it does not exist yet.

Note:

You must be directly above the target reusable request directory when running the reusable-request push command, so the CLI can locate the reusable_request.json file.
You can also pass in the --commit flag (with an optional --commit-message flag) to commit the upserted changes.
You can pass --allow-empty with --commit to create an empty commit when re-upserting an unchanged resource. See empty commits for more on when and why to use this.

See the Reusable request file structure section for details on how reusable request files are organized.

Flags

--environmentstring

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

--branchstring

The branch to use. Defaults to the main branch.

--commitboolean

Push and commit the reusable request(s) at the same time. Defaults to false.

-m, --commit-messagestring

The commit message to pass when using the --commit flag.

--allow-emptyboolean

Only meaningful with --commit. When the resource is already published with no unpublished changes, create an empty commit instead of a no-op publish. Defaults to false.

--allboolean

Whether to push all reusable requests from the target directory path set by --reusable-requests-dir. Defaults to false.

--reusable-requests-dirdirectory

Specifies the target directory path to find and push all reusable requests from. Only available to be used with --all, and defaults to the current working directory.

--forceboolean

Force pushes the resource or resources to Knock, overwriting whatever is currently stored. If you're using this on a non-development environment, you should also ensure you commit the changes. Defaults to false.

--jsonstring

Format output as json.

knock reusable-request validate <reusable_request_key> [flags]

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

Flags

--environmentstring

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

--branchstring

The branch to use. Defaults to the main branch.

--allboolean

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

--reusable-requests-dirdirectory

Specifies the target directory path to find and validate all reusable requests from. Only available to be used with --all, and defaults to the current working directory.

--jsonstring

Format output as json.

knock reusable-request archive <reusable_request_key> [flags]

Archive a reusable request across all environments. If a local copy exists at <knock dir>/reusable-requests/<key>, the command removes that directory so a later push does not create the reusable request again.

--environment is required. Pass --force when you also pass --json.

Flags

--environmentstringRequired

The environment in which the reusable request exists.

--branchstring

The branch to use. Defaults to the main branch.

--forceboolean

Removes the confirmation prompt. Required when using --json. Defaults to false.

--jsonstring

Format output as json.