CLI - Command reference

The Freshworks Command-Line Interface (CLI) enables you to create, build, validate, test, and package apps to publish them in Marketplace.

To view the list of CLI commands, after you install the CLI, at the command prompt type fdk and press Enter.

❯ fdk
Usage: fdk [global-flag] [command] [command-flags] [arguments]

The Freshworks CLI enables you to build, test and publish apps on Freshworks Developer Platform

Options:
  -v, --version                    prints the current version
  -u, --skip-update-check          Skips daily check for new cli versions
  -d, --app-dir <directory>        directory is the path to the directory where
                                   the app will be created. If this option is
                                   not specified, the app will be created in
                                   the current directory.
  -h, --help                       display help for command

Commands:
  create [options]                 Creates a new app based on the specified
                                   options
  generate                         Generates configuration files for the app
  run [options]                    Runs the app on a local server for testing
  validate [options]               Validates the app code
  pack [options]                   Creates the app package that can be
                                   submitted to the Marketplace or published as
                                   a custom app
  version                          Displays the currently installed FDK version
                                   number
  search [options] [query-string]  Searches our developer community for a
                                   specified post
  test [options]                   Runs the unit tests that are saved as part
                                   of the (serverless) app files
  config [options]                 Allows to reconfigure local and global FDK
                                   configurations
  help [command]                   display help for command

ℹ For complete documentation please visit: https://freshworks.dev/ and navigate to the Documentation section.

Helpful options to know before using commands

The Freshworks CLI provides a set of options that allow you to get help, skip FDK update checks, and obtain detailed logs for a command.

Get help for CLI commands

The -h option displays information about a CLI command.

General syntax
fdk COMMAND [-h or --help]

Example

To view information about the usage of the create command, run the following command.

fdk create -h

Skip FDK update checks

When you run the Freshworks CLI commands, if no version update check has run in the last 24 hours, the FDK:

  1. Checks whether a new FDK version is available.
  2. If a new version is available and if you are not on the latest version, displays an update prompt that enables you to move to the latest version.
  3. Keeps track of the update check time.

To prevent the FDK from checking for version updates, you can use the --skip-update-check option, along with the CLI commands, as follows.

General syntax
fdk <-u or --skip-update-check> <COMMAND>

As a result of using the --skip-update-check option, the update prompt is not displayed.

Examples

  • To skip update checks while creating an app, run the following command.

    fdk --skip-update-check create

  • To skip update checks while running an app, run the following command.

    fdk -u run

Get detailed logs

To view detailed logs that pertain to a CLI command, run the following command.

NODE_DEBUG=fdk fdk COMMAND

Config

The command helps to work on environment configurations that must be set appropriately to enable successful app development.

General syntax
fdk config [action-name] [--scope <scope-level>] [key] [value]
OptionUsageDescription

action-name

Possible values: list, get, delete, set

General syntax
fdk config list
fdk config get <key>
fdk config delete <key>
fdk config set <key> <value>

Specifies the action to be performed on the configuration parameter.

Possible values:

  • list: Lists all configuration parameters that are set and their corresponding values as an object of key: value pairs.

  • get: Retrieves the specified configuration parameter and its corresponding value.

    Important:Only configuration parameters set through the set action can be retrieved by the get action. Default parameters (if not reset) cannot be retrieved using get.

  • delete: Deletes the specified configuration parameter.

  • set: Sets the specified value as the value of a configuration parameter identified by the <key> specified.

--scope

Valid only for set action

General syntax
fdk config set --scope <scope-level> <key> <value>

Specifies whether the environment setting is only for the current app being built or whether the setting is applicable to all apps that the developers can switch to.

Possible values of <scope-level>:

  • local
  • global

Default value of <scope-level>: local

Note:For any environment configuration, if a global scope and local scope is defined, the local scope takes precedence.

key

Not valid for list action.
Mandatory for get, delete, and set.

Example
fdk config delete request.timeout

Identifies the configuration parameter to be acted on. Ensure that through dotted notation, key specifies the exact child attribute, that is to be set, retrieved, or deleted.

For example, the config parameter request has a child attribute timeout. To get value of the timeout attribute, the corresponding command is,

fdk config get request.timeout

value

Valid only for set action.

Example
fdk config set request.timeout 20000

Specifies the value to be set for the configuration parameter identified by key.

Examples

  • List all the currently set (or default) configuration parameters and their values

    fdk config list

  • Retrieve the (reset) log.level configuration parameter value

    fdk config get log.level

  • Delete the request.timeout configuration parameter.

    fdk config delete request.timeout

