Upload custom UI assets using CLI

After developing your custom sign-in UI, you can deploy it to Logto Cloud to server your tenant users. As we've already introduced in the "Bring your UI" documentation, you can achieve this by uploading the zipped UI assets in Logto Console.

Here we provide another option to deploy your UI assets to Cloud using the CLI command, which will be useful when you want to integrate the deployment process into an NPM script or CI/CD pipeline.

Instructions

note

Assuming you have your custom sign-in UI assets built in the /path/to/your/custom/ui/dist directory.

The deploy command will automatically zip your UI assets, upload them to Logto Cloud, and set the custom UI as the sign-in experience for your tenant users.

Prerequisites

Since this command interacts with the Logto Management API, a machine-to-machine app is required to authenticate the request. Refer to this documentation to learn what Logto Management API is and how to create a machine-to-machine app with required permissions.

Command options

--help                                 Show help
--version                              Print CLI version
--auth                                 Auth credentials of your Logto M2M a pplication. E.g.: <app-id>:<app-secret>
--endpoint                             Logto endpoint URI that points to your Logto Cloud instance. E.g.: https://<tenant-id>.logto.app/
--path, --experience-path              The local folder path of your custom sign-in experience assets.
--resource, --management-api-resource  Logto Management API resource indicator. Required if using custom domain.
--verbose                              Show verbose output. [default: false]

Run the command

Assuming your app ID is foo, app secret is bar, and your tenant ID is baz.

npx @logto/tunnel deploy --auth foo:bar --endpoint https://baz.logto.app --experience-path /path/to/your/custom/ui/dist

If you are using custom domain for your Logto endpoint, an additional option --management-api-resource (or --resource) must be specified.

Given the fact that Logto Management API resource is always fixed to https://<tenant-id>.logto.app/api. You can run the command as follows:

npx @logto/tunnel deploy --resource https://baz.logto.app/api --auth foo:bar --endpoint https://your.custom.domain --experience-path /path/to/your/custom/ui/dist

Note:

1. This option can be omitted when using the default Logto domain, since the CLI can infer the resource automatically.
2. Using either custom domain or default Logto domain as the endpoint will yield identical results.

Alternatively, if you have an existing zip and prefer to use it directly, you can specify the --zip-path option.

npx @logto/tunnel deploy --auth foo:bar --endpoint https://baz.logto.app --zip-path /path/to/your/custom/ui/dist.zip

Supported environment variables

The deploy command also supports environment variables and will automatically map them to the corresponding options.

All supported environment variables are listed below, prefixed with LOGTO_.

Environment variable	CLI option
LOGTO_AUTH	--auth
LOGTO_ENDPOINT	--endpoint
LOGTO_EXPERIENCE_PATH	--experience-path
LOGTO_PATH	--path
LOGTO_MANAGEMENT_API_RESOURCE	--management-api-resource
LOGTO_RESOURCE	--resource
LOGTO_ZIP_PATH	--zip-path

Use environment variables

1. You can create a .env file in the CLI root directory, or any parent directory where the CLI is located.

.env

LOGTO_AUTH=foo:bar
LOGTO_ENDPOINT=https://your.custom.domain
LOGTO_EXPERIENCE_PATH=/path/to/your/custom/ui/dist
LOGTO_RESOURCE=https://baz.logto.app/api

Then run the command without specifying the options.

npx @logto/tunnel deploy

2. Alternatively, specify these environment variables directly when running the command.

LOGTO_AUTH=foo:bar LOGTO_ENDPOINT=https://your.custom.domain LOGTO_EXPERIENCE_PATH=/path/to/your/custom/ui/dist LOGTO_RESOURCE=https://baz.logto.app/api npx @logto/tunnel deploy