Skip to main content

Settings Commands

Three command groups for managing the CLI itself:

  • config — read and write the global config.
  • env — manage environment profiles (self-hosted deployments, etc).
  • status — health check.

For the conceptual model — where the global config lives, what an environment profile is — see Configuration.

unlayer config​

Read and modify the global CLI config.

config show​

Print the current configuration.

unlayer config show
unlayer config show --json
FlagDescription
--jsonOutput as JSON

The output includes the path to the config file on disk, which is useful when you need to back it up or copy it to another machine.

config set <key> <value>​

Set a single configuration key. Two keys are accepted:

KeyEffect
api-urlOverride the API base URL
token-env-varChange which env var the CLI reads the token from (default: UNLAYER_TOKEN)
unlayer config set api-url https://unlayer-api.your-domain.com
unlayer config set token-env-var MY_COMPANY_UNLAYER_TOKEN
FlagDescription
--jsonOutput as JSON

To set the active workspace or project, use unlayer workspace use <id> or unlayer project use <id> instead. Those are stored differently from the keys above.

config path​

Print the path to the global config file. Handy in scripts.

unlayer config path
# /Users/jane/Library/Preferences/unlayer-cli-nodejs/config.json

unlayer config path --json
# {"path":"/Users/jane/Library/Preferences/unlayer-cli-nodejs/config.json"}
FlagDescription
--jsonOutput as JSON

config reset​

Reset the configuration to defaults. Clears the token, workspace, project, environments — everything.

unlayer config reset           # prompts for confirmation
unlayer config reset --force   # no prompt
FlagDescription
-f, --forceSkip confirmation prompt
--jsonOutput as JSON

unlayer env​

Manage environment profiles — named sets of API/Console/Accounts URLs you can switch between.

Useful when you point the CLI at a self-hosted Unlayer deployment without rewriting the global config every time.

env list​

List all environment profiles.

unlayer env list
unlayer env list --json
FlagDescription
--jsonOutput as JSON

The output flags which profile is active and where each one is defined (global config or the project's unlayer.config.json).

env add <name>​

Add or update a named environment profile in your global config. All three URLs are required flags — there is no interactive prompt.

unlayer env add self-hosted \
  --api-url https://unlayer-api.your-domain.com \
  --console-url https://unlayer-console.your-domain.com \
  --accounts-url https://unlayer-accounts.your-domain.com
ArgumentDescription
<name>Profile name (any string you choose, e.g. self-hosted, local)
FlagDescription
--api-url <url>Required. API base URL
--console-url <url>Required. Console base URL
--accounts-url <url>Required. Accounts base URL
--jsonOutput as JSON

All three URLs are validated as parsable URLs at runtime. Invalid input fails with exit code 2.

env use [name]​

Switch the active environment profile.

unlayer env use self-hosted    # activate the named profile
unlayer env use --none         # back to default URLs
unlayer env use                # interactive picker
ArgumentDescription
[name]Profile name to activate (omit for picker)
FlagDescription
--noneClear active profile (back to defaults)
--jsonOutput as JSON

env show [name]​

Show the URLs configured for a profile.

unlayer env show self-hosted   # specific profile
unlayer env show               # the active profile
ArgumentDescription
[name]Profile name (defaults to active)
FlagDescription
--jsonOutput as JSON

env remove <name>​

Remove a profile from the global config. If you remove the active profile, the CLI clears the active selection.

unlayer env remove self-hosted
ArgumentDescription
<name>Profile name to remove
FlagDescription
--jsonOutput as JSON

You can also define profiles in unlayer.config.json to share them with your team via git. env add writes to the global (per-machine) config, and those overrides win on name conflicts with project-defined profiles.

unlayer status​

Check CLI health and connectivity.

Syntax​

unlayer status [options]

Description​

Reports authentication state, API reachability and latency, the active workspace and project IDs, the API URL, and the path to the global config file. Doesn't require authentication, which makes it useful as the first command to run when something is off. Exits with code 1 when not authenticated or when the API is unreachable, otherwise 0.

Options​

FlagDescription
--jsonOutput as JSON

Examples​

unlayer status
# Authenticated: Yes
# API Reachable: Yes
# API Latency:   42ms
# API URL:       https://api.unlayer.com
# Workspace ID:  42
# Project ID:    17
# Config File:   /Users/jane/Library/Preferences/unlayer-cli-nodejs/config.json
# ✓ All systems operational
unlayer status --json
# {
#   "authenticated": true,
#   "apiReachable": true,
#   "apiLatencyMs": 42,
#   "apiUrl": "https://api.unlayer.com",
#   "workspaceId": 42,
#   "projectId": 17,
#   "configPath": "/Users/jane/Library/Preferences/unlayer-cli-nodejs/config.json",
#   "error": null
# }

# In CI, gate on JSON output
HEALTH=$(unlayer status --json)
echo "$HEALTH" | jq -e '.authenticated and .apiReachable'

See Also​