Fantasi CLI

The Fantasi CLI is a host-side tool that wraps the device's command and storage interfaces into a single interactive shell. It connects over USB or BLE, forwarding commands to the firmware while also providing file-management commands for device storage. Those file operations use framed protobuf over WebUSB/BLE, or the synthetic MSC Fantasi FAT volume with the legacy serial transport.

Building

A bare make (no PLATFORM) builds the host CLI alongside the firmwares. To build just the host tool:

make cli        # or: make -C cli

The binary is placed at build/cli/fantasi. It has no filesystem dependency of its own: device storage is exposed by the firmware as a synthetic FAT volume labelled Fantasi, which the host OS mounts like any USB stick - the CLI does plain file I/O against that mountpoint, so there is no on-disk-format coupling. Requires libreadline-dev for line editing and history, plus udisksctl (udisks2) and findmnt (util-linux) to mount the FAT. BLE transport is compiled in only when libsystemd (BlueZ over D-Bus) is available at build time; without it the --ble flags are unavailable.

Usage

fantasi [--usb|--ble|--ble-addr=ADDR|--serial] [--name NAME] [-c COMMAND]
        [/dev/ttyACMx] [/dev/sdX]

All arguments are optional:

• No arguments - auto-detect a Fantasi device over USB (VID 1209 / PID 0001, resolving the CDC and MSC interfaces). If no USB device is found, it falls back to BLE.
• /dev/ttyACMx and/or /dev/sdX - pin a specific CDC port and/or MSC block device.
• --name NAME - select a specific device by its name (the name whoami prints) when several Fantasi devices are connected. The name is the device's USB serial descriptor and BLE advertised name (Fantasi <NAME>), so it disambiguates over USB and BLE alike.
• --ble - connect over BLE to the first paired/available Fantasi.
• --ble-addr=AA:BB:CC:DD:EE:FF - connect over BLE to a specific address.
• --usb - require the WebUSB protobuf transport (the default USB upgrade when available).
• --serial - retain the legacy CDC/MSC transport and do not upgrade to WebUSB.
• -c COMMAND - run one command non-interactively and exit.

Over BLE the CLI pairs on demand (it registers a BlueZ KeyboardOnly agent before connecting) - enter the passkey shown in the device's USB log. See Bluetooth for pairing details.

Every --usb or --ble process opens an independent firmware session. You can, for example, leave fantasi --usb -c log running and issue fantasi --usb -c whoami from another terminal. w lists all live BLE/WebUSB sessions; Ctrl-C sends cancellation only to the command owned by that process. CDC serial remains single-session for compatibility.

The FAT volume is mounted through udisksctl, which runs unprivileged for the logged-in user, so the CLI normally needs no sudo. BLE access does not touch storage at all.

Commands

All commands

Type help to see every command. Local commands (run by the host client) are shown in yellow. Firmware commands (run on the device over the selected transport) are shown in white.

Local commands:

Paths are resolved relative to the current directory. Use / for absolute paths.

Everything else is forwarded to the device over the selected transport. Commands that require hardware a target does not have report that at runtime rather than being hidden.

Device commands:

Device and system information

device

Print the short identifier for the hardware platform.

version / whoami / uptime

• version shows the CalVer release, codename, git hash, and target.
• whoami prints the unique name derived from the MCU serial number. USB and BLE discovery use this name to distinguish devices.
• uptime prints the time since boot.

batt

Print the battery percentage on targets with battery monitoring. Targets without a battery gauge report that the operation is unsupported.

free / df / ps / memtest

• free reports the FreeRTOS heap, its minimum-ever high-water mark, and free bytes in each SRAM region.
• df reports total, used, and free space for every mounted filesystem, followed by free program-flash space. RAM-backed mounts are identified as RAM rather than given a misleading capacity.
• ps lists FreeRTOS tasks with state, priority, and free stack, followed by task and heap summaries.
• memtest performs a non-destructive write/read-back test of currently free SRAM.

settings

Settings are persisted in internal storage and survive reboots.

The theme setting controls the host client's colours. Run reload after changing it to apply the new theme without restarting the client.

format

format internal erases and reformats internal LittleFS storage. A bare format only prints the warning and syntax; the explicit internal argument prevents accidental erasure.

Radio and BLE

radio

Show the target's radio-coprocessor and wireless-stack information, including whether BLE is active. A target without a supported radio reports that at runtime. See Radio Stack for the Flipper wireless-stack installation procedure.

ble

• ble shows whether BLE is on or off.
• ble on and ble off enable or disable it.
• ble list lists active connections.

scan / connect / disconnect

scan [seconds] prints discovered BLE peers with their address, RSSI, and advertised name. connect <address> connects to a peer; disconnect [handle] disconnects the connection handle shown by ble list, or all peers when no handle is supplied.

pair / unpair

Bare pair waits for an incoming pairing request, while pair <address> connects outward and creates a persistent BLE bond. unpair [address] removes that bond, or all bonds when no address is supplied.

Applications and logging

launch / kill / shortcut

• launch <path> loads an ELF application or Berry script from device storage. Modules needed by an app are normally uploaded to /ramfs by the host client before launch.
• kill [pid] stops a task by PID; bare kill stops the running app.
• shortcut lists, assigns, or runs application shortcuts in slots 0-7.

rfid

rfid is a host-client command that uploads the correct target modules, launches the RFID application, and enters its inline rfid> prompt. It requires WebUSB or BLE protobuf transport. An appended command is passed through immediately, so scripting and aliases work as they do in the native host CLI:

