Skip to main content

Version 3.1.x

Legacy Process

The information here applies only for Showpad Apps v1 (deprecated). While your existing v1 Showpad Apps will continue to work, we strongly recommend:

The Experience App CLI is Showpad's command line tool to help you build Showpad Apps.

It allows you to run specific commands to:

What's new​

Version 3.1.x of the Experience App CLI is packed with powerful commands within the apps namespace. These commands are designed to streamline and enhance your management and control of custom-developed applications within the Showpad platform.

The apps namespace allows you to run specific commands to::

  • Upload: Seamlessly upload your app to Showpad, ensuring a smooth deployment process.
  • Status: Gain into the current status of your app upload, making it easy to track progress and identify any issues.
  • Versions: Quickly retrieve a comprehensive list of all available versions of your app, enabling you to keep track of updates and enhancements.
  • List: Obtain detailed information about all your registered apps in one go, facilitating effective app portfolio management.
  • Assign: Assign a specific version of your app to one or more Showpad organizations, streamlining the distribution process and ensuring the right app versions reach the intended audience.

Upgrade to Showpad CLI Version 3.1.0 now and experience the benefits of these powerful additions to your app management toolkit.

Compatibility​

The Experience App CLI is compatable with the following environments (Node.js 15+):

  • GNU/Linux
  • macOS
  • Windows
INSECURE ORIGINS

Safari doesn't accept WebSocket connections from insecure origins (the Experience App CLI), preventing the Development Proxy App from working. We highly recommend using other browsers to open the Development Proxy App while developing your app on Safari.

Installation​

Installation of the Experience App CLI is done during the Development phase with the following command:

npm install @showpad/experience-app-cli -D

Available Commands​

The following is a description of the available commands that you'll use during the development phase.

tip

You can use the --help option on every command to get more information about the command and its available options.

init​

This command initializes the app by verifying and/or creating required files. It does not set the Showpad access credentials (use the auth command instead).

npx experience-app-cli init

Available Options​

auth​

This command generates a credentials file in the .showpad directory. This allows you to configure multiple profiles.

npx experience-app-cli auth

Available Options​

tip

If you run the command without specifying a profile, the access credentials you provide will be saved as the 'default' profile.

sync​

You can synchronize the manifest.json version from the package.json file. This is helpful when working with Semantic Versioning.

npx experience-app-cli sync
tip

To use Semantic Versioning to update the version of your app, run the following command with the increment type. Git tags are created by default.

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

bundle​

This command creates a .showpad bundle by checking required files and bundling a folder. It defaults to the current working directory.

npx experience-app-cli bundle

Available Options​

Source Files

Showpad Apps can not have duplicate source files (manifest.json, config.json, index.html) in your project.

When using a build tool, you should delete the directory built after bundling or use lib or dist as build directories since the Experience App CLI will ignore these directories.

create​

Deprecated Command

This command is deprecated and will be removed in a future release. We recommend using apps upload instead.

To create a new app Channel from a .showpad bundle, run the following command:

npx experience-app-cli create

Available Options​

proxy​

This command will install the Development Proxy App on the configured domain so you can develop on your localhost with it. It opens up a socket that the Development Proxy App will communicate with while you're developing.

npx experience-app-cli proxy

Available Options​

generateSdmTypes​

This command generates TypeScript types based on the schemas in the SDM (Structured Data Manager).

npx experience-app-cli generateSdmTypes

profiles​

This command returns a list of all configured Showpad access profiles.

npx experience-app-cli profiles

apps upload​

This command allows you to effortlessly upload an app to Showpad. For a full example see the Upload an app guide.

npx experience-app-cli apps upload {{path/to/file}}
caution

Be sure to replace {{path/to/file}} with the path to your .showpad bundle.

Available Options​

apps list​

This command provides a comprehensive overview of all apps registered in your Showpad account.

npx experience-app-cli apps list

The following information is returned for each app:

| ID                         | APPKEY                      | CREATED                  |
| -------------------------- | --------------------------- | ------------------------ |
| 01H28FJ5MM5TQQF942P56RHFZ9 | com.showpad.app.testapp.001 | 2023-06-06T13:50:23.380Z |
| 01H2QMZ9WGT41EXHSTZWZDE6K2 | com.showpad.app.testapp.002 | 2023-06-10T11:13:33.071Z |
| 01H2QPYA2GDP01YS1PDTSXHXMY | com.showpad.app.testapp.003 | 2023-06-12T11:47:57.647Z |

Available Options​

apps status​

This command allows you to conveniently retrieve the upload status of your app versions in Showpad. It provides valuable insights into the current state of your app uploads, enabling you to stay informed about the progress and status of your app versions.

npx experience-app-cli apps status

If you run the command without the --app-id option, you'll be prompted to select an app from a provided list. Once, you've selected an app, the command will return the status of all versions for the selected app.

If you run the command with the --upload-id option, you will only get the status of the specified app version upload.

The command will display a table giving you a clear overview of the status, version, and creation date of each app version:

| STATUS             | VERSION | CREATED                  |
| ------------------ | ------- | ------------------------ |
| ACTIVE             | 1.0.0   | 2023-06-10T13:49:46.567Z |
| WAITING_FOR_UPLOAD | 1.0.1   | 2023-06-06T13:54:35.516Z |

The available statuses are:

  • WAITING_FOR_UPLOAD - Your package is still beeing processed.
  • ACTIVE - Your package has processed correctly.
  • FAILED - Your package has not processed correctly. The error property will contain more details.

Available Options​

apps versions​

This command allows you to retrieve a comprehensive list of all available versions for a specific app. This can be useful for managing and tracking the evolution of your app.

