Form.io CLI Tool

Introduction

The Form.io Command Line Interface tool (CLI) allows you to quickly bootstrap a fully operating project and interface with the Form.io API server. To see the source code behind this tool, check out the Open Source project on Github @ https://github.com/formio/cli.

Project API keys are required within the settings of your source and destination projects.

Installation

Installation is easy... Simply type the following in your command line.

npm install -g @formio/cli

Commands

Migrate

formio migrate <source> [<transformer>] <destination> --src-key [SOURCE_API_KEY] --dst-key [DESTINATION_API_KEY]

The migrate command allows you to migrate submission data from one source to another using a simple command. You can either migrate data from a CSV into a form, or from a form into another form. This works by taking the data from <source>, sending it through a middleware function called <transformer> (which you provide) that transforms the data into the correct format, and then saving that data as a submission into the <destination> form. If you are migrating data from one form to the same form within two different projects, you will just provide form as your transform and your command would be as follows.

formio migrate <source> form <destination> --src-key [SOURCE_API_KEY] --dst-key [DESTINATION_API_KEY]

As an example, if you wish to move submission data from one form in a project to your remotely deployed project. You can use the following command.

formio migrate https://myproject.form.io/myform form https://formio.mydomain.com/myproject/myform --src-key abc1234 --dst-key cde2468

Where you would replace the domains of your from and to, but also need to replace the src-key and dst-key with the API Keys from the from project and API key of your destination project respectively.

Migrating an entire project

You can also migrate an entire project by using the "project" transform as follows.

formio migrate https://myproject.form.io project https://forms.mydomain.com/myproject

Migrating from CSV

In many cases, you may wish to migrate data from a local CSV file into a project submission table. This requires the transform middleware where you will map the columns of your CSV file into the Submission data going into Form.io.

Example: Let's suppose you have the following CSV file of data.

import.csv

First Name, Last Name, Email
Joe, Smith, [e-mail]
Jane, Thompson, [e-mail]
Terry, Jones, [e-mail]

And now you wish to import all of that data into a form. You can create the transform file like the following.

transform.js

var header = true;
module.exports = function(record, next) {
  if (header) {
    // Ignore the header row.
    header = false;
    return next();
  }
  next(null, {
    data: {
      firstName: record[0],
      lastName: record[1],
      email: record[2]
    }
  });
};

This transform middleware file can be a complete Node.js middleware method and works asynchronously so if you need to perform asynchronous behavior, you can do that by only calling the next function when the record is ready.

You can now migrate that data into your form with the following command.

formio migrate import.csv transform.js https://myproject.form.io/myform --key [YOUR_API_KEY]

Here is the list of all the options you can provide to the migrate command:

Option	Description
-p, --protocol [protocol]	Change the protocol
-h, --host [host]	Set the host for the migrate
--key [key]	The API Key to provide to the destination forms
--src-key [key]	The API Key to provide to the source forms
--dst-key [key]	The API Key to provide to the destination form
--username [username]	The destination username to authenticate with
--src-username [username]	The source username to authenticate with
--dst-username [username]	The destination username to authenticate with
--password [password]	The destination password
--src-password [password]	The source password
--dst-password [password]	The destination password
--start-with [startWith]	Start the migration from a specific form. Useful to replay migrations
--delete [delete]	Deletes all submissions in the destination from before the migration occurs
--delete-previous [deletePrevious]	Deletes previous submissions that have been migrated with the migrate script
--delete-after [deleteAfter]	Provides the ability to delete submissions created in the Source after the provided timestamp. The timestamp should be in the format of 2022-05-30T12:00:00.000Z. Use with --delete-before to create a delete "window"
--delete-before [deleteBefore]	Provides the ability to delete submissions created in the Before after the provided timestamp. The timestamp should be in the format of 2022-05-30T12:00:00.000Z. Use with --delete-after to create a delete "window"

Clone

formio clone <source_db|source_api> <destination_db> --src-project=[PROJECT_ID]

Clones a project from one database or an API into another database, and includes all forms, submissions, and every other resources within the project. This command also retains any _id's from the source database. If you specify the API as source make sure to pass the --api-source option.

Clone Submissions

formio clone -o <source_db|source_api> <destination_db> --src-project=[PROJECT_ID]

This command only clones the submissions from one environment to another.

Here is the list of cli options you can use with the clone command:

