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.
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
.
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).
Lists all the commands.
$ shoutem
Usage: shoutem [command] [-h]
Commands:
...
Prints out the CLI version.
$ shoutem -v
1.0.0
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.
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`!
Logs you out from the CLI.
$ shoutem logout
Successfully logged out.
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
andrestaurants
are just used as an example.
Run this command from the extension folder.
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.
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.
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.
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.
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).
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.
Installs selected platform to selected app. Options can also be left out and an interactive dialogue offers you a list of apps and platforms.
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.
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.
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.
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.
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.
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)
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
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.
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.
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:
shoutem configure --release
) and development (shoutem configure
) configurationshoutem configure --production
)$ shoutem configure
Starting build for app 8074
Run this command from the application folder.
Displays the username of current developer.
$ shoutem whoami
tom