Waymaker auth

Overview

Manage authentication with Waymaker Commander using secure OAuth 2.1 with PKCE.

Usage

waymaker auth <subcommand>

Subcommands

Subcommand	Description
login	Authenticate via browser OAuth
logout	Remove stored credentials
status	Check authentication status

Commands

Login

Authenticate with Commander via your browser:

waymaker auth login

What happens:

1. CLI generates a cryptographic code challenge (PKCE)
2. Your browser opens to Commander's OAuth page
3. You sign in with your Commander account
4. You authorize the CLI to access your account
5. Browser redirects to localhost callback
6. CLI exchanges the code for access tokens
7. Tokens are stored in ~/.waymaker/auth.json

Output:

Waymaker Authentication
========================

Opening browser for authentication...

If browser doesn't open, visit:
https://mcp.waymakerone.com/oauth/authorize?...

Waiting for authentication...
Authorization received. Exchanging for tokens...

Authentication successful!
User: user_xxxxxxxx
Organization: Waymaker Head Office

Logout

Remove stored credentials:

waymaker auth logout

Output:

Logged out successfully.

This deletes ~/.waymaker/auth.json.

Status

Check current authentication state:

waymaker auth status

When authenticated:

Authenticated
User ID: user_xxxxxxxx
Organization: Waymaker Head Office
Scopes: read, write, sync
Expires: 2026-02-03T20:00:00Z

When not authenticated:

Not authenticated. Run 'waymaker auth login' to authenticate.

OAuth Flow Details

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

1. No API keys required - Authentication is handled via your browser
2. Secure by design - PKCE prevents authorization code interception
3. Token refresh - Tokens auto-refresh when expired
4. Organization scope - Tokens include your organization context

Token Storage

Credentials are stored in ~/.waymaker/auth.json:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_at": "2026-02-03T20:00:00Z",
  "user_id": "user_xxxxxxxx",
  "organization_id": "org_xxxxxxxx"
}

Security note: Keep this file private. It's created with 600 permissions (owner read/write only).

Troubleshooting

"Authorization Error" in Browser

Symptoms: Browser shows "Authorization Error" page.

Causes:

• Not signed in to Commander
• Not part of an organization
• Invalid OAuth parameters

Solutions:

1. Ensure you have a Commander account at commander.waymakerone.com
2. Verify you're part of an organization
3. Try again: waymaker auth logout && waymaker auth login

"Browser didn't open"

Symptoms: No browser window appears.

Solutions:

1. Copy the URL shown in terminal and paste into browser manually
2. Check your default browser settings
3. On headless systems, use the URL to authenticate on another device

"Token expired"

Symptoms: Commands fail with authentication errors.

Solutions:

waymaker auth login

Tokens are automatically refreshed, but if refresh fails, re-login.

"No organization"

Symptoms: Auth succeeds but organization shows as null.

Solutions:

1. Ensure you're part of an organization in Commander
2. If you just joined, try logging out and back in
3. Contact your organization admin

Related Commands

• init - Initialize project connection
• sync - Start file synchronization
• workspaces - List available workspaces