Option	Description
--api-source	Allows to clone from API (make sure to pass this option if you specify API as source)
-p, --protocol [protocol]	Change the protocol
-h, --host [host]	Set the host for the clone
--deleted-after [timestamp]	Only clone items deleted after the provided UNIX timestamp
--created-after [timestamp]	Only clone items created after the provided UNIX timestamp
--modified-after [timestamp]	Only clone items modified after the provided UNIX timestamp
-a, --all	Include All items (including deleted items) Default: false
-o, --submissions-only	Only clone the submissions within a project Default: false
-f, --delete-submissions	Delete all submissions on the receiving form before cloning Default: false
-s, --src-project <project_id,...>	The Source project ID, or comma separated projects for multiple
-d, --dst-project <project_id>	The Destination project ID
-p, --project <project_id>	The project ID that you wish to clone from one database to another
--src-ca <source_ca>	The TLS certificate authority for the source mongo url
--src-cert <source_cert>	Allows you to provide the TLS certificate file for connections
--dst-ca <destination_ca>	The TLS certificate authority for the destination mongo url
--dst-cert <destination_cert>	Allows you to provide the TLS certificate file for connections

Deploy

formio deploy [src] [dst]

You can deploy a project on a paid plan on form.io to a hosted server with this command. Specify the source and destination servers and the project will be created or updated on the destination server.

Examples:

// A project without a server is implied from https://form.io
formio deploy myproject http://myproject.localhost:3000

// Projects can be specified with a subdomain.
formio deploy https://myproject.form.io http://myproject.localhost:3000

// Projects can also be referred to with their project id which will need to be looked up.
formio deploy https://form.io/project/{projectId} http://localhost:3000/project/{projectId}

Each server will require authentication so you will be asked twice, once for the source and once for the destination. These can also be specified with --src-username, --src-password, --dst-username, --dst-password.

The full list of options that can be used with the deploy command:

Option	Description
-p, --protocol [protocol]	Change the protocol
-h, --host [host]	Set the host for the deploy
--key [key]	The API Key to provide to the destination forms
--src-key [key]	The API Key to provide to the source form
--dst-key [key]	The API Key to provide to the destination form
--username [username]	The destination username to authenticate with
--src-username [username]	The source username to authenticate with
--dst-username [username]	The destination username to authenticate with
--password [password]	The destination password
--src-password [password]	The source password
--dst-password [password]	The destination password

Copy

formio copy [type] [src] [dest]

This command will copy the components of a form or resource into another form or resource. This will overwrite all components within the destination form if that form exists. You can also chain together multiple source forms which will aggregate the components of those forms into the destination form.

Ensure the Read Form Definition permission access of your source form is set correctly to authorize the command.

Examples:

// Copy a form from one project to another.
formio copy form https://myapp.form.io/mysourceform https://myotherapp.form.io/mydestform  --src-key myapikey --dst-key myapikey

// Copy a resource from one project to another.
formio copy resource https://myapp.form.io/mysourceresource https://myotherapp.form.io/mydestresource --src-key myapikey --dst-key myapikey

// Aggregate multiple forms into the same form.
formio copy form https://myapp.form.io/form1,https://myapp.form.io/form2 https://myapp.form.io/allforms --src-key myapikey --dst-key myapikey

Here is the list of options you can use with the copy command:

Option	Description
-p, --protocol [protocol]	Change the protocol
-h, --host [host]	Set the host for the copy
-k, --key [key]	The API Key to provide to the destination forms
--src-key [key]	The API Key to provide to the source form
--src-admin-key [key]	The Admin API Key to provide to the source form
--dst-key [key]	The API Key to provide to the destination form
--dst-admin-key [key]	The Admin API Key to provide to the destination form
--username [username]	The destination username to authenticate with
--src-username [username]	The source username to authenticate with
--dst-username [username]	The destination username to authenticate with
--password [password]	The destination password
--src-password [password]	The source password
--dst-password [password]	The destination password

Submissions

formio submissions <source> [each]

You can output the submissions of the source form to the terminal or make every submission pass through the each middleware.

Examples:

// List all form submissions
formio submissions --username [e-mail] --password 12345 --key myApiKey https://myapp.form.io/myform

// middleware.js
const middlewareFunc = (submission, index) => {
 // Do something with submission
};
module.exports = middlewareFunc;

// Pass every submission through middleware
formio submissions --username [e-mail] --password 12345 --key myApiKey https://myapp.form.io/myform path/to/middleware.js 

Here is the list of options you can use with the submissions command:

Option	Description
-p, --protocol [protocol]	Change the protocol
-h, --host [host]	Set the host for the submissions
--key [key]	The API Key to provide to the destination forms
--username [username]	The destination username to authenticate with
--password [password]	The destination password