Install an App

New
  • Published on May 29, 2025
  • 3 minute(s) read
Prev Next

Install or Upgrade an App

Your Apps are yours to manage! You can install, update, and configure your Apps with the appcfg tool, using the apps suite of commands. There are two parts to a working app platform configuration.

  1. The external app: via appcfg apps list --apps, this is the zip you upload. It has templates, but no values, it cannot do anything on its own, since there is no data to fill the templates.

    application identifier uniquely identified via the external app. It is a 3-part name composed of author, app name, and version, like so: gladly.com/my-app/v1.0.0

  2. The configuration: via appcfg apps list --configs, this is what holds all the data necessary for the templates, e.g. host and any secrets. There can be multiple configurations per app, each for a different set of credentials, and using Shopify as an example, a configuration for each store a customer might manage for their org.

Remember to Use the --help Flag and Autocomplete

While you can find information on installing and managing your Apps below in this article, remember that much of this information and more is available in the appcfg tool itself! Use the —help flag or -h after any CLI command to access docs right in your terminal. The autocomplete feature (accessible via appcfg completion -h) can help you out by finishing your commands for you or suggesting available commands with the Tab button. The appcfg tool is designed to make App Platform discoverable on your own!

Requirements

Important

You need to have access to a Gladly user with email that corresponds to the org email domain. This means you cannot use user@company_b.com for an org that’s domain is set to user@company_a.com

  1. To manage external apps in a Gladly environment, you will need the latest version of. Specifically, you will use the appcfg apps set of commands.

  2. Since these commands run against a Gladly environment, you will need to:

    1. Know your Gladly host, either us-1.gladly.com for production orgs or us-uat.gladly.qa for sandbox environments

    2. Have a dedicated Gladly user with the role API User

    3. Generate an API token associated with that user

  3. You have validated, tested, and built the app using appcfg.

API Tokens

API tokens are associated with users so you need to be logged in as the user you will be using for installation.

Setup

Authentication can be supplied either via flags during the command itself or as environment variables in your shell. Env vars are recommended for ease of use, but they can be overridden by the aforementioned flags.

-g, --gladly-host – This is your Gladly domain, e.g. us-uat.gladly.qa or us-1.gladly.com

-u, --user – The email of the Gladly user that created the API token

-t, --token – The API token used for authentication, which can be created via Admin → App Developer Tools → API Tokens

Alternatively, these can be set as environment variables:

// ~/.zshrc or your shell of choice

export GLADLY_APP_CFG_HOST=

export GLADLY_APP_CFG_USER=

export GLADLY_APP_CFG_TOKEN=<token>

Autocomplete

Please enable autocomplete for the appcfg tool, which provides assistance filling out commands, as well as being able to automatically display apps for configuration, configurations for updating, and so on.

New App

OAuth 2.0 Auth requirements

If you are using OAuth you will need to contact Gladly Support to register the auth domain to the Gladly global app configuration.

1. Installing an external app

appcfg apps install --filepath /absolute/path-to/app.zip

Now your app files have been stored and are ready to be configured. Verify installation with appcfg apps list .

❯❯❯ appcfg apps list
|     APP IDENTIFIER     |   APP CREATED AT    |
|------------------------|---------------------|
| gladly.com/EXAMPLE/v1.0.0 | 2025-04-24 14:00:22 |
|------------------------|---------------------|

You can find the unique “App Identifier” that identifies your app by running the command.

2. Configuring an external app

After you have installed the app, you need to configure it to a specific instance by creating a configuration. Follow /developer-tutorials/docs/appcfg-apps-install#2-configuring-an-external-app

Troubleshooting

While installing the app using appcfg install I received the following error:

❯❯❯ appcfg apps install --filepath gladly.com-EXAMPLE-1.0.0.zip 
Error: app/gladly.com-EXAMPLE-1.0.0.zip
	unexpected file; app/gladly.com-EXAMPLE-1.0.0.zip
	unexpected file

This can happen when you run appcfg build and there us already gladly.com-EXAMPLE-1.0.0.zip inside your apps directory. That is, you have built your app twice, and the second time, your app’s zip included the previously built gladly.com-EXAMPLE-1.0.0.zip .You can avoid this by running appcfg build from outside your apps file directory.

Related docs