@appsemble/cli

Appsemble CLI

Manage apps and blocks from the command line.

Table of Contents

• Installation
• Usage
  • Development server
  • Authentication
  • Organizations
  • Apps
  • Blocks
  • Teams
  • Assets
  • Resources
  • Cronjobs
• License

Installation

npm install @appsemble/cli

Usage

A full list of functionalities can be achieved by running the following command:

appsemble --help

Every subcommand also supports the --help flag.

Development server

The development server can create an app from a specified folder containing an app-definition.yml file. It will check what blocks are needed for the app and will try to load them from the local workspaces, listed in the package.json file in the root of the project, if they are present. This way, all default Appsemble blocks shipped with Appsemble are loaded automatically.

Once the development server is started, making a change to a block’s code or styles will reflect in the browser immediately after refreshing the page, without the need of increasing the block’s version. Running docker database containers, creating a user account and creating an organization are not needed.

The Appsemble CLI can be used to start the development server. For example, the following command serves my-app:

appsemble serve <path-to-app-directory>

This will serve the app on http://localhost:9090.

A different port can be specified with the --port parameter.

The following option allows you to view the app with a specified role:

appsemble serve <path-to-app-directory> --user-role test

The following option allows you to view the app as a Manager of a team:

appsemble serve <path-to-app-directory> --team-role Manager

App data is stored within a db.json file in your machine’s cache directory. Each app has their own directory <my-app>.

MacOS - /Users/<my-name>/Library/Caches/appsemble/<my-app>
Linux - /home/<my-name>/.cache/appsemble/<my-app>
Windows - C:\Users\<my-name>\AppData\Local\appsemble\Cache\<my-app>

App assets will be served from the local file system.

The development server will automatically fetch all blocks that are needed for the served app but are missing from the local workspaces. These are typically third-party or proprietary blocks. The development server will use http://localhost:9999 as the default remote server to fetch blocks from. The following option allows you to specify a different remote (e.g. https://appsemble.app):

appsemble serve <path-to-app-directory> --remote <remote>

The development server will use the corresponding block directory in your machine’s cache directory to store and read block manifests and assets.

MacOS - /Users/<my-name>/Library/Caches/appsemble/blocks/<organisation>/<block-name>/<block-version>
Linux - /home/<my-name>/.cache/appsemble/blocks/<organisation>/<block-name>/<block-version>
Windows - C:\Users\<my-name>\AppData\Local\appsemble\Cache\blocks\<organisation>\<block-name>\<block-version>

You can overwrite the existing block cache with the following option:

appsemble serve <path-to-app-directory> --remote <remote> --overwrite-block-cache

Authentication

The Appsemble CLI uses OAuth2 client credentials to authenticate to the Appsemble server.

To login, run the following command and follow the instructions in the output:

appsemble login

To logout, run the following command and select the client credentials to remove:

apsemble logout

The Appsemble CLI also supports authentication using the APPSEMBLE_CLIENT_CREDENTIALS environment variable. This is mostly useful for automation.

Organizations

The Appsemble CLI can be used to create and update organizations. For example:

appsemble organization create my-organization --name 'My Organization' --icon icon.png

Apps

The Appsemble CLI allows you to bootstrap an Appsemble app into a standard Appsemble project layout. The command is followed by a series of interactive questions. You can also pass the values as arguments.

appsemble app create

The Appsemble CLI can be used to create, export, import and update apps. For example, to create an app in the apps/my-app directory, run:

appsemble app publish apps/my-app

Similarly, to update an app using an app directory, run the following command:

appsemble app update --id <app-id> <path/to/updated app>.

If you want to update settings for an app, run the following command:

appsemble app patch --id <app-id>

Use --help flag with the above command to view the supported arguments.

---

🛈NOTE

The app patch command supports updating the locked property of an app, locked property is updated before other properties. If you set the locked property to fullLock, any other changes won’t be applied unless you are using --force flag.

---

To delete an app using the CLI use the following command:

appsemble app delete --id <appId>

To export an app as a zip file, run the following:

appsemble app export --id <app-id>

Supported arguments for this command are resources, assets and path. Resources is used to specify whether to include the resources in the exported file, the same can be applied to assets and path is the path of the folder where you want to put your downloaded file. The default path is ./apps, and resources and assets are by default false.

To import an app from a zip file, use the following command:

appsemble app import <path-of-zip-file> --organization <organizationId>

For a more in depth explanation of how to build apps, use our app building guide.

Blocks

The Appsemble CLI allows you to bootstrap an Appsemble block into a standard Appsemble project layout. The command is followed by a series of interactive questions.

appsemble block create

The Appsemble CLI can also be used to publish and delete (although we don’t recommend doing it in production) Appsemble blocks. For example, to publish all blocks in the blocks directory, run:

appsemble block publish blocks/*

or to publish a single block located in some other directory, run

appsemble block publish path/to/block/directory

Blocks can be deleted if they are not in use by any apps. To delete a block, run

appsemble block delete <block-name:block-version>

Organization id can be passed as an argument(default for which is “appsemble”).

To know more about the block related commands, run

appsemble block --help

Building blocks uses Webpack. To use this, install the additional dependencies webpack and @appsemble/webpack-config

npm install webpack@webpack-4 @appsemble/webpack-config

For a more in-depth explanation of how to build apps, use our block development guide.

Teams

The Appsemble CLI can be used to manage teams for apps. For example, the following command creates a new team named My Team:

appsemble team create 'My Team' --app-id 1 --context development

Assets

The Appsemble CLI can be used to upload assets from disk. For example, the following command creates an asset named example-asset:

appsemble asset publish --app-id 1 path/to/example-asset.png

Resources

The Appsemble CLI can be used to create a resource from a JSON file or directory:

[
  {
    "title": "My Resource",
    "description": "This record is an example."
  }
]

appsemble resource publish --app-id 1 --context development --app path/to/my-app my-resource path/to/resources/my-resource.json

appsemble resource publish --app-id 1 --context development --app path/to/my-app my-resource path/to/resources/*

And resources can also be updated when they contain an id in the JSON file.

[
  {
    "id": 1,
    "title": "My Updated Resource",
    "description": "This will be the updated content of the first my-resource record."
  }
]

appsemble resource update --app-id 1 --context development --app path/to/my-app my-resource path/to/resources/*

Cronjobs

The Appsemble CLI can be used to run app cronjobs. The following command runs all cronjobs that were scheduled to run in the past 5 minutes:

appsemble run-cronjobs

How often jobs are run (more accurately how far back the job can be scheduled for it to run) the time interval (in minutes) can also be set with:

appsemble run-cronjobs --interval 30

License

LGPL-3.0-only © Appsemble

Changelog

[0.29.9] - 2024-08-22

Added

• Block(detail-viewer): Add support for video asset thumbnails.
• Block(form): Add support for automatic thumbnail generation on video inputs.
• Block(list): Add support for displaying a thumbnail image if a video asset is passed to the image property.
• Node-utils: Add support for thumbnail assets in processResourceBody.
• Server: Add a controller for asset by id HEAD requests.
• Server: Validate imported messages on server side.
• Utils: Add an API path for asset by id HEAD requests.

Changed

• Block(list): Change the request for assets in the header to HEAD.
• Studio: Only export changed translations.

Fixed

• Block(detail-viewer): Don't pass poster if there is no thumbnail link.
• Server: Use correct permission for asset delete permission verification.
• Server: Verify permissions for creating assets.