CLI Reference

The whale-code CLI gives you full access to WhaleTools from your terminal. Manage stores, chat with agents, and run a local MCP server.

Installation

Install the CLI globally via npm. Requires Node.js 18 or later.

npm install -g whale-code

Verify the installation:

whale --version
# whale-code v1.x.x

Authentication

whale login

After login, your session is stored at ~/.whaletools/session.json. The CLI automatically refreshes expired tokens.

Check your current session:

whale status

# Output:
# Authenticated as: you@example.com
# Store: My Store (cd2e1122-...)
# Node: not running

Commands

Command	Description
whale login	Authenticate with your WhaleTools account. Opens a browser for OAuth login and stores the session locally.
whale status	Show the current authentication state, active store, and node status.
whale stores	List all stores associated with your account.
whale agent chat	Start an interactive chat session with an AI agent in your store.
whale node start	Start the local node daemon. Registers this machine as a compute node for your store.
whale mcp	Start the MCP server for integration with Claude Desktop, Cursor, or other MCP clients.

Agent Chat

Start an interactive conversation with an AI agent in your store. The agent has access to your store data and configured tools.

whale agent chat

# Start chat with a specific agent
whale agent chat --agent 72d7aaa8-2e8b-48a0-a38d-f332f69600bb

# Send a single message (non-interactive)
whale agent chat --message "What were today's sales?"

MCP Server Mode

Run the CLI as a Model Context Protocol server, enabling AI clients like Claude Desktop and Cursor to interact with your store.

# Start the MCP server
whale mcp --store your-store-id

# Or use npx without global installation
npx -y whale-code mcp --store your-store-id

See the MCP Integration guide for client configuration details.

Node Mode

Register this machine as a compute node for your store. Nodes report CPU, memory, and disk metrics via heartbeat and can execute local tasks dispatched by the platform.

whale node start

# Output:
# Node registered: 72fad484-45b8-47e7-b78c-8e74499ba730
# Heartbeat interval: 60s
# Listening for tasks...

Configuration

The CLI stores configuration at ~/.whaletools/config.json. You can also set values via environment variables.

// ~/.whaletools/config.json
{
  "defaultStore": "cd2e1122-d511-4edb-be5d-98ef274b4baf",
  "apiUrl": "https://vm.whaletools.cloud",
  "agentUrl": "https://vm.whaletools.cloud/agent"
}

// Environment variable overrides
WHALETOOLS_API_KEY=wk_live_...
WHALETOOLS_STORE_ID=cd2e1122-...