Documentation

CLI Installation

Using an AI assistant (Claude Desktop, Claude Code, Cursor)? You may not need the CLI at all — see Connecting an MCP client instead. The CLI is for scripting from a terminal or CI.

Before you start

Node.js 18+ and npm 9+
An API key (wm_sk_…) — see Authentication

Install

npm install -g @waymakeros/cli

Authenticate

The CLI reads your API key from an environment variable — there's no login flow.

export WAYMAKER_API_KEY=wm_sk_your_key_here

Or add it to a .env file in your project (the CLI loads it automatically via dotenv).

Verify it worked:

waymaker auth status

✓ Authenticated
User ID: user_xxxxxxxx
Organization: org_xxxxxxxx
Permissions: commander:read, commander:write, host:read, host:deploy, sync:read, sync:write

If your key is scoped to specific workspaces or projects, Workspaces: and Projects: lines appear too — only when the key isn't org-wide.

Initialize a project

cd /path/to/your/project
waymaker init

This writes .commander/config.json in the current directory — a small file the CLI uses to remember your current workspace/project context between commands. Then set that context:

waymaker workspaces list
waymaker workspaces use <workspaceId>

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

Configuration files

File	What it holds
`~/.waymaker/config.json`	Global preferences (output format, etc.)
`.commander/config.json`	Per-project context — current workspace/project

Neither file stores your API key — that only ever lives in WAYMAKER_API_KEY (environment/.env), never written to disk by the CLI itself.

waymaker config              # show current config
waymaker config <key> <value>

Troubleshooting

"API key not found" / "Invalid API key format"

WAYMAKER_API_KEY isn't set, or doesn't start with wm_sk_. Set it and re-run waymaker auth status. Mint a new key at admin.waymakerone.com/api/keys if you've lost it — see Managing API Keys.

"Command not found: waymaker"

npm's global bin directory isn't on your PATH.

npm config get prefix
# add <prefix>/bin to your PATH

Permission denied on macOS/Linux installing globally

Don't use sudo. Point npm's global prefix at a directory you own instead:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH   # add to your shell profile

Updating

npm update -g @waymakeros/cli

Uninstalling

npm uninstall -g @waymakeros/cli
rm -rf ~/.waymaker        # global config
rm -rf .commander          # per-project config, run from the project directory