--- title: "Install an App" slug: "appcfg-apps-install" updated: 2025-07-15T19:53:38Z published: 2025-07-15T19:53:38Z canonical: "help.gladly.com/appcfg-apps-install" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.gladly.com/llms.txt > Use this file to discover all available pages before exploring further. # Install an App ## 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`, 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 config list`, 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. > [!NOTE] > 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 > [!WARNING] > 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](https://github.com/gladly/app-platform-appcfg-cli/releases/latest) of. Specifically, you will use the [appcfg apps](https://github.com/gladly/app-platform-appcfg-cli/blob/main/docs/appcfg_apps.md) set of commands. 2. Since these commands run against a Gladly environment, you will need to: 1. Know your Gladly host, either `your-org.us-1.gladly.com` for production orgs or `your-org.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`. > [!NOTE] > API Tokens > > [API tokens](https://help.gladly.com/docs/generate-api-tokens-and-create-webhooks) 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. `your-org.us-uat.gladly.qa` or `your-org.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: ```bash // ~/.zshrc or your shell of choice export GLADLY_APP_CFG_HOST= export GLADLY_APP_CFG_USER= export GLADLY_APP_CFG_TOKEN= ``` > [!WARNING] > 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 > [!CAUTION] > 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 ```bash 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` . ```bash ❯❯❯ 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](/developer-tutorials/docs/appcfg-apps-install#2-configuring-an-external-app) ## Troubleshooting **While installing the app using appcfg install I received the following error:** ```bash ❯❯❯ 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. The **appcfg tool** is a command line tool designed for building, testing, and managing App Platform apps. More information and releases are available on GitHub: https://github.com/gladly/app-platform-appcfg-cli Users assigned the **Team Manager** or **Administrator** roles can contact [Gladly Support](https://help.gladly.com/product-docs/pages/en/contact-gladly-support-team). Log into Gladly as one of these roles, click![hamburger-menu-icon(1)](https://cdn.us.document360.io/7047b671-c4f2-4df0-bb0a-b9b511fd2452/Images/Documentation/hamburger-menu-icon(1).svg?sv=2026-02-06&spr=https&st=2026-10-31T13%3A22%3A15Z&se=2026-10-31T14%3A22%3A15Z&sr=c&sp=r&sig=813ke0tzbKqUwmkhgeeE1TnjpFJ67m7KUQdSriAI3OU%3D)on the top-left corner, then click **Contact Gladly Support**. Gladly Support's primary operating hours are Monday through Friday, 6 AM to 6 PM Pacific Time, but you can submit a request anytime. - Please select the correct business impact (P1 to P4). - Most requests should be sent as a P4.