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. If the extension folder is inside of a cloned app folder, it will also offer you to install the extension into that cloned app. Furthermore, if the extension is already published, it lets you choose it’s new version. If the extension is both published and installed, it will ask you whether or not you want to update the extension that’s installed in the app to the newly published version.

$ shoutem publish
WARNING: shoutem publish command is deprecated. Use shoutem extension publish instead
Checking the extension code for syntax errors... [OK]
? Version 0.0.2 is already published. Specify another version: 0.0.2
Building the server part... [OK]
Building the app part... [OK]
Packing extension... [OK]
Processing upload... [OK]
Uploading Restaurants extension to Shoutem... [OK]
Publishing restaurants version 0.0.2... [OK]
? Update the version used in the current app (tom.restaurants@0.0.1 => @0.0.2)? Yes
Success

Run this command from the extension folder.

  • shoutem extension publish <extension-name>

Publishes the named extension. It also offers you the choice whether or not you want to install the extension into the cloned app. Furthermore, if the extension is already published, it lets you choose it’s new version. If the extension is both published and installed, it will ask you whether or not you want to update the extension that’s installed in the app to the newly published version.

$ shoutem extension publish restaurants
Checking the extension code for syntax errors... [OK]
Building the server part... [OK]
Building the app part... [OK]
Packing extension... [OK]
Processing upload... [OK]
Uploading Restaurants extension to Shoutem... [OK]
Publishing restaurants version 0.0.1... [OK]
? Do you want to install tom.restaurants extension to the app 8074? Yes
Success

Run this command from any directory inside your cloned app.

  • 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 `Restaurants` 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 `Restaurants` 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 platform create [–url ]

When run from app folder, publishes a custom platform with all your non-extension (i.e. native) changes. Previously to the existence of this command, developers needed to use file anchors, but with this you can make any and all changes to everything in your app, including our core code.

It also offers you the choice whether or not you want to publish the platform and install the platform into the cloned app. You can also run it by giving it an –url parameter to an archived platform. For example, you can link to a tag archive in your github repository (needs to be public).

  • shoutem platform publish [–platform ]

Publishes the selected platform, making it visible to you in the Shoutem builder. Options can also be left out and an interactive dialogue offers you a list of platforms.

  • shoutem platform install [–app --platform ]

Installs selected platform to selected app. Options can also be left out and an interactive dialogue offers you a list of apps and platforms.

  • shoutem screen add <screen-name>

Adds a screen to the extension. Furthermore, it lets you choose whether or not the screen should also have a shortcut added to it, allowing it to be added to the app via the Builder as a screen via the Add Screen modal.

$ shoutem screen add List
? Screen name: List
? Create a shortcut (so that screen can be added through the Builder)? Yes
? Shortcut name: restaurants
? Shortcut title: Restaurants
? Shortcut description: A shortcut for List
...
Success

Run this command from the extension folder.

  • shoutem shortcut add <shortcut-name>

Adds a shortcut to the extension, either to a specific screen or a standalone shortcut that you can later connect a screen to.

$ shoutem shortcut add
? Shortcut name: MyShortcut
? Shortcut title: My Shortcut
? Shortcut description: A shortcut for WithoutShortcut
? Which screen would you like to connect with this shortcut? WithoutShortcut
...
Success!

In the example above, WithoutShortcut is a screen added with shoutem screen add that had no shortcut automatically made for it.

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 settings page to the extension. You can choose whether you want to create a React or HTML settings page and whether that page is a shortcut or extension settings page. It will even allow you to add a new screen and shortcut that the settings page is meant for.

$ shoutem page add
? Settings page type: react
? Settings page name: MyPage
? Settings page title: My Page
? This settings page controls settings for: an existing screen
? Select existing screen: List
...
Success

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 path\to\Restaurants
    react-native run-ios
To run your app on Android:
    cd path\to\Restaurants
    Have an Android simulator running or a device connected
    react-native run-android
  • shoutem extension add <extension-name>

Initializes, publishes and installs the app into the cloned app that you’re located in.

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

Title: Restaurants
Version: 0.0.1
Description: List of restaurants

Checking the extension code for syntax errors... [OK]
Building the server part... [OK]
Building the app part... [OK]
Packing extension... [OK]
Processing upload... [OK]
Uploading Restaurants extension to Shoutem... [OK]
Publishing restaurants version 0.0.1... [OK]
Installing it in your app... [OK]

Congratulations, your new extension is ready!
You might try doing cd relative/path/to/vladimir-vdovic.for-reference where you can:

  shoutem screen add
    add a new screen

  shoutem schema add <schemaName>
    add a new data schema

  shoutem theme add <themeName>
    add a new theme

  shoutem page add
    add a new settings page

Success!
Happy coding!

Run from any directory inside cloned app directory.

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

Run this command from the application folder.

  • shoutem whoami

Displays the username of current developer.

$ shoutem whoami
tom