Introduction

Catalyst CLI enables you to set up and work with the project components that you did not initialize during the project initialization. You can set up the client and the functions directories from the CLI at any time while working with the project.

This feature is very convenient if you did not initialize the functions package during the project initialization, or if you initialized an empty project, and then later need the functions component to be added to your application. You can set up the functions directory with one function, and later on add more functions to it as per your needs. You can learn more about Catalyst functions from the Functions help page.  

When a Java or a node function is initialized or set up, the dependent files and the configuration files are added automatically to the function's folder by Catalyst. Therefore, it is advisable to create Catalyst functions either using the CLI or the Catalyst console. This allows for the boilerplate code of the dependency files to be added properly in the standard project directory structure. The updated information about the function component will also be added to the catalyst.json file when you set it up.

You can also launch a node shell for testing, executing, and debugging Catalyst functions locally from the CLI after you code them. The CLI also enables you to delete the deployed functions. We will discuss each of these CLI commands in this help page.

Set Up Functions

1. You can set up the functions directory in your project by navigating to your project directory and executing the following command in your CLI:
    

   $ catalyst functions:setup

   
   The procedure is the same as initializing the functions directory during the project initialization. 
2. Select the type of function you would like to develop and press Enter.
   
   The five types of functions that you can develop in Catalyst are: Basic I/O, Advanced I/O, Event, Cron, and Integration functions. To learn more about the function types and their purposes, refer to the Functions help page.
   
   Integration Functions:
   
   The CLI initialization process is the same for all the other function types, except the Integration functions. If you select Integration from the list, you have to perform these two extra steps before moving on to the next step:
    
   1. Select the service that you want to integrate with. You can currently only select Cliq integration.
      
   2. Select the handlers that you require. You can learn more about this from the Integration Functions help page.
      
      The rest of the setup process is the same for all function types. The process only varies with the function stack.
3. Select a stack to develop the server side functions in and press Enter. The list displays all supported runtimes. You can select the latest supported version of either Java or Node.js from the list.
    
   Note: You can include both Java and Node.js functions in a single function directory using the catalyst functions:add command.
   
   Set Up a Java Function of Any Type
   
   
   1. If you are setting up a Java function, enter the reference name of the Java function when prompted and press Enter. This will also be the name of the function's folder.
      
   2. Provide the main class name of the Java function and press Enter. The CLI will then download the Java SDK package and complete the functions setup process.
      
   The Java function's folder will be created with the main .java class file, the library JAR files, catalyst-config.json, and other configuration files. These values will be updated in the catalyst.json configuration file.
   
   You can learn about the Java function directory structure in detail from the Project Directory Structure help page.
   
   Set Up a Node.js Function of Any Type
   
   
   1. If you are settting up a Node.js function, provide a package name for your Node function when prompted and press Enter.
      
   2. Enter the name of the entry point file and press Enter.
      
   3. Enter a name for the function author and press Enter.
      
   4. The CLI will then prompt you to allow installation of node dependencies. Press Y to confirm the installation, and press Enter to confirm your choice. If you don't install all the required dependencies, it could cause errors during the function's execution.
      
      The CLI will then download the Node.js SDK package and complete the function setup process.
       
      Note: Catalyst enables you to create an Advanced I/O Node.js function in the Express template, which installs the Express.js modules. However, you will not be able to create the Express template from the CLI. But you can install Express on your system independently by executing npm install express --save from a particular function's directory to use the Express modules in it. You can learn more the Express template from the Advanced I/O Function help page.
   The Node function's directory is now set up with the .js main function file, catalyst-config.json, and the necessary node modules and configuration files if you installed the dependencies. These values will be updated in the catalyst.json configuration file.
   
   You can learn about the Node.js function directory structure in detail from the Project Directory Structure help page.

You can now work on the function that you set up. You can code the function by uploading the package to the Catalyst console, and working on it using the online editor in the console or by another editor of your choice. You can also use the functions shell to test and execute the function's code, and then deploy it to the console.

Add Functions

You can add any number of new functions of both the Java and Node.js stacks in the functions directory, after you have initialized or set up the first function for your project. Each new function will be created in its own directory inside the functions directory.

You can add a new function in your functions directory by executing the following command from your project directory:

$ catalyst functions:add

The procedure is the same as initializing or setting up a function. Refer to the previous section for details.

Once the function is added, an individual folder will be created for it in the functions directory along with its dependencies and configuration files, as mentioned in the previous section.

Configure Function Memory

Catalyst enables you to configure the memory for each of your functions. This memory will be allocated when the function is executed. You can choose a memory between 128 MB to 512 MB for any function.

The default memory assigned to a function is 256 MB. That is, if you don't configure the memory, or if you had created a function before this feature was made available, the memory would be set to 256 MB automatically.

You can modify this value for any of your existing functions as per your requirements in the following way:

