# How to Send Files with Custom Display Filenames in wacli

> Learn how to send files with custom display filenames using the wacli send file --filename flag. wacli handles actual file paths for MIME detection and hashing.

- Repository: [Peter Steinberger/wacli](https://github.com/steipete/wacli)
- Tags: how-to-guide
- Published: 2026-04-17

---

**Use the `--filename` flag in `wacli send file` to specify a custom display name while the actual file path remains used for MIME detection and content hashing.**

The `wacli` command-line tool for WhatsApp automation, maintained in the `steipete/wacli` repository, supports sending files with custom display filenames. This feature allows you to present a different name to recipients than the actual file stored on disk, which is particularly useful for renaming reports, masking temporary filenames, or standardizing document titles across your organization.

## Understanding the `--filename` Flag

The `--filename` flag is defined in the CLI layer at [`cmd/wacli/send_file_cmd.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/send_file_cmd.go) (lines 69-71). When you invoke `wacli send file`, this flag captures your custom display name and passes it through the application layers to the WhatsApp message constructor.

If you omit the flag, `wacli` automatically uses the basename of the file path specified in `--file` as the display name.

## How wacli Processes Custom Display Filenames

### CLI Flag Parsing and Propagation

In [`cmd/wacli/send_file_cmd.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/send_file_cmd.go), the `--filename` value is stored in a local variable and passed to the `sendFile` helper function (lines 49-51). The function signature accepts this as a distinct `filename` parameter, separating the display name concerns from the physical file path.

### Name Resolution Logic

Inside [`cmd/wacli/send_file.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/send_file.go) (lines 29-33), the `sendFile` function implements the resolution logic:

- If `filename` is non-empty after trimming, it becomes the `name` variable
- If empty, `name` defaults to the basename of the actual file path

This `name` variable represents the final display name that recipients see in their WhatsApp client.

### WhatsApp Protobuf Construction

For document-type uploads, the resolved `name` is injected into the WhatsApp protocol buffer at [`cmd/wacli/send_file.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/send_file.go) (lines 1010-1014). The code sets both `FileName` and `Title` fields of `waProto.DocumentMessage` to the custom display name.

These fields control what appears as the document title in the recipient's chat interface, while the actual file content and MIME type detection use the original `--file` path.

### Local Storage Persistence

After successful transmission, `wacli` persists the custom filename in the local SQLite database via `UpsertMessage` in [`internal/store/messages.go`](https://github.com/steipete/wacli/blob/main/internal/store/messages.go) (lines 21-22 and 33-35). The database schema includes a dedicated `filename` column added in migration version 2, defined in [`internal/store/migrations.go`](https://github.com/steipete/wacli/blob/main/internal/store/migrations.go) (lines 132-134).

This allows message history queries to display the correct custom filename even if the original file has been moved or renamed on disk.

## Practical Code Examples

Send a quarterly report with a standardized display name while keeping the original filename for internal tracking:

```bash
wacli send file \
    --to 15551234567 \
    --file ./reports/2024-Q1-draft-final-v3.pdf \
    --filename "Q1-2024-Report.pdf" \
    --caption "Quarterly performance summary"

```

**JSON output** (using `--json` flag):

```json
{
  "sent": true,
  "to": "15551234567@s.whatsapp.net",
  "id": "ABCD1234EFGH5678",
  "file": {
    "name": "Q1-2024-Report.pdf",
    "mime_type": "application/pdf",
    "media": "document"
  }
}

```

**Default text output:**

```

Sent Q1-2024-Report.pdf to 15551234567@s.whatsapp.net (id ABCD1234EFGH5678)

```

The `--filename` flag works consistently across document, image, video, and audio uploads, though for media types the visible caption often takes precedence over the filename in the WhatsApp UI.

## Summary

- Use `--filename` with `wacli send file` to set a custom display name independent of the source file path
- The actual file path (`--file`) drives MIME type detection and content hashing, while `--filename` populates the WhatsApp message metadata
- The custom name is stored in `waProto.DocumentMessage.FileName` and `Title` fields for document uploads
- Local SQLite persistence via `UpsertMessage` maintains the custom filename in the `messages` table for history tracking
- If `--filename` is omitted, `wacli` automatically uses the basename of the `--file` argument

## Frequently Asked Questions

### What happens if I don't specify the `--filename` flag?

If you omit the `--filename` flag, `wacli` extracts the basename from the `--file` path and uses that as the display name. This logic is implemented in [`cmd/wacli/send_file.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/send_file.go) (lines 29-33), where the code checks if the `filename` parameter is empty and defaults to the file's basename.

### Does the custom filename affect MIME type detection?

No. The custom filename provided via `--filename` is used exclusively for display purposes in the WhatsApp interface. MIME type detection and content hashing use the actual file path specified in `--file`. According to the source code in [`cmd/wacli/send_file.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/send_file.go), the display name is resolved separately from the media type detection logic.

### Is the custom filename visible in message history?

Yes. When you send a file with a custom filename, `wacli` persists this name in the local SQLite database via the `UpsertMessage` function in [`internal/store/messages.go`](https://github.com/steipete/wacli/blob/main/internal/store/messages.go). The database schema includes a dedicated `filename` column (added in migration version 2), ensuring that message history queries display the correct custom filename even if the original file has been moved or renamed.

### Can I use custom filenames for images and videos?

Yes, the `--filename` flag works for all media types including images, videos, and audio files. However, for these media types, the WhatsApp UI typically prioritizes the caption text over the filename in the display. The custom filename is still sent in the message metadata and stored in local history, but recipients may see the caption more prominently than the filename for non-document media.