Installation

Install and configure WS.Eng CLI for local development.

Prerequisites

Before installing, ensure you have:

Node.js 24 or later (download)
Git 2 or later (download)
GitHub CLI 2 or later (download)
AWS Account Access: You must have access to the WS.Eng AWS account (RAM-AWS-Dev-WSEngineering-WSEng-Admin). Reach out to your engineering manager for access. See the AWS setup guide.

Installation Steps

1. Clone the Repository

git clone https://github.com/trilogy-group/ws-eng-cli.git
cd ws-eng-cli

2. Install Dependencies

The project uses pnpm as its package manager:

# Install pnpm globally (if not already installed)
npm install -g pnpm

# Install project dependencies
pnpm install

3. Link CLI Globally

Make the CLI available system-wide:

pnpm link --global

This creates a global wseng command you can run from any directory.

WSL users: use pnpm add -g . instead — pnpm link --global does not reliably produce a working global wseng on WSL. See the WSL / headless section below.

4. Verify Installation

Check that the CLI is accessible:

wseng --version

You should see the current version number.

Initial Setup

Run Init Command

Initialize the CLI within your project repositories:

cd /path/to/your/project
wseng init

The wseng init command:

Creates .wseng configuration files (personal and project-level)
Sets up working directory context
Prepares the CLI for first use

You can run wseng init multiple times safely. It's the bridge between installation and configuration.

Verify Setup

Run a simple command to confirm everything works:

wseng --help

You should see the full list of available commands grouped by category.

WSL / Headless Environments

Linux-on-Windows (WSL) and other headless setups need a few deviations from the default instructions:

Install with pnpm add -g ., not pnpm link --global. From the cloned ws-eng-cli directory:
```
pnpm add -g .
```
The link-based install does not reliably produce a working global wseng binary on WSL.
Use Node 24 via nvm, and do not run pnpm setup. Install Node through nvm and let it manage the global bin directory; running pnpm setup on top of an nvm-managed Node breaks global installs.
saml2aws needs the pass+gpg keyring backend. wseng init --aws drives saml2aws, which stores credentials in a keyring. On WSL the default file backend does not work with the credential flow — configure the pass backend (backed by gpg) before running wseng init --aws:
```
# one-time setup
sudo apt install pass gnupg
gpg --generate-key
pass init "<your-gpg-key-id>"
```
Then run wseng init --aws as usual.

Common Installation Issues

❌ Bad: `wseng: command not found`

This means global linking failed.

Solution:

cd ws-eng-cli
pnpm link --global

# Verify pnpm's global bin directory is in PATH
pnpm root -g

Add pnpm's global bin directory to your PATH if needed.

❌ Bad: Permission errors during `pnpm install`

Solution:

# Don't use sudo with pnpm
# Instead, fix npm/pnpm permissions:
mkdir ~/.pnpm-global
pnpm config set store-dir ~/.pnpm-global

Next Steps

After installation, you need to authenticate with AWS, GitHub, and optionally Google to unlock full CLI functionality.

Authentication

Set up AWS profiles, GitHub CLI login, and Google authentication.

Configuration

Understand .wseng configuration files and customize CLI behavior.

Ticket Lifecycle Workflow

Start using the CLI for your first ticket.

Introduction

Authentication