Waymaker CLI Installation

Overview

Using an AI agent (Claude Desktop, Cursor)? You don't need the CLI — see the Cloud MCP setup instead. The CLI is for terminal users who want to run commands like waymaker host apps deploy or waymaker sync start.

This guide walks you through installing and configuring the Waymaker CLI on your local machine.

What You'll Learn

• How to install the CLI
• How to authenticate with Commander via OAuth
• How to configure your environment
• How to verify your installation

Before You Start

• Node.js 18 or higher installed
• npm 9 or higher installed
• A Commander account at commander.waymakerone.com
• Member of an organization in Commander

Step-by-Step Installation

Step 1: Install the CLI

Option A: npm (Recommended)

npm install -g @waymakeros/cli

Option B: Build from Source

# Clone the repository
git clone https://github.com/stuart-leo/waymaker.git
cd waymaker/packages/waymaker-cli

# Install dependencies and build
npm install
npm run build

# Link globally (optional)
npm link

Step 2: Authenticate with OAuth

waymaker auth login

This command:

1. Opens your browser to Commander's OAuth page
2. Prompts you to sign in with your Commander account
3. Asks you to authorize the CLI access
4. Redirects back to the CLI with your credentials

The CLI uses OAuth 2.1 with PKCE for secure authentication - no API keys required.

Step 3: Verify Authentication

waymaker auth status

Expected output:

Authenticated
User ID: user_xxxxxxxx
Organization: Your Organization Name
Scopes: read, write, sync

Step 4: Initialize a Project

Navigate to your project directory:

cd /path/to/your/project
waymaker init

Follow the interactive prompts:

1. Select your workspace
2. Select your project
3. Select your taskboard

This creates a .commander/config.json file with your connection settings.

Configuration Files

~/.waymaker/auth.json

Stores your authentication tokens (created automatically after login):

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_at": "2026-02-03T..."
}

Security: Keep this file private. Never commit it to version control.

.commander/config.json

Per-project configuration (created by waymaker init):

{
  "workspace_id": "uuid-here",
  "project_id": "uuid-here",
  "taskboard_id": "uuid-here"
}

Add .commander/ to your .gitignore if you don't want to share project settings.

AI Agent Setup

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "waymaker": {
      "command": "waymaker",
      "args": ["serve", "-p", "/path/to/project"]
    }
  }
}

Claude Code loads MCP servers from .mcp.json, not .claude/settings.json.

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "waymaker": {
      "command": "waymaker",
      "args": ["serve", "-p", "."]
    }
  }
}

See AI Agent Setup Guide for detailed configuration.

Partners: Per-Project Organization Isolation

If you manage multiple client organizations, do NOT rely on global MCP config. Your global config uses your own org's identity. Every MCP operation — tasks, documents, workspaces — will land in YOUR org, not the client's.

Create a per-project .mcp.json in each client project root with the client's access key:

{
  "mcpServers": {
    "waymaker": {
      "command": "waymaker",
      "args": ["serve"],
      "env": {
        "WAYMAKER_API_KEY": "wm_sk_client_access_key_here"
      }
    }
  }
}

Claude Code loads MCP servers from .mcp.json, not .claude/settings.json. Add .mcp.json to .gitignore.

The env block passes the client's access key to the CLI, overriding your global OAuth token. Always run waymaker auth status first to confirm you see the client's organization name.

Troubleshooting

"Authorization Error" During Login

Symptoms: Browser shows "Authorization Error" after attempting to sign in.

Solutions:

1. Ensure you have a Commander account
2. Verify you're part of an organization
3. Try again: waymaker auth logout && waymaker auth login
4. Clear browser cache and try again

"No workspaces found" During Init

Symptoms: waymaker init shows no workspaces to select.

Solutions:

1. Verify authentication: waymaker auth status
2. Ensure your organization has workspaces in Commander
3. Check you have access to at least one workspace

"Command not found"

Symptoms: waymaker: command not found

Solutions:

1. Check npm global bin is in PATH:

   npm config get prefix
   # Add the bin directory to PATH
   

2. For source builds, use the full path:

   node /path/to/waymaker/packages/waymaker-cli/dist/cli/index.js
   

3. Or create an alias:

   alias waymaker="node /path/to/waymaker/packages/waymaker-cli/dist/cli/index.js"
   

Build Errors

Symptoms: TypeScript errors during npm run build

Solutions:

# Clear and reinstall
rm -rf node_modules dist
npm install
npm run build

Permission Denied on macOS/Linux

Solutions:

Don't use sudo. Instead, fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Add the export to your shell profile (~/.bashrc, ~/.zshrc).

Updating the CLI

npm Installation

npm update -g @waymakeros/cli

From Source

cd waymaker/packages/waymaker-cli
git pull origin main
npm install
npm run build

Uninstalling

# Remove global package
npm uninstall -g @waymakeros/cli

# Remove auth tokens
rm -rf ~/.waymaker

# Remove project config (per-project)
rm -rf .commander

Related Articles

• Authentication Commands - OAuth flow details
• Init Command - Project configuration
• Sync Command - Bidirectional sync setup
• AI Agent Setup Guide - MCP server configuration

---

Still having issues? Contact support at help.waymakerone.com