Create

The command creates an app in the specified directory, based on the default app template. If no directory is specified, the app is created in the current directory.

Note:Ensure that the directory in which the app is to be created is empty.

General syntax
fdk create [--app-dir DIR] [--products PRODUCT] [--template TEMPLATE]
OptionUsageDescription

--app-dir

Or

-d

General syntax
fdk create --app-dir <DIR>

Or

fdk create -d <DIR>

<DIR> is the directory path to the project directory where the app is to be created through the fdk create command.

Example
fdk create -d /user/myFirstApp

Specifies the absolute or relative path of the project directory where the app is to be created.

If the option is not used with the create command, the app is created in the current directory.

--product

Or

-p

General syntax
fdk create --product <product>

Or

fdk create -p <product>

<product> is the name of the Freshworks product.

Example
fdk create -p freshdesk

Specifies the product for which the app is created.

If the option is not used with the create command, you’re prompted to select a product. Select freshdesk.

--template

Or

-t

General syntax
fdk create --template <template>

Or

fdk create -t <template>

<template> is the name of the template.

Example
fdk create -t your_first_app

Specifies the template for the app.

If not specified, you’re prompted to select a template.

Select your_first_app to create a front-end app and your_first_serverless_app to create a serverless app.

Examples

  • To create a Freshdesk app in the current directory, run the following command.

    fdk create --product freshdesk --template your_first_app

  • To create a Freshdesk app in the myfirstapp directory, run one of the following commands.

    fdk create --app-dir ./myfirstapp

    Or

    fdk create --app-dir /Users/user/myfirstapp

Generate

The command is used to generate app files with a specific template for an existing app that was created by using the create command.

  1. After you create an app, run the following command.

    fdk generate

    The list of the following files is displayed.

    • oauth_config.json: Contains the configuration parameters, such as client_id, client_secret, authorize_url, token_url, and account/agent scope, required for OAuth-based authentication.
    • iparams.json: Contains the installation parameters, such as iparam name and type of iparam, whose values are set when the app is installed.
    • iparams.html: Contains the html code to build the Custom Installation page. You can enter the page title, select the product CSS to link, and choose to add JQuery, fresh_client.js, iparam.js and iparam.css.
    • server.js: Contains the event registration and callback methods. You need to enter the names of the events and callback functions.
    • manifest.json: Contains app information such as version, product, location, and so on. You need to select the product and app location.

  2. Select a file and enter the appropriate parameter values. The corresponding file is generated based on the values.

Run

The command starts the local server, deploys the app project on the server, and enables you to test the app.

Command
fdk run [--app-dir DIR]
OptionUsageDescription

--app-dir

Or

-d

General syntax
fdk run --app-dir <DIR>

Or

fdk run -d <DIR>

<DIR> is the directory path to the folder containing the app that is tested locally through the fdk run command.

Example
fdk run -d /user/myFirstApp

Specifies the directory path to the folder that contains the app that is tested locally.

--skip-validation

Or

-V

General syntax
fdk run --skip-validation <Validation-type>

Or

fdk run -V <Validation-type>

<Validation-type> is the type of validation check that is skipped

Example
fdk pack -V lint

Skips specific validation checks. The errors associated with the validation, if any, are not displayed when the app is tested locally.

After testing, press Control + C to stop the server. A code coverage summary that indicates the extent of testing is displayed. A coverage summary that indicates extensive testing is as follows.

========= Coverage summary ==========
    Statements   : 98.18% ( 54/55 )
    Branches     : 100% ( 4/4 )
    Functions    : 84.62% ( 22/26 )
    Lines        : 98.18% ( 54/55 )
======================================

Note:When apps are submitted for the app review process, ensure that in the coverage summary, the coverage of each component is at least 80%.

Configure timeout when running an app

The fdk config command enables you to set the request timeout time in milliseconds, which determine when a Request Method call times out during local testing.

SyntaxExample
fdk config set request.timeout <timeout in milliseconds>fdk config set request.timeout 20000

This command adds or updates the request.timeout attribute with the given value in the .fdk/configs.json file of your app. Once the attribute is set, use the fdk run command to run the app.

Important:
  • The valid values for the timeout are 15000, 20000, 25000, and 30000, with 15000 being the default value.
  • If you specify any value for timeout other than these, it defaults to 15 seconds, and a warning message is displayed.
  • If you don’t specify a timeout value, it defaults to 15 seconds.

