How WACLI_DEVICE_LABEL and WACLI_DEVICE_PLATFORM Control WhatsApp Client Identity in wacli

WACLI_DEVICE_LABEL sets the human-readable device name that WhatsApp displays for this client, while WACLI_DEVICE_PLATFORM determines the platform enum (Android, iOS, Chrome, etc.) that controls server-side feature compatibility.

The wacli command-line tool by steipete/wacli provides a WhatsApp Web client implementation that relies on the go.mau.fi/whatsmeow library. At startup, wacli reads two specific environment variables to configure how the WhatsApp servers identify and treat the client session. Understanding these variables is essential for deployments where you need to emulate specific device types or ensure proper feature flag support.

What WACLI_DEVICE_LABEL Controls

The WACLI_DEVICE_LABEL environment variable customizes the operating system identity that wacli reports to WhatsApp. This value influences both local storage and the network handshake payload.

OS Info Storage

When wacli initializes, it calls store.SetOSInfo(label, [3]uint32{0,1,0}) in cmd/wacli/main.go (lines 20-31). This function stores the label as the operating-system name in the local SQLite database, which WhatsApp uses to display the device name in the "Linked Devices" section of the mobile app.

User-Agent Configuration

The same label propagates to the WhatsApp User-Agent string sent during the client handshake. According to the source code in cmd/wacli/main.go, the label is assigned to:

• store.BaseClientPayload.UserAgent.Device – identifies the specific device model
• store.BaseClientPayload.UserAgent.Manufacturer – identifies the device manufacturer

This dual assignment means that setting WACLI_DEVICE_LABEL="Pixel 5" causes WhatsApp to register the client as a "Pixel 5" manufactured by "Pixel 5".

What WACLI_DEVICE_PLATFORM Controls

The WACLI_DEVICE_PLATFORM environment variable determines the platform type enum that controls which WhatsApp feature set the server enables for the session.

Platform Type Parsing

In cmd/wacli/main.go (lines 34-44), wacli parses the raw string value using a helper function parsePlatformType. This function maps string inputs to the waCompanionReg.DeviceProps_PlatformType enum defined in the go.mau.fi/whatsmeow/proto/waCompanionReg package.

Valid values include:

• ANDROID
• IOS
• CHROME
• EDGE
• SAFARI

The resulting enum is stored in store.DeviceProps.PlatformType, which becomes part of the device properties payload sent during registration.

Default Behavior

If WACLI_DEVICE_PLATFORM is unset or empty, wacli defaults to CHROME. This default is handled in the initialization logic at cmd/wacli/main.go lines 22-26, ensuring that standard desktop deployments work without explicit configuration.

Practical Configuration Examples

Configure these environment variables before running wacli to control how WhatsApp identifies your client:

# Example 1: Custom desktop label

export WACLI_DEVICE_LABEL="My-Desktop"
wacli sync

# Example 2: Emulate an Android device

export WACLI_DEVICE_PLATFORM=ANDROID
wacli sync

# Example 3: Combined configuration for specific device emulation

export WACLI_DEVICE_LABEL="Pixel 5"
export WACLI_DEVICE_PLATFORM=ANDROID
wacli sync

Running wacli after setting these variables changes the metadata stored locally via store.SetOSInfo and modifies the BaseClientPayload sent during the WhatsApp login handshake. This can affect media feature availability, encryption protocol versions, and how the device appears in the WhatsApp mobile app's linked devices list.

Implementation Details in cmd/wacli/main.go

The environment variable handling is centralized in cmd/wacli/main.go within the main initialization function:

• Lines 20-31: Read WACLI_DEVICE_LABEL and call store.SetOSInfo(label, [3]uint32{0,1,0}) to persist the OS name to the local store.
• Lines 22-26: Set store.BaseClientPayload.UserAgent.Device and store.BaseClientPayload.UserAgent.Manufacturer to the label value.
• Lines 34-44: Read WACLI_DEVICE_PLATFORM, parse it via parsePlatformType, and assign the result to store.DeviceProps.PlatformType.

These assignments happen before the WhatsApp client establishes its connection, ensuring the server receives the custom identity from the first handshake packet.

Summary

• WACLI_DEVICE_LABEL controls the human-readable device name stored in the local database and broadcast to WhatsApp as the User-Agent device and manufacturer fields.
• WACLI_DEVICE_PLATFORM sets the platform enum (Android, iOS, Chrome, etc.) that determines server-side feature flags, parsed by parsePlatformType in cmd/wacli/main.go.
• Both variables are optional; omitting them defaults to an empty label and the CHROME platform type.
• These settings directly influence how the client appears in the WhatsApp mobile app's "Linked Devices" list and which protocol features the server enables.

Frequently Asked Questions

What happens if I don't set WACLI_DEVICE_LABEL?

If WACLI_DEVICE_LABEL is unset, wacli passes an empty string to store.SetOSInfo and the User-Agent fields. WhatsApp will display a generic or empty device name in the Linked Devices list, and the manufacturer/device fields in the handshake payload will be blank.

What values are valid for WACLI_DEVICE_PLATFORM?

Valid values correspond to the waCompanionReg.DeviceProps_PlatformType enum and include ANDROID, IOS, CHROME, EDGE, and SAFARI. The parsePlatformType function in cmd/wacli/main.go handles the string-to-enum mapping. Invalid values will typically default to CHROME or cause a parsing error depending on the implementation.

Does changing these variables affect an existing session?

Yes, but the changes only take effect on the next connection or re-authentication. The store.SetOSInfo call writes to the local database immediately, but WhatsApp servers typically only re-evaluate the device identity during the initial handshake or when the client re-registers. To ensure the server sees the new label or platform, you may need to log out and log back in.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}