Waymaker CLI & MCP

What You Get

The Waymaker CLI connects your IDE to Commander. Install it once, then use whichever features you need:

Feature	Command	What it does
File Sync	waymaker sync start	Markdown files sync bidirectionally with Commander documents
MCP Server	waymaker serve	AI assistants (Claude, Cursor) can read/write your tasks
Terminal Kanban	waymaker kanban	View and manage your taskboard without leaving the terminal

You don't need to use all of them. Want just MCP tools for Claude? Skip sync. Want just file sync? Skip MCP. They're independent.

How It Works

1. Install the CLI (one-time)
2. Login with your Commander account via browser
3. Connect your project directory to a workspace and taskboard
4. Use whichever features you need

Your IDE                    Commander
   │                            │
   │  ┌──────────────────┐      │
   │  │   Waymaker CLI   │      │
   │  ├──────────────────┤      │
   ├──│ sync             │──────┤  Files ↔ Documents
   │  │ serve (MCP)      │──────┤  AI Tools ↔ Tasks
   │  │ kanban           │──────┤  Terminal ↔ Taskboard
   │  └──────────────────┘      │
   │                            │

Two Ways to Connect

Method	Best For	Install?
CLI (@waymakeros/cli)	Terminal users — deploy apps, manage Host, sync files, run commands	Yes — npm install -g @waymakeros/cli
Cloud MCP	AI agents (Claude Desktop, Cursor, Claude Code)	No — just add an access key to your AI tool config

Using an AI agent? See the AI Agent Setup Guide — no CLI installation needed.

Quick Start

1. Install the CLI

# Using npm (recommended)
npm install -g @waymakeros/cli

# Or clone and build
git clone https://github.com/stuart-leo/waymaker.git
cd waymaker/packages/waymaker-cli
npm install
npm run build

2. Login to Commander

waymaker auth login

This opens your browser for secure OAuth authentication. Sign in with your Commander account and approve access.

3. Initialize Your Project

Navigate to your project directory and run:

waymaker init

Follow the interactive prompts to:

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

This creates a .commander/ folder with your connection settings.

4. Start Syncing

waymaker sync start

Your tasks and documents now sync between your IDE and Commander.

Commands

Authentication

Command	Description
waymaker auth login	Login via browser OAuth
waymaker auth logout	Remove stored credentials
waymaker auth status	Check authentication state

Project Setup

Command	Description
waymaker init	Connect directory to Commander

Sync

Command	Description
waymaker sync start	Start the sync daemon
waymaker sync status	Check sync daemon status
waymaker sync all	Sync all files immediately

Tools

Command	Description
waymaker kanban	Open terminal kanban board
waymaker serve	Start MCP server for AI assistants

How It Works

OAuth 2.1 with PKCE

The CLI uses industry-standard OAuth 2.1 with PKCE (Proof Key for Code Exchange) for secure authentication:

1. CLI generates a cryptographic code challenge
2. Browser opens Commander OAuth page
3. You sign in with Clerk authentication
4. Commander issues an authorization code
5. CLI exchanges code for access tokens
6. Tokens stored securely in ~/.waymaker/auth.json

Project Configuration

When you run waymaker init, the CLI creates:

your-project/
├── .commander/
│   └── config.json    # Workspace, project, and taskboard IDs
└── ... your files

Bidirectional Sync

The sync daemon watches for changes:

• IDE → Commander: Markdown files sync as documents, TODO comments become tasks
• Commander → IDE: Task updates appear in your editor, documents update locally

AI Assistant Integration

MCP Server Mode

Start the MCP server to enable AI assistants to interact with Waymaker:

waymaker serve -p /path/to/project

This exposes Waymaker tools to Claude Code, Cursor, and other MCP-compatible assistants.

Available Tools

When running in MCP mode, AI assistants can:

• List and manage tasks
• Read, create, and update documents
• Create spreadsheets with initial data
• Create folders for organization
• Place content in folders
• Check sync status
• Create new tasks from conversation context

Troubleshooting

"Authorization Error" During Login

1. Ensure you have a Commander account
2. Check you're part of an organization
3. Try logging out and back in: waymaker auth logout && waymaker auth login

"No workspaces found" During Init

1. Verify you're logged in: waymaker auth status
2. Check you have workspaces in Commander
3. Ensure your organization has workspaces created

Sync Not Working

1. Check daemon is running: waymaker sync status
2. Verify .commander/config.json exists
3. Restart the daemon: waymaker sync start

Next Steps

• Installation Guide - Detailed setup for all platforms
• Authentication - OAuth flow details
• Init Command - Project configuration
• Project Organization - Prepare your docs before syncing
• Sync Command - Sync daemon setup
• AI Agent Setup - MCP server configuration

---

Need more help? Contact support at help.waymakerone.com