Skip to main content

Authentication

The CLI authenticates with Personal Access Tokens (PATs). Tokens are scoped to your account and can be revoked any time from the Unlayer Console.

unlayer login

Here's what happens:

  1. Starts a local HTTP server on a random port bound to 127.0.0.1.
  2. Opens your default browser to the Unlayer accounts page (with a returnUrl chained through the console's cli-auth endpoint).
  3. Once you're signed in, the console mints a Personal Access Token and redirects to the local server with the token + a CSRF state parameter.
  4. The CLI validates the state, stores the token, and shuts the server down.

The local server binds to 127.0.0.1 only — it's never exposed to the network. The login window times out after 5 minutes.

After the token is verified, you'll be prompted to pick a default workspace and project. The CLI skips that step if you pass --skip-context, if there's only one workspace/project to choose from, or if you pass --workspace-id and --project-id explicitly.

Manual Token Entry​

When the browser callback can't reach the CLI's local server (the most common case: you're SSH'd into a remote machine and the browser opens on your laptop), use --manual:

unlayer login --manual

This opens the browser to the Personal Access Tokens page (/home/profile/tokens in the console) rather than the auto-callback flow. You generate a PAT, copy it, and paste it into the CLI when prompted.

For fully headless environments with no browser at all, skip login entirely and use --token directly or set UNLAYER_TOKEN. See Non-Interactive Login (CI/CD) below.

Non-Interactive Login (CI/CD)​

Pass the token directly as a flag or environment variable.

Via flag​

unlayer login --token unlayer_pat_xxxxxxxxxxxx

Tokens must start with unlayer_pat_. The CLI validates the prefix and rejects anything else.

Via environment variable​

export UNLAYER_TOKEN=unlayer_pat_xxxxxxxxxxxx
unlayer template list

The CLI checks UNLAYER_TOKEN before reading the global config, so an env var always wins.

In CI, you typically set UNLAYER_TOKEN as a secret and skip unlayer login entirely. Most commands work as long as the token is present in the environment.

All login Flags​

FlagPurpose
-t, --token <token>Personal Access Token (skips browser flow)
-u, --url <url>Override API URL (default: https://api.unlayer.com)
-m, --manualUse manual token entry instead of browser
-f, --forceOverwrite existing authentication
--workspace-id <id>Auto-select workspace by ID
--project-id <id>Auto-select project by ID
--skip-verifySkip token verification (local development only)
--skip-contextSkip workspace/project selection after login
--jsonOutput as JSON

Verifying Who You Are​

unlayer whoami

Calls the API with the active token to confirm it works, then prints a token prefix, the token source (env var or config file), the API URL, the active workspace and project IDs, and the list of workspaces accessible to the token. See unlayer whoami for the full output.

Logging Out​

unlayer logout

Clears the stored token. Pass -a / --all to clear the entire global config (token, workspace and project preferences, custom API URL, and any environment profiles you defined):

unlayer logout --all

Pass -f / --force to skip the confirmation prompt.

Token Storage​

The CLI uses conf to store the token in your OS-standard config location:

PlatformPath
macOS~/Library/Preferences/unlayer-cli-nodejs/config.json
Linux~/.config/unlayer-cli-nodejs/config.json
Windows%APPDATA%\unlayer-cli-nodejs\Config\config.json

You can see the exact path with unlayer config show (it includes a Config File field) or unlayer config path.

Don't commit this file.

It contains your active token. If you ever leak it, revoke the token in the Unlayer Console immediately.

Token Environment Variable Override​

By default, the CLI reads the token from UNLAYER_TOKEN. You can change the env var name the CLI looks at:

unlayer config set token-env-var MY_COMPANY_UNLAYER_TOKEN

After that, the CLI reads MY_COMPANY_UNLAYER_TOKEN instead. Useful if you have multiple Unlayer-related env vars or you're working around naming conflicts in CI.

See Also​