Examples

  • To deploy the app project located in the current directory, run the following command.

    fdk run

  • To deploy the app project located in the myfirstapp directory, run the following command.

    fdk run --app-dir /Users/user/myfirstapp

    The output is the same as that from the previous example.

Validate

Note:Ensure to install or update to the latest FDK version.

The command validates whether the app code is error free. If there are errors in the code, corresponding violations are displayed after the command is run.

General syntax
fdk validate [--app-dir DIR] [--fix]
OptionUsageDescription

--app-dir

Or

-d

General syntax
fdk validate --app-dir <DIR>

<DIR> is the directory path to the folder containing the app files that are validated for errors.

Example
fdk validate -d /user/myFirstApp

Specifies the directory path to the folder that contains the app that is validated.

--fix

Or

-f

General syntax
fdk validate --fix
Example
fdk validate -f -d /users/myFirstApp

When validating an app, the option fixes all lint errors for which auto-fix support is available.

--skip-validation

Or

-V

General syntax
fdk run --skip-validation <Validation-type>

<Validation-type> is the type of validation check that is skipped

Example
fdk pack -V lint

Skips specific validation checks. The errors associated with the validation, if any, are not displayed when the app is tested locally.

The latest FDK version requires Node.js 14 or later versions. If you run the fdk validate command to validate an app built using an earlier (major) Node.js version and if your current Node.js runtime environment is 14 or later, the FDK displays a warning message and a prompt asking whether you want to continue. If you continue with the validation, the FDK:

  1. Deletes the existing coverage folder. The folder contains the results of the fdk run command that is used to set up the local server and test an app.
  2. Deletes the node_modules folder. The folder contains the npm dependencies (specified in manifest.json) that are installed when the fdk run command is run.
  3. Includes or updates the engines attribute in manifest.json. The updated engines.node and engines.fdk values reflect the Node.js and FDK versions on which the app is validated.

After a successful validation, ensure to retest the app by using the fdk run command. The retesting generates the coverage folder and the coverage summary that is required to pack your app for submission.

If there is a minor Node.js version mismatch between the version used to build the app and the current Node.js runtime version, the FDK automatically updates manifest.json > engines.node to reflect the Node.js version on which the app is validated.

Pack

Note:Before packing, ensure to validate the app; resolve all Node.js version mismatch issues, if any.

The command creates an app package file that can be submitted for the app review process.

General syntax
fdk pack [--app-dir DIR]
OptionUsageDescription

--app-dir

Or

-d

General syntax
fdk pack --app-dir <DIR>

<DIR> is the directory path to the folder containing the app files that are packed for Marketplace review.

Example
fdk pack -d /user/myFirstApp

Specifies the directory path to the folder that contains the app that is packed.

--skip-validation

Or

-V

General syntax
fdk pack --skip-validation <Validation-type>

<Validation-type> is the type of validation check that is skipped.

Example
fdk pack -V lint

Skips specific validation checks. The errors associated with the validation, if any, are not displayed when the app is packed.

--skip-coverage

Or

-s

General syntax
fdk pack --skip-coverage

Skips code coverage of an app.

Important:The code coverage of an app should be at least 80%. Using this option allows you to package the app even if the code coverage is less than 80%. While you may use this option for testing an app, avoid using it when packaging the app for submission to the Freshworks Marketplace. If your app does not meet the 80% code coverage requirement and you use this option during packaging, your submission to the Freshworks Marketplace will be rejected.

The command displays the Node.js and FDK versions that are used when packing the app.

After you run the fdk pack command, a dist/<app_directory>.zip file is generated. To submit the app and get it published to Marketplace, upload the generated file to the Freshdesk developer portal.

Examples

  • To pack the app files located in the current app project directory, run the following command.

    fdk pack

  • To pack the app project files located in the myfirstapp directory, run the following command.

    fdk pack --app-dir /Users/user/myfirstapp

Version

The command displays the installed and latest CLI version numbers.

fdk version

The search command searches our developer community for all content relevant to the specified query-string (search phrase) and lists the links to the content. If the search finds appropriate WIKI articles, the articles are listed first and then other relevant content in the community are listed.

General syntax
fdk search [query-string]

Example

To search for content related to the serverless app, run one of the following commands.

fdk search Serverless app

Or

fdk search "Serverless app"

Test

The FDK includes a testing framework (currently in beta) to help test serverless apps. This enables you to write and maintain unit tests as part of app files. The test command runs these unit tests.

Command
fdk test

For information on how to use the testing framework and the output of the test command, see the Testing Framework documentation.