Back4App

Setup Command Line Interface to Parse Server

Introduction

The Command Line Interface (CLI) is a tool which provides commands for interacting with Back4App Platform via terminal or command window. In other words, it’s a text-based interface, that is used to operate commands at our platform. The CLI can be used to perform various actions like:

  • To create a new app;
  • To develop and deploy Cloud Code Functions;
  • To manage app releases;
  • To set the SDK version;
  • To deploy an Full-stack web application;
  • To install an NPM module via package.json;

This guide is an introduction to Command Line Interface. Our main goal here will be to create a new Back4App App and after that deploy and run a simple cloud function that returns a Hello World, everything using CLI. If you don’t know what is Cloud Code Function please click here.

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.

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. You just need to select the right tab to start the installation:

Step 1 - Install Back4App CLI

In Mac OS X and Linux/Unix environments, you can install the Back4App Command Line Tool by running this 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. There’s no other junk, so to uninstall, just delete that file. This will also update your command line tool if you already have it.

Step 2 - Get Account Key

This second step consists of 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. To obtain your account key, log in to your account at Back4App Website and hover the Hello, < username > button in the top right, then click on Account Keys:

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

Now, go to your terminal, type b4a configure accountkey, paste your key create 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, you should run b4a configure accountkey -d to overwrite your old key with a new one.

The account key 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 have to login with your Back4App credentials every time you run a deploy command. To avoid that please run this step again and if didn’t work check this file to make sure you are using the same account key 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

This second step consists of 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. To obtain your account key, log in to your account at Back4App Website and hover the Hello, < username > button in the top right, then click on Account Keys:

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

Now, go to your terminal, type b4a configure accountkey, paste your key create 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, you should run b4a configure accountkey -d to overwrite your old key with a new one.

The account key 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 have to login with your Back4App credentials every time you run a deploy command. To avoid that please run this step again and if didn’t work check this file to make sure you are using the same account key selected in your Back4App account.

Step 3 - Create a new Back4App App

Now, let’s start to create a new app, open your terminal and type the command: b4a new, then 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 a existing App (Optional)

Open your terminal and type the next command: b4a new. Then 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 goal here is to run a Cloud Code Function on your connected App. Cloud Code function is a tool that let you run a NodeJS function in Back4App Cloud. Back4App executes your code once you call the function via API or via SDK. The first step to run a cloud function is to deploy it. Let’s see how to do it now. 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 strucure comes with a main.js file that contains the function we are going to call in the next step. To check your file structure you can go to your computer filesystem and navigate to /home/{USER}/{Name-App}. Check the final structure below:

// Use Parse.Cloud.define to define as many cloud functions as you want.
// For example:
Parse.Cloud.define("hello", function(request, response) {
  response.success("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.

Now its time to use the CLI power. We are going to deploy our flies and folders to Back4App with a single command. The 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

Awesome! You have now a cloud funciton ready to call at your BAck4App App. To view that on Back4App navigate to your App Dashboard and then click over Cloud Code Functions menu inside Core section.

Step 8 - Calling your Cloud Code Function

Now its time to call the function. Go to your terminal again and then execute the cURL command bellow:

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 see the following response:

Now you have concluded the main goals for this guide. If you want to know more about what is possible to do with CLI please see the extra step bellow:

Step 9 - Commands available at Back4App CLI (Extra)

To better understand the CLI full potential you can run the help command on your terminal. After that all the commands available at Back4App CLI will be listed, 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. At the next tabs, you will go through some commands that will help you succeed at this task:

The command b4a list will show a list of all apps connected to your Back4App account. If this is executed inside a directory created by the b4a new, it will also list the apps that are associated with Cloud Code in the current directory. The output looks like the following:

$ 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 are able to manage your applications via the terminal! It seems like you’ve followed this tutorial and all the steps splendidly. If you are facing any error or need any help to configure the Command Line Interface on your computer, please contact our Support Team by chat.