Configuration

The CLI reads configuration from three sources, in order of precedence:

1. Environment variables — for CI and one-off overrides.
2. Global config — your stored CLI state (unlayer login, unlayer config set, unlayer workspace use, etc.).
3. Project config — unlayer.config.json in your repo.

A typical setup uses the global config for personal authentication and the project config for project-scoped defaults like the project ID and output directory.

---

Global Flags

These work on every command:

Flag	Effect
--json	Output as machine-readable JSON (stdout)
--non-interactive	Never prompt; fail if input would be required
-v, --verbose	Verbose logging to stderr
-q, --quiet	Suppress decorative output (header, status messages)

CI environments automatically enable --non-interactive and --quiet. The CLI detects them via the CI env var, CONTINUOUS_INTEGRATION, UNLAYER_NON_INTERACTIVE, or a non-TTY stdin.

Output Contract

The CLI separates streams cleanly so you can pipe and parse:

• stdout — machine-readable data (JSON, URLs). Safe to | jq or capture.
• stderr — human messages, spinners, errors.
• In --json mode, errors are written to stderr as {"error": "..."}.

---

Environment Variables

Variable	Effect
UNLAYER_TOKEN	Personal Access Token (highest-priority token source)
UNLAYER_API_URL	Override the API base URL
UNLAYER_WORKSPACE_ID	Override the active workspace
UNLAYER_PROJECT_ID	Override the active project
UNLAYER_NON_INTERACTIVE	Force non-interactive mode
CI	Auto-enables non-interactive + quiet
CONTINUOUS_INTEGRATION	Same as CI

The token env var name itself is configurable. See Authentication → Token Environment Variable Override.

---

Global Config File

Stored by conf in your OS-standard config location:

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

Run unlayer config show to see the exact path on your machine.

Stored Keys

Key	Set By	Purpose
token	unlayer login	Active Personal Access Token
tokenId	unlayer login	Server-side ID of the token (for revocation)
tokenEnvVar	unlayer config set token-env-var	Name of the env var the CLI looks at (default UNLAYER_TOKEN)
apiUrl	unlayer config set api-url / unlayer login --url	API base URL
workspaceId	unlayer workspace use	Active workspace
projectId	unlayer project use	Active project
environments	unlayer env add	Named environment profiles
activeEnvironment	unlayer env use	Currently selected environment profile

You normally manage these via commands rather than editing the file directly.

---

Project Config File

Drop a unlayer.config.json at the root of your repo to commit project-scoped defaults:

{
  "projectId": 17,
  "defaults": {
    "outputDir": "./templates"
  },
  "environments": {
    "self-hosted": {
      "apiUrl": "https://unlayer-api.your-domain.com",
      "consoleUrl": "https://unlayer-console.your-domain.com",
      "accountsUrl": "https://unlayer-accounts.your-domain.com"
    }
  }
}

The CLI walks up from the current directory to find this file, the way .gitignore resolution works.

Key	Type	Purpose
projectId	number | null	Default project for commands that need one
defaults.outputDir	string	Default output directory for unlayer pull (defaults to ./templates)
environments	Record<string, { apiUrl, consoleUrl, accountsUrl }>	Named environment profiles for this project

🔒 Security: the keys token, apiKey, and $schema are stripped from the parsed config so a leaked file can't leak credentials. Don't put secrets in this file. Use env vars instead.

---

Environment Profiles

If you need to point the CLI at a different Unlayer deployment (a self-hosted instance, for example), save the URLs as a named profile and switch with one command:

# Define a profile (saved in global config)
unlayer env add self-hosted

# Switch the active profile
unlayer env use self-hosted

# Inspect
unlayer env list
unlayer env show self-hosted

# Switch back to defaults
unlayer env use --none

Profiles set the API URL, Console URL, and Accounts URL together. They can be defined in the global config (personal) or in unlayer.config.json (project-shared). Global wins on name conflicts. See Settings commands → env for details.

---

Resolution Order

For each setting, the CLI uses the first source that has a value:

Setting	1st	2nd	3rd	4th
Token	UNLAYER_TOKEN env var (or whatever tokenEnvVar names)	global config token	—	—
API URL	UNLAYER_API_URL	active env profile	global config apiUrl	https://api.unlayer.com
Workspace ID	UNLAYER_WORKSPACE_ID	global config workspaceId	—	—
Project ID	UNLAYER_PROJECT_ID	global config projectId	unlayer.config.json projectId	—
Output dir	command-line --output-dir	unlayer.config.json defaults.outputDir	./templates	—

---

See Also

• Authentication — token storage, the tokenEnvVar knob
• Settings commands — config, env, status
• Examples — pointing at a self-hosted deployment