Troubleshooting

Node.js LTS is required because Ellygent CLI is currently installed from GitHub using npm.

winget install OpenJS.NodeJS.LTS
node --version
npm --version
irm https://ellygent.com/cli/install.ps1 | iex

npm should be installed together with Node.js LTS. If node --version works but npm --version does not, reinstall Node.js LTS and reopen PowerShell.

node --version
npm --version
winget install OpenJS.NodeJS.LTS

Retry the checkout-and-build install manually so you can see the full clone, npm, or build error output.

git clone --depth 1 https://github.com/EEQuality/ellygent-cli.git
cd ellygent-cli
npm install
npm run build
npm install -g .

The global npm bin directory must be present in PATH before PowerShell can resolve ellygent.

npm bin -g
npm list -g --depth=0
where.exe ellygent

VS Code caches PATH when it starts. If the installer completed successfully in PowerShell, restarting VS Code usually fixes the integrated terminal immediately.

# Close all VS Code windows completely
# Reopen VS Code
# Open a new PowerShell terminal
ellygent --help

$env:Path += ";$env:APPDATA\npm"
ellygent --help

These commands show whether the current terminal can see the install directory and the resolved binary.

npm bin -g
where.exe ellygent
Get-Command ellygent
[Environment]::GetEnvironmentVariable("Path", "User")

Use this only if npm installed the CLI successfully but PowerShell still cannot resolve the global npm bin directory.

$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$npmBin = npm bin -g

if ($userPath -notlike "*$npmBin*") {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$npmBin", "User")
}

Symptoms:

Error: 401 Unauthorized or login failed

Common Causes:

• Invalid or expired Personal Access Token

• Wrong API URL

• An older CLI build is being resolved first

Solutions:

# Confirm the token starts with elly_pat_
# Then retry with the same PAT

ellygent config
# Verify api-url is correct

# Go to Account -> Personal Access Tokens in the web UI
# Revoke the old token and create a new one

ellygent auth login --token <your-personal-access-token>
ellygent whoami

Symptoms:

ECONNREFUSED, ETIMEDOUT, or unable to reach the API

Common Causes:

• Firewall or proxy blocking connections

• Incorrect API URL

• API service is down

Solutions:

ellygent config
# Verify api-url is correct and accessible

curl https://www.ellygent.com/api/health
# Should return 200 OK

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# Ensure outbound HTTPS (443) is allowed
# Contact IT if behind a corporate firewall

Symptoms:

Sync command fails, ZIP extraction errors, or missing files

Common Causes:

• Network interruption during download

• Insufficient disk space

• Corrupt ZIP package

• Project or version not found

Solutions:

ellygent context projects --org <org-name>
ellygent context versions --project <project-id>

df -h .  # Unix/macOS
# Ensure sufficient free space

ellygent context pull --project <project-id> --version <version>

rm -rf .ellygent/
ellygent context pull --project <project-id> --version <version>

Symptoms:

Token expired or invalid token errors

Common Causes:

• PAT was revoked

• The stored token no longer has access

• A different CLI install is being used

Solutions:

ellygent auth login --token <your-personal-access-token>

# Go to Account -> Personal Access Tokens
# Create a new token and update environment

rm ~/.ellygent/config.json
ellygent auth login --token <your-personal-access-token>