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.
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
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 viaappcfg 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
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.
Since these commands run against a Gladly environment, you will need to:
Know your Gladly host, either
us-1.gladly.com
for production orgs orus-uat.gladly.qa
for sandbox environmentsHave a dedicated Gladly user with the role API User
Generate an API token associated with that user
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.