Version 2.x (legacy)

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:

• Creating new apps with Showpad Apps v2
• Migrating your v1 apps to v2

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

It allows you to run specific commands to:

• Initialize any JavaScript app to become a Showpad App
• Synchronize your Showpad App's manifest.json file (created during development)
• Bundle your Showpad App
• Create new Channels for your Showpad App
• Install the Development Proxy App
• Generate TypeScript types for SDM Schemas

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

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

yarn

yarn add @showpad/experience-app-cli@2.2.0 -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 Showpad App by verifying and/or creating required files. You'll be prompted to provide Showpad access credentials.

npm

npx experience-app-cli init

yarn

yarn experience-app-cli init

Available Options

• -u, --unattended
• --host
• --client_id
• --client_secret
• --username
• --password
• --src

---

sync

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

npm

npx experience-app-cli sync

yarn

yarn 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

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

yarn

yarn 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.

npm

npx experience-app-cli bundle

yarn

yarn experience-app-cli bundle

Available Options

• -u, --unattended
• --dist
• --output

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:

testing

npm

npx experience-app-cli create

yarn

yarn experience-app-cli create

Available Options

• -u, --unattended
• --channel_name

---

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.

npm

npx experience-app-cli proxy

yarn

yarn experience-app-cli proxy

---

generateSdmTypes

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

npm

npx experience-app-cli generateSdmTypes

yarn

yarn experience-app-cli generateSdmTypes

---

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.

Option	Value
--host	The 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.

Option	Value
--client_id	The 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.

Option	Value
--client_secret	The 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.

Option	Value
--username	The 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.

Option	Value
--password	A 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.

---

--src

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

Option	Value
--src	The 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.

---

--dist

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

Option	Value
--dist	The 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 allows you to pass the output directory of your bundle (relative to the current working directory) to your app.

Option	Value
--output	The 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:

npm

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

yarn

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

---

--channel_name

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

Option	Value
--channel_name	The 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.

Option	Value
--channel_id	The ID of an app Channel. Example: --channel_id xyz123abc