CLI installation and connection

macOS: installation reports EBADENGINE and EACCES

If npm install -g tylor-cli@latest prints both messages, there are two separate problems:

Message	Meaning	Fix
WARN EBADENGINE, requiring node: '>=18' with current: v16.13.0	Node.js is too old. Tylor CLI 0.3.0 requires Node 18 or newer.	Install a current LTS (long-term support) version of Node.js.
ERR! EACCES, mkdir '/usr/local/lib/node_modules/tylor-cli'	npm cannot write to its system-wide installation directory. This is the error that stops installation.	Use a Node version manager that installs under your own user account.

The notice about a new npm version is informational. Updating npm alone does not fix either problem, and the newest npm may itself require a newer Node.js. Use the npm bundled with your new Node installation first.

Recommended recovery on macOS

These steps use Terminal with zsh (the default macOS shell) or bash, on Intel or Apple Silicon. They require an internet connection. On a university-managed Mac that restricts software installation, ask IT to provide a supported Node.js LTS version and a writable npm installation location if these steps are blocked.

1. Install nvm using its official installation instructions. Follow its macOS notes if prompted for Apple’s command-line tools. If you already use another Node version manager, use that manager to install and select an LTS version instead of adding nvm.

2. Close Terminal and open it again. Check that nvm loaded:

   command -v nvm

   This should print nvm. If it prints nothing, follow the official macOS shell setup guidance. For zsh, check that the installer added its initialization lines to ~/.zshrc; create that file if missing and rerun the nvm installer, then reopen Terminal.

3. Install and select the latest LTS Node.js, and make it the default for new terminals:

   nvm install --lts
   nvm use --lts
   nvm alias default 'lts/*'

4. Check the active tools and installation location:

   node -v
   npm -v
   command -v node
   npm config get prefix

   Node should report the LTS version you installed. With the default nvm setup, the Node path and npm prefix should be inside your home directory under .nvm, rather than /usr/local.

5. Install Tylor and check its help without connecting to your account:

   npm install -g tylor-cli@latest
   tylor --help

   Help output confirms that the command runs. Continue with creating an API key and connecting the CLI.

Avoid sudo as the workaround

Do not use sudo npm install -g tylor-cli or broadly change permissions on /usr/local. Elevated permissions do not fix an unsupported Node version. npm recommends a version manager or a user-writable installation directory for global installation permission errors.

Node still shows v16, or npm still targets /usr/local

Run nvm use --lts in the terminal where you will install Tylor, then repeat the checks above. Use type -a node npm tylor to see whether multiple installations are competing on your PATH. Restart an IDE or agent application too if its integrated terminal still selects the old Node.

If nvm explicitly reports an incompatible npm prefix setting, remove a previously added user-level prefix override with npm config delete prefix, then run nvm use --lts again. Custom NPM_CONFIG_PREFIX environment settings also conflict with nvm; remove that override from your shell setup if you added it. See nvm compatibility notes. Do not combine nvm with a separate custom-prefix workaround.

npm or tylor: command not found

If node or npm is missing, complete the Node installation and reopen Terminal first. The npm package is named tylor-cli, but the installed command is tylor.

If only tylor is missing, check the active installation:

node -v
npm list -g tylor-cli --depth=0
npm config get prefix
command -v tylor

Version managers keep global packages separate for each Node installation. After switching Node versions, reinstall with npm install -g tylor-cli@latest in that environment. On macOS/Linux, the prefix’s bin directory must be on PATH; with nvm, its shell initialization handles this. Reopen your terminal or agent after fixing it.

To run without a global Tylor installation, use:

npx --yes --package=tylor-cli@latest tylor --help

This downloads the published CLI if needed and still requires a compatible Node.js and writable npm cache. It does not fix an old Node version. Replace --help with list once credentials are configured.

Browser login problems

Browser-assisted setup requires CLI 0.4.0 or newer. Upgrade with npm install -g tylor-cli@latest, then run tylor login.

