# 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**](https://github.com/formio/cli). {% hint style="info" %} [**Project API keys**](https://help.form.io/userguide/projects/project-settings#api-settings) are required within the settings of your source and destination projects. {% endhint %} ## Installation Installation is easy... Simply type the following in your command line. ``` npm install -g @formio/cli ``` ## Commands ### Migrate ``` formio migrate [] --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 ``, sending it through a middleware function called `` (which you provide) that transforms the data into the correct format, and then saving that data as a submission into the `` 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 form --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, joe@example.com Jane, Thompson, jane@example.com Terry, Jones, terry@example.com ``` 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 --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 --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 \ | The Source project ID, or comma separated projects for multiple | | -d, --dst-project \ | The Destination project ID | | -p, --project \ | The project ID that you wish to clone from one database to another | | --src-ca \ | The TLS certificate authority for the source mongo url | | --src-cert \ | Allows you to provide the TLS certificate file for connections | | --dst-ca \ | The TLS certificate authority for the destination mongo url | | --dst-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. {% hint style="info" %} Ensure the [**Read Form Definition**](https://help.form.io/developers/roles-and-permissions#submission-data-permissions) permission access of your source form is set correctly to authorize the command. {% endhint %} **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:
OptionDescription
-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 [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 user@example.com --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 user@example.com --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 |