Skip to main content

Errors & Troubleshooting

The CLI uses three exit codes and writes errors to stderr. In --json mode, errors are JSON-encoded so they're parseable.

Exit Codes​

CodeMeaning
0Success
1Runtime error — API failure, network problem, unexpected exception
2Usage error — bad input, missing required arg, unknown flag, not authenticated

Use these in shell scripts:

if ! unlayer pull; then
  case $? in
    1) echo "API or runtime error — retry?" ;;
    2) echo "Bad usage or not authenticated — fix invocation" ;;
  esac
fi

Output Streams​

StreamContent
stdoutMachine-readable data only (JSON, URLs). Safe to pipe.
stderrHuman-readable messages, spinners, errors

In --json mode, errors land on stderr in the form {"error": "..."}.

Common Errors​

Not authenticated​

✗ Not authenticated. Run unlayer login to get started.

The CLI couldn't find a token. Fix:

unlayer login
# or in CI:
export UNLAYER_TOKEN=unlayer_pat_xxxxxxxx

If you've configured a non-default token env var name (via config set token-env-var ...), the CLI looks at that variable, not UNLAYER_TOKEN. Check with:

unlayer config show
# → look for the "Token Env Var" line

Invalid token / 401 Unauthorized​

The stored token has been revoked or expired. Re-authenticate:

unlayer logout
unlayer login

Project not found / Project ID required​

Some commands need a project ID. Resolution order:

  1. --project-id flag on the command
  2. UNLAYER_PROJECT_ID env var
  3. unlayer project use <id> (writes to global config)
  4. projectId in unlayer.config.json at the repo root

If none of these is set, commands that scope to a project will fail. Run:

unlayer project list
unlayer project use <id>

Workspace not found / Workspace ID required​

Same pattern as Project ID, but for workspace scope. Resolved in this order:

  1. UNLAYER_WORKSPACE_ID env var
  2. unlayer workspace use <id>
unlayer workspace list
unlayer workspace use <id>

unknown option '--xxx' / missing required argument​

These are Commander parse errors. The CLI exits with code 2. The error message names the offending command and option. Run unlayer <command> --help to see valid options.

unlayer pull --help

unlayer.config.json parse warning​

Warning: Failed to parse /path/to/unlayer.config.json: ...

The CLI found a config file but it isn't valid JSON. The CLI keeps going with defaults. Validate the file with cat unlayer.config.json | jq ..

Authentication browser flow times out​

Authentication timed out after 5 minutes. Please try again.

The CLI listened for the OAuth callback for 5 minutes and gave up. Common causes:

  • The browser couldn't reach localhost.
  • A firewall blocked the local server (it binds to 127.0.0.1).
  • You closed the browser tab before completing sign-in.

Try again, or use manual token entry:

unlayer login --manual

EACCES / permission denied during install​

npm install -g @unlayer/cli
# → EACCES: permission denied

Use a Node version manager (nvm, fnm, volta) instead of system Node, or change npm's global prefix to a user-writable location. Don't sudo npm install -g.

Node version not supported​

The CLI requires Node 20+. Check with node --version. If you're below 20:

nvm install 20
nvm use 20

Verbose Logging​

When you can't tell why a command is failing, run with --verbose:

unlayer pull --verbose

Verbose output goes to stderr (so it doesn't break --json piping) and shows config resolution, API URLs, and HTTP status codes.

Connectivity Check​

unlayer status is the quickest way to verify the CLI can reach the API:

unlayer status

It works without authentication, which makes it useful when your token has expired or you're debugging a corporate proxy.

Where to Report Bugs​

Open an issue at github.com/unlayer/cli/issues with:

  • The command you ran
  • The output (use --verbose to capture more)
  • unlayer status --json output
  • Your OS and Node version

See Also​