Local Development

Command Line Interface Setup

Introduction

The Command Line Interface (CLI) is a tool that allows you to interact with the back4app platform via a terminal or command window. You can use CLI to:

  • Create a new app;
  • Deploy local files (e.g. Cloud Functions files);
  • Manage app releases;
  • Set the SDK version;
  • Deploy a web application;
  • Install NPM modules via package.json;

In this guide you will create a simple back4app app using the CLI and deploy your local Cloud Functions files.

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).

  • If you face any error during the installation, please try to add sudo in front of the command above.

Step 2 - Connect CLI with your back4app account

In order to connect your account with CLI you need to get the back4app account key. To obtain your account key, log into your account at back4app website and hover over the Hello, < username > button (top right).

Account Keys

  • 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.

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.

Go to your terminal and type b4a configure accountkey. 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 - Connect CLI with your back4app account

In order to connect your account with CLI you need to get the back4app account key. To obtain your account key, log into your account at back4app website and hover over the Hello, < username > button (top right).

Account Keys

  • 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.

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.

Go to your terminal and type b4a configure accountkey. 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 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

  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 - Deploy a Cloud Funtion

Let’s now create a Cloud Function on your local environment and then deploy it to your back4app connected app. First we need to create a local cloud code file called main.js and then deploy it using the CLI.

Cloud Code Function

  • The Cloud Code function is a tool that allows you to run a javascript function on back4app servers. Back4app executes your code once you call the function via GraphQL, RESTor SDK.

Go back to your CLI and then press ENTER to automatically create your local folder structure.

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)

To check your file structure go to your computer file system and navigate to /home/{USER}/{Name-App}. CLI has created 2 local folders. The first folder cloud contains your cloud functions files and was created with an initial main.js file. The second folder public will have your web application files. The final structure is shown 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.

To deploy your cloud and public folders to your connected back4app app hit the 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)

You have now a cloud function deployed and ready to be used. To check your functions go to your App Dashboard click on Cloud Code Functions menu inside the Core section.

To call your functions go to our Cloud Code Functions guide and choose the way that best fit your needs.

CLI full commands list

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

What to do next

As a next step we recommend you to install and explore the back4app local environment back4app local environment (Local Parse Server).

Conclusion

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