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 Shoutem team internally (they can still be seen with 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 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 Shoutem developer. If you still are not a developer, after you entered correct credentials, you’ll be prompted a new developer name.

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

Logs you out from CLI.

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

Initializes extension project.

$ shoutem init example
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:

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

Run this command from 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 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 extension folder.

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

Installs extension to the app. If no flags or arguments are passed, CLI will offer 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 app by providing app ID. To find out ID of the app, go to Settings and scroll down to Advanced informations.

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

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

Adds 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 --shortcut option with shortcut name as value, to create a screen and connect it with new shortcut in extension.json.

$ shoutem screen add List --shortcut List
Enter shorcut 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 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 extension folder.

  • shoutem schema add <schema-name>

Adds 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 extension folder.

  • shoutem page add <page-name>

Adds 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 extension folder.

  • shoutem theme add <theme-name>

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

Connects local extension to the app for local development. An extension must be shoutem push-ed and installed in the app (using either the https://builder.shoutem.com or shoutem install command) prior to running the shoutem link command.

Note

A linked extension does not have to be pushed on every change because linked extensions are used directly from your computer. Only a single push and installation of extension is necessary. To get the change new changes, reload the simulator.

$ shoutem link
Extension successfully linked. Please, kill the packager before running the app.

Run this command from extension folder.

Counterpart to the shoutem link. Disconnects local extension from your app. This will cause the next run to pull the extension code directly from the Shoutem server instead of using the extension located in the current directory.

$ shoutem unlink
Unlink successful. Please, kill the packager before running the app.

Run this command from extension folder.

  • shoutem unlink --all is used to unlink all of the currectly linked extensions. It’s simply a shortcut for going through each linked extension one by one. You don’t have to run this command from extension folder.

Note

If you delete extension directory or change the path to the directory, that extension will automatically get unlinked.

  • shoutem show

Shows currently logged user and list of linked extensions.

$ shoutem show
Signed in as `tom`.
Linked extensions:
  `restaurants` - ~/tom/extensions/restaurants
  • shoutem run [<app-id>] [--dev] [--local] [--small]

Executes React Native packager locally to run and debug custom or existing extensions using Shoutem Preview app (available for iOS and Android) on both Android and iOS without having to setup Android Studio and/or XCode. Moreover, you can use Windows to develop iOS apps. The only 2 things you would need to run the app are react-native-cli and Node.js v7. See our FAQ if you have problems setting this up.

$ shoutem run
Select your app: Restaurants (8074)
...
http://shoutem.app.link/?host=df4d8960.ngrok.io&port=80&dev=false
`Printed QR code`

If app-id is ommited, command lists all user’s apps for selection.

You can scan the QR code containing the app url using Shoutem Preview app (available for iOS and Android) or any other QR code reader. Regular QR code reader should open or install the Shoutem Preview app, which will automatically open the requested app.

Upon reading the QR code, Shoutem Preview will connect to your computer and embed the JS code within itself. You can now see how your app behaves and feels on a real device without ever having to build or pull the native code. By default, shoutem run bundles the release build (See Building your app for production.

shoutem run --dev If you want to debug your extensions using this method, you should first link them using shoutem link command and then use the --dev flag with shoutem run. This will create debug build. The app performance will be a bit slower, but this will allow you to use Chrome/Safari/Firefox debug tools.

shoutem run --local By default, React Native packager is tunneled through [ngrok]((https://ngrok.com/). Use --local flag if you are connected with your smartphone to the same network as your computer. This will allow Shoutem Preview app to fetch the JS bundle directly from your computer, which will reduce the delay in refreshing code changes. Also, your computer must be able to open 8081 port. This might require manual configuration of your computer’s firewall settings.

shoutem run --small Creates a smaller QR code. Useful if you don’t like resizing the terminal, but sometimes has troubles rendering with some terminal fonts.

Note

Using shoutem run to preview your app on the device, your extensions can’t include any native code. Reason behind this is that you can’t change the native code on the fly. If your extension has native functionalities, use shoutem run-ios or shoutem run-android.

  • shoutem run-ios []

Runs application with app-id ID locally on the iOS simulator or your device connected with a cabel. Setup iOS environment for React Native before.

$ shoutem run-ios
Select a device: iPhone 6
Select your app: Restaurants (8074)
Running `Restaurants` app on `iPhone 6` simulator...
...

If app-id is ommited, command lists all user’s apps for selection.

shoutem run-ios --mobileapp <mobile-platform-path> allows you to run your own version of shoutem platform instead of the official one selected in settings > platform settings. This is useful for modifying or debugging the platform itself. Shoutem’s platform source can be cloned from https://github.com/shoutem/platform. By default, shoutem run-ios bundles the debug build.

shoutem run-ios --release creates a release build without debug information. This mode allows to see how the app performs in the real world but turns off both debugger tools and code reload feature.

shoutem run-ios --device "<my iPhone device name>" skips the device selection menu and runs the app on the physical device.

shoutem run-ios --simulator "iPhone 4s" skips the device selection menu and runs the app on the selected simulator.

  • shoutem run-android []

Runs application with app-id ID locally on the Android emulator. Setup Android environment for React Native before.

$ shoutem run-android
Select a device: TestDevice
Select your app: Restaurants (8074)
Running `Restaurants` app on `TestDevice` simulator...
...

If app-id is ommited, command lists all user’s apps for selection.

shoutem run-android --mobileapp <mobile-platform-path> allows you to run your own version of shoutem platform instead of the official one selected in settings > platform settings. This is useful for modifying or debugging the platform itself. Shoutem’s platform source can be cloned from https://github.com/shoutem/platform. By default, shoutem run-android bundles the debug build.

shoutem run-android --release creates a release build without debug information. This mode allows to see how the app performs in the real world but turns off both debugger tools and code reload feature.

shoutem run-android --device "<my android device name>" runs the app on the selected android (either a physical or simulated) device.

  • shoutem build-android [<app-id>]

Builds an android app for production. The app being built does not have to be published via Shoutem builder. Application is built using current design configuration, i.e. release configuration is ignored if app is published via Shoutem builder. The build-android command generates .apk file within the current working dir. Generated apk file can be installed on an Android device or submitted to Google Play Store.

If app-id argument is ommited, a list of all user’s applications is displayed for selection.

We prepared a tutorial on how to publish your app.

shoutem build-android --mobileapp <path to local shoutem platform code> creates a build using local version of shoutem app code which can be cloned from here. This option overrides the Shoutem app’s platforms settings and forces the local mobile app.

  • shoutem build-ios [<app-id>]

Builds an iOS app for production. The app being built does not have to be published via Shoutem builder. Application is built using current design configuration, i.e. release configuration is ignored if app is published via Shoutem builder. The build-ios command generates .ipa file and xarchive directory within the current working dir. Generated ipa file can be installed on an iOS device or submitted to Apple Store.

If app-id argument is ommited, a list of all user’s applications is displayed for selection.

We prepared a tutorial on how to publish your app.

shoutem build-ios --mobileapp <path to local shoutem platform code> creates a build using local version of shoutem app code which can be cloned from here. This option overrides the Shoutem app’s platforms settings and forces the local mobile app.

$ shoutem pull-app
Select your app: Restaurants (8074)
Pulling the app `Restaurants`...
Pulling extensions...
Change your working directory to `Restaurants`


- ##### shoutem pull-app [\<app-id>]

Downloads a complete app project which includes [Shoutem platform](https://github.com/shoutem/platform) and all extensions installed in the app (you can see them in `Extensions` tab in the Builder. Helpful for figuring out the details of how complete app works and to help you understand how is extension code integrated with the app itself. The command will create a directory with the same name as the app being pulled. The directory will have a `extensions` directory containing the source code of all extensions installed in the given app.

```ShellSession
$ shoutem pull-app
Select your app: Restaurants (8074)
Pulling the app `Restaurants`...
Pulling extensions...
Change your working directory to `Restaurants`

If app-id is ommited, list of all user’s apps is displayed for selection.

  • 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

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 extension folder.

  • shoutem whoami

Displays the username of current developer.

$ shoutem whoami
tom

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