Symptom	Recovery
The browser does not open	Run tylor login --no-browser, then open the printed link yourself.
The browser asks you to sign in	Sign in to your existing Tylor account, then compare the terminal code and choose Connect CLI.
Connect CLI is disabled	Check the code, then select the confirmation checkbox. Expired requests need a fresh tylor login.
Wrong account or unexpected code	Use Use a different account, or Decline and start a fresh login. Never approve a request someone sent you.
Login expired or timed out	Run tylor login again and approve within ten minutes. Use the newest link and code.
Backend does not support browser login	Ask the administrator to deploy the matching backend and frontend; manual API-key setup remains available.
TYLOR_API_KEY overrides saved login	Keep it for automation, or run unset TYLOR_API_KEY in macOS/Linux Terminal before browser login. Remove persistent overrides from your shell/agent settings too.
Saved login belongs to another server	Unset a conflicting TYLOR_API_URL, or add that instance with tylor login --api-url … --web-url … and select its saved account. Do not change only the API URL while retaining another server’s key.
Could not save config	Check ownership and permissions of ~/.config/tylor. The CLI preserves existing settings and tries to revoke the new key. If it reports failed revocation, revoke the new device key in Tylor before retrying.
Invalid JSON config	Fix the JSON object locally without sharing its contents. Login will not overwrite a malformed config file.
Config is locked	Wait for another CLI save to finish. Only if no Tylor process is saving, remove the reported config.json.lock file and retry.
Account access denied	Open Tylor and check whether your account is awaiting approval or suspended. Ask your administrator.

A browser message CLI approved means approval succeeded; wait for the terminal’s Connected as… message to confirm the config was saved. Interrupted login attempts try to cancel on the server. If the CLI reports that cancellation failed, do not approve that tab; revoke any newly created device key under Account → Advanced → API keys.

See the login walkthrough for screenshots and self-hosted setup.

Installed, but cannot connect

If tylor --help works, try the read-only tylor list command.

Symptom	What to check
no API key	Run tylor login in the same machine/user environment, or configure TYLOR_API_KEY for automation. Browser sign-in alone does not authenticate the CLI.
HTTP 401	Check that the key belongs to the selected Tylor instance and has not been revoked. An environment key overrides the key in the config file.
HTTP 403	Check your account’s access to the requested project and any account restrictions with its owner or administrator.
Connection, DNS, or TLS error	Check your network and TYLOR_API_URL. It defaults to https://api.tylor.app; a self-hosted instance needs its own API endpoint. Ask IT about a proxy or certificate error; do not disable TLS verification.
(no projects) or a missing project	Check the account and server associated with the key. Projects stored only in a browser’s local workspace are unavailable to the CLI.

See CLI and API keys for setup and the API activity console. Installation failures and requests with invalid keys do not appear in that console. For Git library backup errors, see library backups.

What to share when asking for help

Include your macOS version, whether the Mac is managed by your institution, the failing command, the error message, and the output of:

node -v
npm -v
command -v node
command -v npm
command -v tylor
npm config get prefix
npm list -g tylor-cli --depth=0

Remove personal usernames from paths if you prefer. Never share API keys, your entire environment, or the contents of ~/.config/tylor/config.json. Inspect npm debug logs before sharing them; start with the relevant error excerpt rather than uploading the full log.

Multiple-account problems (CLI 0.6.0+)

Message or symptom	Recovery
Account is not saved	Run tylor auth list, then tylor login --alias company to add the missing login. Approve the intended account.
This account is already saved	Use tylor login --replace to reconnect that account; all other accounts remain saved.
Account selection is ambiguous	The email occurs on several servers. Select the ID from auth list, or give each entry a unique alias with auth alias.
--account conflicts with TYLOR_API_KEY	Unset the environment key before selecting a saved account. On macOS/Linux, env -u TYLOR_API_KEY tylor --account company tree scopes that change to one command.
Account verification failed, or email changed	Reconnect the intended account with tylor login --replace. Commands never fall back to another account.
Place --account before the command	Use tylor --account company tree, not tylor tree --account company.
Wrong account without --account	Check tylor auth status and auth list. Choose tylor auth default personal; environment keys still override this default.
Checkout belongs to another account	Keep its local files and pending receipts. Pull into a separate directory with the intended account. This also applies to shared projects.
Checkout predates account binding	Preserve edits, pull a fresh checkout, and merge. Recover any uncertain pending write using CLI 0.5.0 and the original credential before migrating; do not remove its receipt.
Another account uses this backup directory	Initialize with a separate --dir for each account. Do not remove the account marker to bypass this check.

See multiple-account setup.