Shoutem CLI

Shoutem Command Line Interface (CLI) is a tool that helps you build extensions. Using it, you can create extensions, generate code snippets, upload extensions to your Shoutem account and install them on your apps.

Installation

Download and install Shoutem CLI through npm, the package manager for Node.js.

$ npm install -g @shoutem/cli

If the previous command fails because of permission issues, you need to run it with sudo permission: sudo npm install -g @shoutem/cli.


In case you don’t have npm installed, the best way to install it is with installing Node.js, which includes npm.

Commands

Here is the list of available commands with their arguments and flags. Some of the arguments and flags are not documented, which we only found useful for the Shoutem team internally (they can still be seen when using help commands).

  • shoutem

Lists all the commands.

$ shoutem
Usage: shoutem [command] [-h]

Commands:
...
  • shoutem [--version|-v]

Prints out the CLI version.

$ shoutem -v
1.0.0
  • shoutem <cmd> [--help|-h]

Every command’s description and arguments list can be invoked using -h flag. So for example, the command shoutem init -h prints usage info for the init command and shoutem screen add -h prints usage info for the shoutem screen add command:

$ shoutem init -h

Usage: shoutem init <extension-name>

Create a scaffold of all files and folders required to build an extension.
  • shoutem login

Authenticates you as a developer. Enter your Shoutem credentials. If you’re not a Shoutem user yet, sign up here.

