Back4App

Setup Command Line Interface to Parse Server

Introduction

The Command Line Interface (CLI) text-based interface tool provides commands for interacting with the Back4App Platform via a terminal or command window. The CLI can be used to perform various actions, for example:

  • Create a new app;
  • Develop and deploy Cloud Code Functions;
  • Manage app releases;
  • Set the SDK version;
  • Deploy a Full-stack web application;
  • Install an NPM module via package.json;

This guide is an introduction to the Command Line Interface. Our main goals here are to:

  1. Create a new app at Back4App;
  2. Deploy and run a simple cloud function that returns a Hello World.

Everything is done with the CLI.

Goal

  • To install and setup CLI in your terminal;
  • To use CLI to create a new app at Back4App;
  • To use CLI to connect to an existing app;
  • To use CLI to deploy Cloud Code Functions and files.

    For information about Cloud Code Function, please click here.

Prerequisites

To complete this tutorial, you will need:

  • A Back4App account created.

Configuring Command Line Interface

To manage your apps at Back4App, you need to install the Command Line Interface in your operational system.

Select the appropriate tab to start the installation:

Step 1 - Install Back4App CLI

In Mac OS X and Linux/Unix environments, install the Back4App Command Line Tool by running the following command:

curl https://raw.githubusercontent.com/back4app/parse-cli/back4app/installer.sh | sudo /bin/bash

This installs a tool named “b4a” to class=/usr/local/bin/b4a. This is the only file in this location.

If you want to uninstall this tool, just delete that file. This will also update your command line tool (if you already have it).

Step 2 - Get Account Key

Connect your CLI tool with your Back4App account. Account keys are personal access tokens that can be used to create a new Back4App app, and list properties and keys for the given Back4App app.

Step 2.1

To obtain your account key, log into your account at Back4App Website and hover over the Hello, < username > button (top right).

Step 2.2

Click on Account Keys:

You can find existing keys or create a new one. All you need to do is to write your key name (1) and click on ‘+’ (2) to save this to your key list.

Step 2.3

Go to your terminal and type b4a configure accountkey.

Step 2.4

Paste the key you created previously and press Enter.

$ b4a configure accountkey

Input your account key or press ENTER to generate a new one.
NOTE: on pressing ENTER we'll try to open the url:
  "http://dashboard.back4app.com/classic#/wizard/account-key"
in default browser.
Account Key: ${ACCOUNT_KEY}
Successfully stored account key for: "your configured email".
$

This command will only work for the first time you do this setup in a specific computer. Otherwise, run b4a configure accountkey -d to overwrite your old key with a new one.

The account keys you’ve used are stored in ${HOME}/.back4app/netrc for Mac and Linux.

If your account is not properly connected using an account key, you’ll need to login with your Back4App credentials every time you run a deploy command. To avoid this situation run this step again. If this does not work check this file to make sure you are using the account key you selected in your Back4App account.

Step 1 - Install Back4App CLI

The Command Line Interface for Windows is available here. You need to download b4a.exe file.

Then you need to copy and paste that executable to C:\windows\system32, so that b4a becomes executable by the command line.

Note: this is not an installer, it is just a plain Windows executable.

Step 2 - Get Account Key

Connect your CLI tool with your Back4App account. Account keys are personal access tokens that can be used to create a new Back4App app, and list properties and keys for the given Back4App app.

Step 2.1

To obtain your account key, log into your account at Back4App Website and hover over the Hello, < username > button (top right).

Step 2.2

Click on Account Keys:

You can find existing keys or create a new one. All you need to do is to write your key name (1) and click on ‘+’ (2) to save this to your key list.

Step 2.3

Go to your terminal and type b4a configure accountkey.

Step 2.4

Paste the key you created previously and press Enter.

$ b4a configure accountkey

Input your account key or press ENTER to generate a new one.
NOTE: on pressing ENTER we'll try to open the url:
  "http://dashboard.back4app.com/classic#/wizard/account-key"
in default browser.
Account Key: mFUszlwnM6OIt3j0vCZiP6Ic3wNgpACzzXqXm5Ec
Successfully stored account key for: "your configured email".
$

This command will only work for the first time you do this setup in a specific computer. Otherwise, run b4a configure accountkey -d to overwrite your old key with a new one.

The account keys you’ve used are stored in C:\Users\yourName\.back4app\netr for Windows.

If your account is not properly connected using an account key, you’ll need to login with your Back4App credentials every time you run a deploy command. To avoid this situation run this step again. If this does not work check this file to make sure you are using the account key you selected in your Back4App account.

Step 3 - Create a new Back4App App

To create a new app:

  1. Open your terminal and type the command: b4a new

  2. Type (n) and choose the app name.
    Please see the commands printed on your terminal below:

$ b4a new
Would you like to create a new app, or add Cloud Code to an existing app?
Type "(n)ew" or "(e)xisting": n
Please choose a name for your Parse app.
Note that this name will appear on the Back4App website,
but it does not have to be the same as your mobile app's public name.
Name: CLI-Back4App

Step 4 - Connect to an existing App (Optional)

  1. Open your terminal and type the next command: b4a new.

  2. Type (e) and select the number for the name of the application you want to configure:

$ b4a new
Would you like to create a new app, or add Cloud Code to an existing app?
Type "(n)ew" or "(e)xisting": e
1:  CLI-Back4App
2:  Live Query
3:  MyApp2
Select an App to add to config: 3
Please enter the name of the folder where we can download the latest deployed
Cloud Code for your app "MyApp2"
Directory Name: (Enter)