fantasi> rfid read t5577

See RFID for its read, write, sniff, collect, and emulation commands.

log

Bare log streams device log messages until interrupted. log write <message> writes a log message.

w

List the active BLE and WebUSB protobuf sessions. Each client owns an independent command session; cancellation from one client does not interrupt another client's command.

File commands

The host client maintains a working directory, so file commands accept relative or absolute paths. ls, cd, and pwd navigate device storage; cat prints files; mkdir, rm, and rmdir modify directories and files; cp and mv copy or rename them.

upload <local> <remote> copies a host file to device storage, while crc32 <file> verifies its size and CRC32. edit <file> downloads the file when necessary, opens $EDITOR (or a detected terminal editor), and uploads the saved result over WebUSB or BLE; with MSC it edits the mounted file directly.

USB modes

msc / cdc

msc exposes the synthetic FAT volume. Flipper Zero, Kiisu, Chameleon Ultra, and Proxmark5 keep MSC and CDC available concurrently. Proxmark3 has only enough endpoints for one at a time, so it re-enumerates in MSC mode; ejecting the volume returns it to CDC. cdc explicitly requests serial mode.

webusb

Switch USB to the framed protobuf WebUSB interface used by the launcher and by fantasi --usb.

Device control

echo / reboot / shutdown

• echo <text> tests the command connection by returning its arguments.
• reboot warm-resets the MCU.
• shutdown drains pending output and powers off targets with software power control. Unsupported targets report that instead.

dfu

Reboot into the platform's supported bootloader or DFU mode for firmware flashing. On the Flipper Zero, dfu radio activates the FUS before entering DFU for wireless-stack maintenance. See Flashing.

power

Bare power reports the allowed sleep depth, inhibitor votes, sleep statistics, wake reasons, and idle power-off timeout. power sleep on|off enables or disables CPU sleep. power off-timeout <seconds> sets the idle auto-power-off interval; zero disables it.

Client behavior

Command history

The interactive client keeps persistent history in ~/.fantasi/fantasi.log; the main prompt and rfid> prompt keep separate histories. Up/down navigate the history for the active prompt. One-shot -c commands are not recorded.

Themes

The theme comes from the device's saved theme setting. The built-in presets are synthwave (default), sunset, cyberpunk, ember, aurora, midnight, copper, mint, templeos, hotdogstand, and none.

fantasi> settings set theme cyberpunk
fantasi> reload

Colour is disabled when NO_COLOR is set, output is not a TTY, or the theme is none.

You can type any firmware command directly:

fantasi> scan 3
fantasi> ble off
fantasi> settings
fantasi> whoami

Examples

Upload a splash screen

$ build/cli/fantasi
serial: /dev/ttyACM0
storage: on-demand (FAT auto-mount)
fantasi> upload art/fantasi_splash.bin /splash.bin
art/fantasi_splash.bin -> /splash.bin (1024 bytes)
fantasi> ls
  splash.bin           1024
  settings.cfg         6

Toggle BLE and check settings

fantasi> ble off
ble off
fantasi> settings
ble=0
fantasi> ble on
ble on
fantasi> radio
secure flash: 236 KB @ 0x080C5000
BLE:   on

Check device identity

fantasi> whoami
Shetak0
fantasi> device
FZ

How it works

Device storage is presented over USB MSC as a single synthetic FAT volume (label Fantasi). The firmware synthesizes the FAT boot sector, FAT tables, and directory entries on the fly from its real filesystems - internal flash (LittleFS, mounted at /) and the RAM-backed /ramfs. Reads are served from those filesystems; writes are parsed back out of the FAT directory/data sectors and committed to the underlying filesystem. The CLI checkpoints uploads every 4 KiB, bounding firmware staging memory; each checkpoint is explicitly synchronized.

The first local command (ls, upload, …) triggers the CLI to mount that volume. On composite devices (Flipper, Kiisu, Chameleon, Proxmark5) the block device is always present alongside CDC; on switch-mode devices (Proxmark3, which reuses its CDC endpoints for MSC) the CLI first sends the msc command to flip the device into MSC mode. Either way the volume is then mounted with udisksctl, and local commands are plain stdio against the mountpoint. When the CLI next needs the serial port (a forwarded firmware command, or exit) it unmounts; on switch-mode devices it also SCSI-ejects so the firmware re-enumerates as CDC.

Serial commands are sent as raw text over the CDC port. WebUSB and BLE commands and file operations use framed protobuf requests in independent logical sessions.

Storage notes

• Removable memory cards must be formatted as FAT32. exFAT, NTFS, ext2/3/4, and other filesystems are not currently supported. Until format external support arrives, use a host computer to format it as FAT32 before inserting it.
• Because the FAT is synthetic, the host sees a normal removable drive - you can also mount and browse it with your file manager. Long (non-8.3) filenames are supported via VFAT LFN entries.
• Composite devices (FZ, Kiisu, CU, PM5) keep CDC and MSC active simultaneously, so the CLI freely interleaves commands and storage access.
• Switch-mode devices (PM3) trade the CDC endpoints for MSC, so each storage operation is bracketed by a mode switch in and a SCSI eject out; the CLI handles this transparently and waits for the CDC port to reappear.
• crc32 <file> reads a device file and prints its CRC32 and size - used by tools/flash.py to skip re-uploading unchanged resources without capturing binary data over the link.