npx experience-app-cli apps versions

If you run the command without the --app-id option, you'll be prompted to select an app from a provided list. Once, you've selected an app, the command will display a table that provides the following information for each version of the app:

| Version | Version ID                 | Created                  |
| ------- | -------------------------- | ------------------------ |
| 1.0.0   | 01H28FJ5N95X4A9EZ7ZKC69N0T | 2023-06-06T13:50:23.401Z |
| 1.0.1   | 01H28FVAW71XRN98KBK3EK23WR | 2023-06-06T13:55:23.654Z |

Available Options

apps assign​

This command enables you to assign a specific version of your app to one or more Showpad organizations, making it easy to distribute the app to the intended audience.

npx experience-app-cli apps assign

If you don't provide the --version-id option, the command will prompt you to select the desired app and version.

If you don't specify the --organisations, the command will prompt you to enter them as a comma-separated list.

For a full example, see Manage Assignments.

Available Options

Option Details​

All commands have optional flags available. The Experience App CLI will not prompt if the corresponding option is present and valid, however if an invalid option is passed, it will prompt.

caution

All options are mandatory in -u, --unattended mode. The Experience App CLI will throw an error if the option is neither present nor valid.

-u, --unattended​

This option allows you to run a CLI command unattended.

Unattended mode requires all options to be present and will throw an error if any are missing or don't pass validation.

Unattended mode is different in some aspects than passing all options in the default (attended) mode. For example, unattended mode has some default values for prompts or values that can not be passed through options.

In addition, running in unattended mode will do the following:

  • automatically create the manifest.json file from the package.json
  • automatically select the first Development Proxy App (if multiple are present)
  • throw errors on invalid options instead of prompting the value

--host​

This option allows you to pass your Showpad domain to your app.

OptionValue
--hostThe address of your Showpad domain.

Example: --host https://your-domain.showpad.biz

--client-id​

This option allows you to pass your Showpad OAuth client ID to your app.

OptionValue
--client-idThe ID of your Showpad OAuth client.

Example: --client-id fhudsahfiuadshfgidusahfidusfghaisudf

You can learn all about authentication, authorization, and OAuth clients in the Showpad API section.

--client-secret​

This option allows you to pass your Showpad OAuth client secret to your app.

OptionValue
--client-secretThe secret of your Showpad OAuth client.

Example: --client-secret example_client_secret

You can learn all about authentication, authorization, and OAuth clients in the Showpad API section.

--username​

This option allows you to pass a Showpad username to your app.

OptionValue
--usernameThe email address a user logs into Showpad with.

Example: --username JohnPublic@publiccompany.biz

--password​

This option allows you to pass a Showpad user's password to your app.

OptionValue
--passwordA Showpad user's password.

Example: --password mySecur3pwd

If SSO is being used to log into Showpad, you must set username and password authentication to make use of the Experience App CLI. This does not alter your existing SSO setup. You can always use the forgot password manual to quickly set a password.

--profile​

This option allows you to specify the credentials profile to use. If no arguments are provided, the default value is used.

If you run a command without specifying a profile, the 'default' profile (created by the auth command) will be used.

--src​

This option allows you to pass the source directory of your project to your app. Common directories are src and public.

OptionValue
--srcThe source directory of your project.

Example: --src public

Beware if you pass the --src option while not having an index.html file. The Experience App CLI will place it in the same directory as config.json and manifest.json files , which can be unintended. However, most framework scaffolding will already generate an index.html.

--types​

This option allows you to specify the types to return. If not set, all types will be returned.

--dist​

This option allows you to pass the build directory of your project to your app. Common directories are src and dist.

OptionValue
--distThe build directory of your project.

Example: --dist src

Most build tools will compile your code to a specific directory like dist. You can just select your src directory if you aren't using a build tool.

--output​

This option generates a .ts file with the extracted types to a specified directory.

OptionValue
--outputThe output directory of your project.

Example: --output myoutputdirectory

The output path is relative to the current working directory. You can use dots to navigate to the parent directories. For example:

  • your folder structure: monolith/subproject
  • your current working directory: monolith/subproject
  • desired build location: monolith

You can execute the following command:

npx experience-app-cli bundle --output ../

--channel-name​

This option allows you to pass the name of an app Channel to your app.

OptionValue
--channel-nameThe name of an app Channel.

Example: --channel-name SuperCoolStuff

--channel-id​

This option allows you to pass the ID of an app Channel to your app.

OptionValue
--channel-idThe ID of an app Channel.

Example: --channel-id xyz123abc

--overwrite-values​

This option allows you to overwrite the values of the config.json file while updating an app Channel.

OptionValue
--coverwrite-valuesFlag to overwrite the values in the config.json file.

Example: --overwrite-values

--types​

This option allows you to specify the types to return. If not set, all types will be returned.

--app-id​

This option allows you to specify the app ID to use.

OptionValue
--app-idThe identifier of a specific app.

Example: --app-id 01H28FJ5N95X4A9EZ7ZKC69N0T

--upload-id​

This option allows you to define a specific upload to use.

OptionValue
--upload-idThe identifier of a specific upload.

Example: --upload-id 01234XYZ56789

--version-id​

This option allows you to define a specific app version to use.

OptionValue
--version-idThe identifier of a specific app version.

Example: --upload-id 02I39FJ5N95X4A97ZKC69N0TEZ

--organisations​

This option allows you to specify the organizations the app should to be assigned to.

      Option            Value
--organisationsThe identifiers of specific organizations.

Example: --organisations 2664cf58-514c-4424-b467-3a57c92bb048 17db0dc4-0b4a-11ee-be56-0242ac120002