Step 5 - Create locally a sample Cloud Code Function file

The main objective at this stage is to run a Cloud Code Function on your connected app. The Cloud Code function is a tool that allows you to run a NodeJS function in Back4App Cloud. Back4App executes your code once you call the function via the API or via SDK.

The first step to run a cloud function is to deploy it. At this point, you have two possible paths: create a blank or a sample cloud code function directory. In this guide, we’ll choose to create a sample cloud code directory.

Awesome! Now it's time to set up some Cloud Code for the app: "CLI-Back4App",
Next we will create a directory to hold your Cloud Code.
Please enter the name to use for this directory,
or hit ENTER to use "CLI-Back4App" as the directory name.

Directory Name: (Enter)
You can either set up a blank project or create a sample Cloud Code project
Please type "(b)lank" if you wish to setup a blank project, otherwise press ENTER: (Enter)

Step 6 - Check your files and directory structure

This sample directory structure includes a main.js file that contains the function we will call in the next step. To check your file structure go to your computer file system and navigate to /home/{USER}/{Name-App}. Check that the final structure is listed below:

// Use Parse.Cloud.define to define as many cloud functions as you want.
// For example:
Parse.Cloud.define("hello", (request) => {
  return "Hello world!";
});

The created directory looks like this:

├── CLI-Back4App/
│  ├── cloud/
│  │   ├── main.js
│  ├── .parse.local
│  ├── .parse.project
│  ├── public/
│  │

Where .parse.local and .parse.project are config files that store application info and project level info, respectively. The cloud directory stores your Cloud Code. Also in that directory, you’ll typically be editing main.js, which stores all of your Cloud Code functions. The public directory stores any static content that you want to host on Parse.

The powerful CLI enables us to deploy our flies and folders to Back4App with a single command. b4a deploy:

$ b4a deploy
Uploading source files
Uploading recent changes to scripts...
The following files will be uploaded:
/Users/{USER}/CLI-Back4app/cloud/main.js
Uploading recent changes to hosting...
The following files will be uploaded:
/Users/{USER}/CLI-Back4app/public/index.html
Finished uploading files
New release is named v1 (using Parse JavaScript SDK v2.2.25)

Step 7 - Check your deployed code at Back4App

You have now a cloud function ready to call at your BAck4App app. To view this function on Back4App, navigate to your App Dashboard and mouse over the Cloud Code Functions menu inside the Core section.

Step 8 - Calling your Cloud Code Function

Go to your terminal again and execute the following cURL command:

curl -X POST \
 -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
 -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
 -H "Content-Type: application/json" \
 -d "{}" \
 https://parseapi.back4app.com/functions/hello

You’ll receive the following response:

Now you have achieved the main goals set out in this guide.

To learn more about what is possible to do with CLI, see the additional step below

Step 9 - Commands available at Back4App CLI (Extra)

To better understand CLI’s full potential you can run the help command on your terminal. It lists all the commands available at Back4App CLI (as shown below):

$ b4a help
Parse Command Line Interface
Version 3.1
Copyright 2018 Parse, Inc.
http://parse.com

Usage:
  parse [flags]
  parse [command]

Available Commands:
  add         Adds a new Parse App to config in current Cloud Code directory
  cloud       Call cloud code function
  configure   Configure various Parse settings
  default     Sets or gets the default Parse App
  deploy      Deploys a Parse App
  develop     Monitors for changes to code and deploys, also tails parse logs
  download    Downloads the Cloud Code project
  functions   List Cloud Code functions and function webhooks
  generate    Generates a sample express app in the current project directory
  help        Help about any command
  jssdk       Sets the Parse JavaScript SDK version to use in Cloud Code
  list        Lists properties of given Parse app and Parse apps associated with given project
  logs        Prints out recent log messages
  migrate     Migrate project config format to preferred format
  new         Adds Cloud Code to an existing Parse app, additional can create a new Parse app
  releases    Gets the releases for a Parse App
  rollback    Rolls back the version for the given app
  symbols     Uploads symbol files
  triggers    List Cloud Code triggers and trigger webhooks
  update      Updates this tool to the latest version
  version     Gets the Command Line Tools version


Flags:
  -h, --help   help for parse

Use "parse [command] --help" for more information about a command.

After you created some apps, it is important to start managing them. The next tabs, include some commands that help you succeed at this task:

The command b4a list shows a list of all the apps connected to your Back4App account. If this command is executed inside a directory created by the b4a new, it will also list the apps associated with Cloud Code in the current directory. The output appears as follows:

$ b4a list
The following apps are associated with Cloud Code in the current directory:
* CLI-Back4App

These are the apps you currently have access to:
1:  Back4AppTest
2:  B4A
3:  B4AApp
4:  CLI-Back4App

You can add a new Back4App app to config the current Cloud Code directory by simply running:

$ b4a add
1:  Back4AppTest
2:  B4A
3:  B4AApp
4:  CLI-Back4App
Select an App to add to config: 2
Written config for "B4A"

By using the b4a add command, you will have some apps running in the same directory, which may cause hassles when using other commands, like having to put the name of the app in the end of the command (like this b4a deploy < appname >). Fortunately, our CLI stores the default app to avoid this problem. To change the default app, simply type:

$ b4a default CLI-Back4App
Default set to CLI-Back4App
$ b4a default
Current default app is CLI-Back4App

Conclusion

Congratulations, now you can manage your applications via the terminal!

If you encounter any error, or need any help to configure the Command Line Interface, please contact our Support Team by chat.