Skip to main content

Auth Commands

Three commands handle the authentication lifecycle: login, logout, whoami.

For the conceptual overview of how authentication works (PATs, env vars, token storage), see Authentication.

unlayer login​

Authenticate with your Unlayer account.

Syntax​

unlayer login [options]

Description​

Starts an OAuth-style browser flow by default: opens the Unlayer accounts page, chains through the console's cli-auth endpoint to mint a Personal Access Token, and redirects back to a local server bound to 127.0.0.1. The token is then stored in your global CLI config.

--manual opens the Personal Access Tokens page (/home/profile/tokens) instead and prompts you to paste the token. Useful when the browser callback can't reach the CLI — for example, when you're SSH'd into a remote machine.

In CI, pass --token or set UNLAYER_TOKEN to skip the browser flow entirely.

After authentication, the CLI prompts you to pick a default workspace and project. It 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. Tokens must start with unlayer_pat_; anything else is rejected.

Options​

FlagDescription
-t, --token <token>Personal Access Token (skip browser flow)
-u, --url <url>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 (non-interactive)
--project-id <id>Auto-select project by ID (non-interactive)
--skip-verifySkip token verification (local development)
--skip-contextSkip workspace/project selection after login
--jsonOutput as JSON

Examples​

# Interactive browser login
unlayer login

# Login with a token (CI-friendly)
unlayer login --token unlayer_pat_xxxxxxxxxxxx

# Auto-select workspace and project (great for scripts)
unlayer login --token $UNLAYER_PAT --workspace-id 42 --project-id 17

# Manual token entry (no browser available)
unlayer login --manual

unlayer logout​

Clear stored credentials.

Syntax​

unlayer logout [options]

Description​

Removes the stored token (and tokenId) from the global config. Pass --all to clear the entire global config — token, workspace and project preferences, custom API URL, environment profiles, and the active environment.

If you're already not logged in, the command prints You are not currently logged in. and exits cleanly without any changes.

Options​

FlagDescription
-a, --allClear all configuration including workspace and project settings
-f, --forceSkip confirmation prompt
--jsonOutput as JSON

Examples​

# Confirm interactively, then clear the token
unlayer logout

# No confirmation (e.g., in scripts)
unlayer logout --force

# Wipe token + workspace + project
unlayer logout --all --force

unlayer whoami​

Verify the active authentication and show context.

Syntax​

unlayer whoami [options]

Description​

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. Exits with 2 if not authenticated, 1 if the API call fails.

Options​

FlagDescription
--jsonOutput as JSON

Examples​

unlayer whoami
#  Authentication
#    Token:   unlayer_pat_xxxxxxxx...
#    Source:  Config file
#    API URL: https://api.unlayer.com
#
#  Current Context
#    Workspace: #42
#    Project:   #17
#
#  Accessible Workspaces
#    ├ Acme (ID: 42)
#    └ Side Project (ID: 51)
#
#  Authentication verified
unlayer whoami --json
# {
#   "token": { "prefix": "unlayer_pat_xxxxxxxx...", "isEnvVar": false },
#   "apiUrl": "https://api.unlayer.com",
#   "workspaceId": 42,
#   "projectId": 17,
#   "workspaces": [ { "id": 42, "name": "Acme" }, ... ],
#   "configPath": "/Users/jane/Library/Preferences/unlayer-cli-nodejs/config.json"
# }

A common script pattern — pull the active workspace ID out of the JSON:

WORKSPACE_ID=$(unlayer whoami --json | jq -r '.workspaceId')
echo "Active workspace: #$WORKSPACE_ID"

See Also​