$ shoutem login
Enter your Shoutem credentials (obtained at https://builder.shoutem.com):
E-mail: tom@shoutem.com
Password: ********

Each Shoutem user can become a Shoutem developer. If you’re not a developer yet, you’ll be prompted to create a developer name after entering your credentials.

Enter new developer name:
Name: tom
You are registered as `tom`!
  • shoutem logout

Logs you out from the CLI.

$ shoutem logout
Successfully logged out.
  • shoutem init <extension-name>

Initializes an extension project.

$ shoutem init restaurants
Enter information about your extension. Press `return` to accept (default) values.

Title: Restaurants
Version: 0.0.1
Description: List of restaurants
...
Extension initialized!

After initialization, your extension folder structure will look as follows:

tom.restaurants/
  ├ app/
  |  ├ node_modules/
  |  ├ extension.js
  |  ├ index.js
  |  └ package.json
  ├ server/
  |  ├ node_modules/
  |  └ package.json
  └ extension.json

Note

tom and restaurants are just used as an example.

Run this command from the extension folder.

  • shoutem push

Pushes extension to Shoutem server.

$ shoutem push
Uploading `Restaurants` extension to Shoutem...
Success!

As long as extension is not published, every push will overwrite current development version of extension. Once you publish extension, that version of extension will be unchangeable and you will be able to push only higher version numbers.

Run this command from the extension folder.

  • shoutem publish

Publishes extension to Shoutem server.

$ shoutem publish
Publishing `Restaurants` extension to Shoutem...
Version `0.0.1` is successfully published!

Run this command from the extension folder.

  • shoutem install [--new [<restaurant-name>]] [--app <app-id>]

Installs extension to the app. If no flags or arguments are passed, the CLI will offer an interactive menu.

$ shoutem install
Select app to install your extension:
> RestaurantsApp
  --------------
  Create a new app

Pass a flag --new to install it on a new app.

$ shoutem install --new Restaurants
Installing `Restaurnats` extension to the new app...
Extension successfully installed to the new app. Check it here:
https://builder.shoutem.com/app/8074

Also, you can install it on specific a app by providing an app ID. To find out ID of the app, go to Settings and scroll down to Advanced information section of the App info.

$ shoutem install --app 8074
Installing `Restaurnats` extension to `Restaurants` app...
Extension successfully installed to the app. Check it here:
https://builder.shoutem.com/app/8074

Installation can be done through Builder as well by going to the Extensions tab in the sidebar, clicking on the + button next to Extensions to open the Extension Marketplace and then selecting the My extensions tab.

  • shoutem screen add <screen-name> [--shortcut <shortcut-name>]

Adds a screen to the extension.

$ shoutem screen add List
Screen `List` is created in file `app/screens/List.js`!
File `app/extension.js` was modified.
File `extension.json` was modified.

Pass the --shortcut option with the shortcut’s name as a value to create a screen and connect it with a new shortcut in extension.json.

$ shoutem screen add List --shortcut List
Enter shortcut information:
Title: List

Screen `List` is created in file `app/screens/List.js`!
Shortcut `List` is created!
Shortcut `List` opens `List` screen.
File `app/extension.js` was modified.
File `extension.json` was modified.

Run this command from the extension folder.

  • shoutem shortcut add <shortcut-name>

Adds shortcut to the extension.

$ shoutem shortcut add List
Enter shortcut information:
Title: List
Shortcut `List` is created!
File `extension.json` was modified.

Run this command from the extension folder.

  • shoutem schema add <schema-name>

Adds a data-schema to the extension.

$ shoutem schema add Restaurants
Schema `Restaurants` is created in file `server/data-schemas/Restaurants.json`!
File `extension.json` was modified.

Run this command from the extension folder.

  • shoutem page add <page-name>

Adds a page to the extension.

$ shoutem page add HelloPage
Page `HelloPage` is created in `server/pages/HelloPage` folder.
File `extension.json` was modified.

Run this command from the extension folder.

  • shoutem theme add <theme-name>

Adds a theme to the extension.

$ shoutem theme add Argo
Theme `Argo` is created in file `app/themes/Argo.js`.
Variables for the theme are created in file `server/themes/ArgoVariables.json`
File `extension.json` was modified.
  • shoutem show

Shows the currently logged in user and their Shoutem home directory.

$ shoutem show
Registered as `tom`.
Home directory: `/path/to/.shoutem` (customizable through SHOUTEM_CLI_HOME env variable)
  • shoutem clone [<app-id>]

Clones a complete app project which includes the Shoutem platform and all extensions installed in the app (you can see them in Extensions tab in the Builder). Useful for running and figuring out the details of how a complete Shoutem app works, and to help you understand how extension code integrates with the app itself. The command will create a directory with the same name as the app being pulled, with spaces being replaced with underscores. The directory will have an extensions directory containing the source code of all extensions installed in the given app.

$ shoutem clone
Select your app: Restaurants (8074)
Pulling the app `Restaurants`...
Cloning `Restaurants` to `Restaurants`
Done.

To run your app on iOS:
    cd C:\Users\ikatun\Desktop\test\Restaurants
    react-native run-ios
To run your app on Android:
    cd C:\Users\ikatun\Desktop\test\Restaurants
    Have an Android simulator running or a device connected
    react-native run-android
  • shoutem pack

Packs the extension. This command is used by shoutem push and with it, you can check how your extensions looks like when it’s pushed to Shoutem servers.

$ shoutem pack
Extension is packed at: ~/restaurants.tgz

Find the extension packed in the root of the extension folder.

By default, shoutem pack command will do npm run build in both app and server folder, which is performed also on shoutem push. If you don’t want to get the pack without building it, use shoutem pack --nobuild (not documented flag).

Run this command from the extension folder.

  • shoutem configure [–release] [–production]

Runs the platform’s configure script to sync the local app with native changes to local extensions. The flag --release bundles the downloaded configuration, so that the app doesn’t download it on every start. The flag --production is used to configure the app’s bundle ID for iOS and Android to match the one provided in the Builder. It also activates the code push feature, analytics and push notifications. The --production configuration automatically sets the release flag in config.json.

Furthermore, you can customize the bundle ID for your app via the iosBundleId and androidApplicationId properties in the config.json file in the cloned app’s root directory. These settings override the Builder defined values.

The command should be called when:

  • new extension is created, installed to the current app & pushed
  • changing native code of any of the extensions from the extensions/ directory
  • changing cocoapods or gradle dependencies of any of the extensions from the extensions/ directory
  • switching between published (shoutem configure --release) and development (shoutem configure) configuration
  • preparing app for manual building and publishing (shoutem configure --production)
$ shoutem configure
Starting build for app 

Run this command from the application folder.

  • shoutem whoami

Displays the username of current developer.

$ shoutem whoami
tom