1. Execute the following command from your function's project directory.

   $ catalyst functions:config

   
   The CLI will list all the functions you have created in your project, along with information of their current memory allocation.
2. Select one of the functions to configure, and press Enter.
   
3. Select the memory to allocate to the function from the available options, and press Enter.
   
   The memory configuration for the function will be updated.
   

You can also directly configure a function's memory by specifying the function's name or ID along with the command like:

$ catalyst functions:config[function_name_or_id]

For example:

$ catalyst functions:config Generate_Invoice

The CLI will then ask you to select a memory configuration in the same manner.

Configure Function Memory Options

You can also directly specify the memory you want allocated for a specific function using the --memory <value> option for the catalyst functions:config command, followed by the function's name or ID.

This can be done in the following way:

$ catalyst functions:config [--memory <value>] [function_name_or_id]

For example, if you want to allocate 128 MB memory for a function named MailOrder, then execute the following command:

$ catalyst functions:config --memory 128MB MailOrder

The CLI will ask you for confirmation. Enter Y and press Enter.

The memory configuration for the function will be updated.

Launch a Shell for Functions

The functions shell offers you the capabilities of a Node.js shell console combined with the efficiency of Catalyst CLI, to test and debug your functions.

Using the Catalyst CLI functions shell, you can test and debug the following types of functions of both Java and Node.js platforms in your project: Basic I/O, Cron, Event, and Integration functions.

The output of a function's execution is fetched and displayed in the CLI in the JSON format. For a Basic I/O function, the String output is generated in the CLI, and for the other function types, the appropriate responses are fetched.

While testing a Basic I/O function, you can also attach a debugger to the function's endpoint and test its code through a local server, or enable the HTTP mode for it in the shell. Catalyst CLI also provides several other options for the functions shell, that we will discuss later on in this section.

To launch a shell for testing a function, navigate to the project directory of the function and execute the following command:

$ catalyst functions:shell

This opens the shell in the CLI. You can test any function in your project other than Advanced I/O functions, pass inputs and execute it in case of a Basic I/O function, and perform other node shell operations on it.

You can pass inputs to a Basic I/O function the shell in two ways:

• Pass values to the function variables and run the function.
• Declare a variable in the CLI, assign it to a function variable, and pass the input values through the declared variable. You can then bind the declared variable to that function and execute it.

An Example for Passing Direct Input:

Let's test a simple function called EMI, which allows you to pass an input value for a variable called principal. This function then calculates the EMI amount for a shipment service, based on some pre-defined constant values.

We pass a value for the input variable and execute the EMI function in the shell by entering the following statement:

functions> EMI({"principal":"10000"})

This invokes the function EMI and passes the input to its variable. Once the function execution is complete, the output is obtained from the server as a JSON response. The CLI displays the function's output along with the HTTP status code as sent by the server.

An Example for Declaring a Variable and Binding it:

You can also declare a variable in the CLI and assign it to the variable in the function. This will allow you to use the declared variable in the place of the function's variable and pass input values to it easily.

Let's declare a variable 'P', assign it to the principal variable in the EMI function, and pass an input value. This can be done by executing the following command in the shell:

functions> var P={"principal":"3000"}

This assigns P to principal and passes the input value of 3000 to P. You can verify if the variable is assigned by printing the value of P in the console. 

This can be done using the Node.js function console.log() in the following manner:

functions> console.log(P)

If the variable was assigned and the value was passed successfully, the shell will print the value of the value of principal that was passed.

You can now bind the declared variable to the function and execute it as follows:

functions> EMI(P)

This invokes the function and passes the input to its variable through P. Once the function execution is complete, the CLI will display the output along with the HTTP status code as sent by the server.

The CLI will return the appropriate HTTP response codes from the server if runtime errors occur.

You can exit the functions shell by killing the terminal command based on your local environment or by executing the following command:

functions> .exit

Once your function is tested thoroughly, you can deploy the function from the local environment to the remote console. 

Functions Shell Options

There are four options that you can use with the functions shell launch command.

--http [port]

The --http option invokes your Basic I/O function in the HTTP mode. The CLI serves your function through a local host, and provides you the access to its local endpoint. The server will be listening to the port where the function is hosted locally, and the CLI will display a live log of the activities at the port. The CLI will then open the functions shell where you can test your function.

This option is similar to the functionality of the catalyst serve command that serves Basic I/O functions, Advanced I/O functions, and the client components locally.

You can start a function shell in the HTTP mode and test all the Basic I/O functions in a project, by executing the following command from the project directory:

$ catalyst functions:shell --http

This will host all the Basic I/O functions in the functions directory of the project locally, in the default port 8080. The CLI will display the endpoint URLs of all the functions. You can access these functions by opening the URLs in your browser at any time while performing the shell operations.

