Version 3.0.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
• Authenticate against a Showpad instance
• Synchronize your app's manifest.json file (created during development)
• Bundle your app
• Create new Channels for your app
• Install the Development Proxy App
• Generate TypeScript types for SDM Schemas
• List authentication profiles

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

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

yarn

yarn add @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).

npm

npx experience-app-cli init

yarn

yarn experience-app-cli init

Available Options

• -u, --unattended
• --src

---

auth

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

npm

npx experience-app-cli auth

yarn

yarn experience-app-cli auth

Available Options

• -u, --unattended
• --host
• --client-id
• --client-secret
• --username
• --password
• --profile

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.

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:

npm

npx experience-app-cli create

yarn

yarn experience-app-cli create

Available Options

• -u, --unattended
• --channel-name
• --profile

---

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

Available Options

• --profile

---

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

Available Options

• --profile
• --types
• --output

---

profiles

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

npm

npx experience-app-cli profiles

yarn

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

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.

---

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

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.

---

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

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 generates a .ts file with the extracted types to a specified directory.

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

---

--types

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