Skip to main content

Version 3.0.x (legacy)

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.x of the Experience App CLI introduces the concept of profiles. This allows you to store Showpad access credentials for multiple users without having to manually update the credentials every time.

Since the addition profiles requires managing multiple creditentials, the following changes were made:

  • Credentials are more secure as they are now stored in a hidden .showpad folder in the user's home directory
  • New commands have been added: profiles and auth
  • The behavior of some existing commands has been updated
  • Command options are now required to use kebab-case, rather than snake_case

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

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

Available Options


profiles

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

npx experience-app-cli profiles

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.