You can now test and run your functions as discussed in the previous section using the shell, and view them in HTTP mode by accessing their URLs.

You can also start the server in a different port if you require while, and override the default port 8080. This can be done by specifying the port number with the --http option.

For example, if you prefer to use the port 7000, execute this command from the project directory:

$ catalyst serve --http 7000

--debug [port]

Catalyst enables you to test your functions locally with a remote debugger attached to the live localhost server. 

When you use the --debug option and start the functions shell, Catalyst will listen for the transport dt_socket at the default or custom port and will wait for the connection from the debugger to be established after invoking the function. Once the connection is established, the attached debugger will debug the execution of your function and identify any errors and issues in its code.  

You can start your functions shell and initiate the connection to the debugger by executing the following command from the project directory:

$ catalyst functions:shell --debug

This will open the functions shell in the same way as before. When you invoke the function in the shell, Catalyst will establish the connection to the debugger. Catalyst CLI will allocate port 8000 for the debugger by default.

Once the debugger is attached, the CLI will display a message to indicate this fact. Catalyst will then execute your function in the debugging mode and display the server response.

You can override the default port 8000 and start the debugger in a different port, if required. This can be done by specifying the port number with the --debug option.

For example, if you prefer to use the port 7000, execute the following command from the project directory:

$ catalyst serve --debug 7000

--ignore-scripts

This option allows you to inform Catalyst to ignore the pre- and post-lifecycle scripts written in the catalyst.json file for a particular function. 

Since you can host and access Basic I/O function endpoints using the --http option in the functions shell, the preserve and postserve scripts are executed automatically when they are hosted. The preserve script executes before the function is served, and the postserve script executes after you exit the local serve, if available.

You can inform Catalyst to ignore these pre- and post-lifecycle scripts when the functions are served using the --ignore-scripts option.

For example, let's configure the catalyst.json file of a project to include the following preserve and postserve scripts for a function.

If you launch the functions shell without using the --ignore-scripts option, the scripts will be executed before the shell opens and after you exit the shell respectively as shown below.

To ignore the preserve and postserve scripts, launch the functions shell by executing the following command from your project directory:

$ catalyst functions:shell --ignore-scripts

This will ignore the scripts and run the shell in the standard manner.

--no-watch

Catalyst CLI enables a live watch mode in the functions shell by default. This mode actively watches for changes made in the function file or the function directory after the shell is opened. When it detects changes committed in the function file or the function directory, it enables a hot reload of the functions shell to reflect the updates live. You will therefore be able to access the updated version of the function in the live shell immediately after the changes are saved, without having to re-compile or re-serve the code.

You can disable this default watch mode by launching the functions shell using the --no-watch option, as shown below:

$ catalyst functions:shell --no-watch

Now if you make any changes to the function file after you have launched it in the shell, the updates will not be reflected in the compiled function open in the shell. You can work with the updated version of the function either by re-invoking the function after the changes are made, or by exiting the shell and re-opening it.

For example, let's consider a function that contains the default sample code of a Node.js Basic I/O function. It prints the message "Hello from index.js" when it is invoked in the functions shell.

If you make changes to the function's code as shown below, these updates are not reflected live in the CLI while the function is still open in the shell.

You will need to invoke the function again to get the output for the updated code.

However, if you don't use the --no-watch option and launch the functions shell with the default watch mode enabled, the shell will detect the changes made in the code live and perform a hot reload of the function automatically, as shown below.

Delete Functions

You can permanently delete functions of your Catalyst project using the CLI. You can choose to delete functions from the remote console or from your local project directory while executing this command.

1. To delete functions in your project, execute the following command from your project directory:

   $ catalyst functions:delete

2. The CLI will ask you to choose between the functions in the remote console or the functions in your local project directory. Select an option and press Enter.
   
3. The CLI will list all the functions in your remote console or in your local directory, based on the options you chose. Select the functions that need to be deleted and press Enter.
   
4. The CLI will ask for a confirmation. Enter "Y" to and press Enter to confirm. The selected functions will be deleted from the chosen location.
   

You can also directly specify the function to be deleted by including the function's name or ID with the along with the command like:

$ catalyst functions:delete [function_name_or_id]

For example:

$ catalyst functions:delete InvoiceFetch

The CLI will then prompt you to select between the remote console or the local directory, then ask you for the delete confirmation in the same manner.

Delete Functions Options

You can directly choose to list the functions in either the remote console or in your local project directory to delete using the respective options.

To list functions available in your local project directory, execute the catalyst functions:delete command as follows:

$ catalyst functions:delete --local

To list functions available in the remote console of your project, execute the catalyst functions:delete command as follows:

$ catalyst functions:delete --remote

The CLI will list the functions accordingly, and you can delete the required functions as explained previously.

You can also directly delete a function from the remote console or the local directory as shown below:

$ catalyst functions:delete InvoiceFetch --remote