{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":2369,"path":"application-development/servicenow-cli/create-command.md","title":"Create a custom command in ServiceNow CLI","bundle":null,"doc_type":null,"release":"australia","body":"\n# Create a custom command in ServiceNow CLI\n\nManage your custom application from the command line by creating custom commands in the ServiceNow CLI.\n\n## Before you begin\n\nRole required: admin\n\n## About this task\n\nA ServiceNow CLI command maps to a scripted REST endpoint in the End Point \\[sn\\_cli\\_metadata\\_end\\_point\\] table. You can define a scripted REST endpoint to perform a function in your custom application, or use any existing REST endpoint. Then map a CLI command to execute the REST call.\n\n## Procedure\n\n1.  Make a REST endpoint available to a ServiceNow CLI command.\n\n    1.  Navigate to **Command Line Interface \\(CLI\\)** &gt; **End Points**.\n\n    2.  Select **New** and complete the form.\n\n        |Field|Description|\n        |-----|-----------|\n        |Resource Path|Required. Path to the endpoint on the instance to map a command to. Can be the path to an inbound REST API, or a scripted REST API. For example, `api/now/table/{table}/{sysid}`. For more information, see [Available REST APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/api-rest.md) and [Scripted REST APIs](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/api-reference/c_CustomWebServices.md).|\n        |HTTP Method|Required. HTTP method to use when the user runs the associated command.|\n        |Application|Read-only application scope for the endpoint.|\n\n2.  Create a command group.\n\n    Alternatively, you can add your new command to an existing command group.\n\n    1.  Navigate to **Command Line Interface \\(CLI\\)** &gt; **Command Groups**.\n\n    2.  Select **New** and complete the form.\n\n        |Field|Description|\n        |-----|-----------|\n        |Name|Required. Name of the command group.|\n        |Parent Group|Parent command group.|\n        |Reference Group|Command group to reference. For example, you can create a new command group as an alias for an existing command group. When the user calls a referenced command using the new command group, the original command executes. This enables you to create a command group specific to your custom application that includes both new and existing commands.|\n        |Short Description|Required. Short description for the command group.|\n        |Description|Description of the command group used as help text when the user runs the `--help` command on the command group.|\n        |Application|Read-only application scope for the command group.|\n        |Active|When selected, the command group is active.|\n\n3.  Create a command.\n\n    1.  Navigate to **Command Line Interface \\(CLI\\)** &gt; **Commands**.\n\n    2.  Select **New** and complete the form.\n\n<table id=\"table_o3q_qyg_m4b\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nRequired. Name of the command.\n\n</td></tr><tr><td>\n\nCommand Group\n\n</td><td>\n\nRequired. Command group that the command is a part of.\n\n</td></tr><tr><td>\n\nReference Command\n\n</td><td>\n\nCommand to reference. For example, you can create a new command as an alias for an existing command. When the user calls the new command, the original command executes. This enables you to create a command specific to your custom application that executes existing functionality.**Note:** A command cannot reference a command that references another command, or reference a descendant command, an ancestor command, or a callback command.\n\n</td></tr><tr><td>\n\nAPI Endpoint\n\n</td><td>\n\nRequired. API call to execute when the user runs the command.\n\n</td></tr><tr><td>\n\nShort Description\n\n</td><td>\n\nRequired. Short description of the command.\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nRead-only application scope for the command.\n\n</td></tr><tr><td>\n\nActive\n\n</td><td>\n\nWhen selected, the command is active.\n\n</td></tr><tr><td>\n\nIs Callback Command\n\n</td><td>\n\nWhen true, designates the command as a callback command. Select this option to hide the command from the CLI client and prevent users from calling it from the command line. Use this field with the **Callback** section of a primary command. The callback command executes when the primary command is complete.\n\n</td></tr><tr><td colspan=\"2\">\n\n**Help Text**\n\n</td></tr><tr><td>\n\nDescription\n\n</td><td>\n\nDescription of the command used as help text when the user runs the `--help` command.\n\n</td></tr><tr><td>\n\nExamples\n\n</td><td>\n\nExamples of the command used as help text when the user runs the `--help` command.\n\n</td></tr><tr><td colspan=\"2\">\n\n**Expressions**\n\n</td></tr><tr><td>\n\nSuccess Expression\n\n</td><td>\n\nExpression used to evaluate the response from the server and determine if the command succeeded. For example, `result.code = 1`.\n\n</td></tr><tr><td>\n\nFailure Expression\n\n</td><td>\n\nExpression used to evaluate the response from the server and determine if the command failed.\n\n</td></tr><tr><td colspan=\"2\">\n\n**Messages**\n\n</td></tr><tr><td>\n\nSuccess Message\n\n</td><td>\n\nMessage displayed on the CLI client when the command is successful.\n\n</td></tr><tr><td>\n\nProgress Message\n\n</td><td>\n\nMessage displayed on the CLI client when the command is in progress.\n\n</td></tr><tr><td>\n\nFailure Message\n\n</td><td>\n\nMessage displayed on the CLI client when the command fails.\n\n</td></tr><tr><td colspan=\"2\">\n\n**Callback**\n\n</td></tr><tr><td>\n\nCallback Expression\n\n</td><td>\n\nExpression used to determine whether to execute the callback command. For example, you can write an expression that checks on a long-running process. If the expression produces a certain result, the callback executes.\n\n</td></tr><tr><td>\n\nCallback Command\n\n</td><td>\n\nCommand to execute when the **Callback Expression** is satisfied. Must be a command with the **Is Callback Command** field selected.\n\n</td></tr><tr><td>\n\nCallback Interval\n\n</td><td>\n\nThe interval between callback command executions. Unit: Milliseconds\n\n Default: 1,000\n\n</td></tr><tr><td>\n\nMax Retries\n\n</td><td>\n\nMaximum number of times the callback command executes. Default: 10\n\n</td></tr></tbody>\n</table>    3.  In the Command Arguments related lists, create any command arguments needed for the command.\n\n        Create a command argument to allow users to set options when running a command.\n\n<table id=\"table_hg5_nnh_m4b\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nRequired. Name of the command argument, for example `data`.\n\n</td></tr><tr><td>\n\nShort Name\n\n</td><td>\n\nShort dame of the command argument, for example `d`.\n\n</td></tr><tr><td>\n\nData Type\n\n</td><td>\n\nRequired. Type of data expected for the command argument. Options include:-   String: Allows users to enter a string as input.\n-   Integer: Allows users to enter a number as input.\n-   Boolean: Allows users to enter `true` or `false` as input.\n-   File Input: Allows users to upload a file as input. Map this argument to a Body **Parameter Type** in the API Endpoint Arguments related list in the next step. Users can pass plain text, YAML, JSON, or another file type accepted by the REST API. When the user submits a YAML file, the CLI client converts to file to JSON format by default. Use the **Skip Pre-processing** field to disable this behavior.\n-   Password: Allows users to securely enter a password as input.\n **Note:** For File Input data types, the file size limit is 10 MB by default. However, you change this limit using the **glide.rest.scripted.max\\_inbound\\_content\\_length\\_mb** system property.\n\n</td></tr><tr><td>\n\nSkip Pre-processing\n\n</td><td>\n\nSet this flag to prevent the CLI client from converting YAML files into JSON format before sending them in the request. When **Data Type** is set to **File Input** and the user submits a YAML file, the CLI client converts the file to JSON before executing the command by default.**Note:** Only applies when **Data Type** is set to **File Input**.\n\n</td></tr><tr><td>\n\nDefault Value\n\n</td><td>\n\nDefault value to use when the user does not pass a value.\n\n</td></tr><tr><td>\n\nShort Description\n\n</td><td>\n\nRequired. Short description of the command argument. Used as help text when the user runs the `--help` command.\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nRead-only application scope for the argument.\n\n</td></tr><tr><td>\n\nCommand\n\n</td><td>\n\nRequired. Command that the argument applies to.\n\n</td></tr><tr><td>\n\nMandatory\n\n</td><td>\n\nWhen selected, the user must provide a value for the argument when running the associated command.\n\n</td></tr><tr><td>\n\nPrompt\n\n</td><td>\n\nPrompt to request information from the user. The CLI prompts for information when the user does not include a required argument in a command.\n\n</td></tr><tr><td>\n\nVisibility Expression\n\n</td><td>\n\nExpression used to determine whether the CLI should prompt for the argument. Typically used to display an argument based on the value provided to a previous argument.\n\n</td></tr><tr><td>\n\nOrder\n\n</td><td>\n\nOrder in which to prompt for the argument.\n\n</td></tr></tbody>\n</table>    4.  In the API Endpoint Arguments related lists, create any API endpoint arguments needed for the command.\n\n        Map command arguments from the Command Arguments related list to parameters in your REST endpoint.\n\n<table id=\"table_jqf_qnh_m4b\"><thead><tr><th>\n\nField\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nName\n\n</td><td>\n\nRequired. Name of the argument.\n\n</td></tr><tr><td>\n\nValue\n\n</td><td>\n\nRequired. The value from the command that you want to pass to the REST endpoint. You can pass a static value, or an expression such as `{flags.table}`. Use the `flags` global variable to access the command arguments.\n\n</td></tr><tr><td>\n\nParameter Type\n\n</td><td>\n\nRequired. The type of parameter in the REST endpoint that you want to pass the **Value** to. For example, if you select **Body**, the CLI passes the value of the **Value** field to the REST endpoint body. Options include:-   Body\n-   Header\n-   Path\n-   Query\n\n\n</td></tr><tr><td>\n\nApplication\n\n</td><td>\n\nRead-only application scope for the argument.\n\n</td></tr><tr><td>\n\nCommand\n\n</td><td>\n\nRequired. Command that the argument applies to.\n\n</td></tr></tbody>\n</table>    5.  In the Return Values related lists, create any return values needed for the command.\n\n        Create return values to only return certain keys from the response.\n\n        |Field|Description|\n        |-----|-----------|\n        |Path Expression|Required. Expression representing the path to the key that you want to return.|\n        |Alias|Variable name to assign the return value to.|\n        |Application|Read-only application scope for the command.|\n        |Command|Required. Command that the return value applies to.|\n\n\n## Result\n\nWhen the user runs the ServiceNow CLI command, the system executes the associated REST API call and returns the result to the ServiceNow CLI.\n\n**Parent Topic:**[ServiceNow CLI](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/application-development/servicenow-cli/servicenow-cli.md)\n\n"}}