CLI Reference

Fantasi presents a USB CDC serial interface on all supported devices. Connect at 115200 baud to the enumerated port:

• Linux: /dev/ttyACM*
• macOS: /dev/tty.usbmodem*
• Windows: check Device Manager for the COM port

fantasi> _

Commands that need hardware a target doesn't have (a radio, a battery gauge) report that at runtime rather than being hidden.

The commands below run on the device. A handful of others - cat, cd, crc32, edit, ls, mkdir, pwd, reload, rfid, rm, rmdir, upload - are answered by the host client itself (the fantasi program on your computer); they are highlighted in the client's own theme colour. See The host client at the end of this page for client-only features (--name, -c, history, and themes).

help

List all available commands.

fantasi> help
  batt        show battery level
  ble         BLE status [list|on|off]
  cat         print file contents
  cd          change directory
  cdc         return USB to serial (CDC) mode
  connect     connect to a BLE peer
  crc32       CRC32 of a device file
  device      print device identifier
  df          show free flash bytes
  dfu         reboot into bootloader/DFU
  disconnect  disconnect BLE peer(s)
  echo        print arguments back
  edit        edit a device file in default editor
  exit        exit the CLI
  free        report heap and SRAM free bytes
  help        list commands
  kill        stop a pid or the running app
  launch      load and run an app (.elf) or Berry script (.be)
  log         stream or write log messages
  ls          list files
  memtest     write/read-back test free SRAM
  mkdir       create a directory
  msc         enter USB mass storage mode
  pair        pair with a BLE device
  ps          list tasks (state, priority, free stack) + heap summary
  pwd         print working directory
  quit        exit the CLI
  radio       show radio stack info
  reboot      restart the device
  reload      refresh client settings from the device
  rfid        launch RFID app
  rm          delete a file
  rmdir       remove empty directory
  scan        scan for BLE devices
  settings    manage saved settings
  shortcut    list/set/run app shortcuts (slots 0-7)
  shutdown    power the device off
  unpair      remove BLE bond(s)
  upload      copy host file to device
  uptime      show time since boot
  version     show firmware version
  webusb      switch USB to WebUSB (protobuf) mode
  whoami      show unique device name

Device & system info

device

Print the device identifier - a short string for the hardware platform.

fantasi> device
FZ

version

Show the firmware version (CalVer yy.mm.pp), codename, git hash, and device.

fantasi> version
fantasi 26.8.0 "Basilia" (git 9fb22f6, device fz)

whoami

Print the unique device name derived from the MCU's serial number (the web launcher uses it to tell devices apart).

uptime

Time since boot.

fantasi> uptime
1h 23m 4.567s

batt

Battery level as a percentage. Errors on devices without a gauge (Proxmark3).

fantasi> batt
Battery level: 73%

• Flipper Zero: BQ27220 fuel gauge over I2C
• Chameleon Ultra: SAADC voltage sense
• Proxmark3: no battery

free

Report the FreeRTOS heap (with the minimum-ever high-water mark) and each SRAM region.

fantasi> free
heap: 48212/61440 B free (min-ever: 41088)
SRAM1  ...... B total, ...... B free
app: ...... B free

df

Free internal-flash bytes available for LittleFS storage.

fantasi> df
flash free: 131072 bytes

ps

List FreeRTOS tasks - state, priority, and free stack - followed by a task count and heap summary.

memtest

Non-destructive write / read-back test of free SRAM.

settings

Manage saved settings (persisted in LittleFS, so they survive reboots). Bare settings lists everything; the sub-verbs read and write individual keys.

fantasi> settings
ble=1
fantasi> settings get theme
theme: not set
fantasi> settings set theme cyberpunk
theme=cyberpunk
fantasi> settings unset theme
unset theme

The theme key selects the host client's colour theme; see Themes. The host reads it at startup, so run reload after changing it from the same session.

Radio & BLE

radio

Show radio-coprocessor info. On the Flipper Zero: secure-flash size, FUS version, the installed wireless-stack version/type (if any), and whether BLE is active. Errors on devices without a radio (Proxmark3).

fantasi> radio
secure flash: 512 KB @ 0x08080000
FUS:   1.2.0
stack: 1.20.0 (type 0x01)
BLE:   on

See Radio Stack for installing the BLE stack.

ble

Show BLE status. ble on / ble off enable or disable the radio; ble list lists active connections.

scan

Passive BLE scan for 5 seconds, printing each device's address, RSSI, and name (if advertised). Flipper Zero and Chameleon Ultra only; errors on the Proxmark3.

fantasi> scan
scanning for 5 s...
AA:BB:CC:DD:EE:FF  -42 dBm  "SomeDevice"
11:22:33:44:55:66  -67 dBm
scan complete: 2 devices

connect / disconnect

Connect to, or disconnect from, a BLE peer.

pair / unpair

Create or remove a BLE bond. Bonds persist across reboots (see settings).

Apps

launch

Load and run an application from /ramfs or an /apps path. Accepts a compiled app (.elf) or a Berry script (.be).

fantasi> launch /apps/hello

kill

Stop a running task by pid, or the current app with a bare kill.

fantasi> kill
kill: stopping app (pid 22)

shortcut

List, set, or run app shortcuts bound to slots 0-7 - a quick way to launch a frequently used app without typing its full path.

rfid

Launch the on-device RFID app and enter its interactive rfid> sub-prompt. Requires the protobuf transport (--usb or --ble). This is the entry point to Fantasi's whole RFID subsystem - reading, writing, sniffing, and emulating LF and HF tags across every device. See the RFID page for the full command set.

fantasi> rfid
rfid> list
rfid> exit

log

Stream log messages to the terminal, or write a log line.

Files

Fantasi keeps a working directory, so the file commands take relative or absolute paths.

ls / cd / pwd

List a directory, change the working directory, and print it.

cat

Print a device file's contents.

mkdir / rm / rmdir

Create a directory, delete a file, and remove an empty directory.

crc32

Print the CRC32 of a device file - handy for verifying an upload landed intact.

upload

Copy a file from the host into device storage.

fantasi> upload hello.arm7.elf /ramfs/hello

edit

Open a device file in your $EDITOR (falling back to nano, vim, or vi). On a mass-storage device the file is edited in place; over WebUSB or BLE the client downloads it to a temporary file, opens the editor, and uploads it back when you save.

fantasi> edit /apps/config.be

USB mode

msc

Enter USB mass-storage mode to expose the LittleFS volume as a block device (512-byte sectors). On the Proxmark3 this re-enumerates the device (CDC and MSC can't run at once - only 4 endpoints); on the Flipper Zero / Chameleon Ultra MSC runs concurrently with CDC. Host-side eject returns the Proxmark3 to CDC.

cdc

Return USB to serial (CDC) mode.

webusb

Switch USB to WebUSB (protobuf) mode - the vendor pipe the web launcher and flasher use to talk to the device from the browser.

Control

echo

Print arguments back - handy for testing the serial link.

fantasi> echo hello world
hello world

reboot

Warm-reset the MCU.

Proxmark3 note: If the serial link becomes unresponsive after a reboot, unplug and replug.

shutdown

Power the device off. Drains the serial output, then cuts power.

fantasi> shutdown

Not supported on the Proxmark3 (no software power control) - it reports shutdown not supported on this platform.

dfu

Reboot into the device's bootloader / DFU mode for firmware flashing. See Flashing.

fantasi> dfu

reload

Ask the host client to re-read its settings from the device (for example after a settings set theme ...), so a change takes effect without restarting the client.

The host client

fantasi is also the program you run on your computer to talk to a device. It picks a transport and either drops you into an interactive prompt or runs a single command.

usage: fantasi [--ble[=ADDR]] [--usb|--serial] [--name NAME] [-c <command>] [/dev/ttyACMx] [/dev/sdX]

• --usb uses the WebUSB (protobuf) pipe; --serial uses the plain CDC serial line; --ble[=ADDR] connects over Bluetooth. The RFID app needs a protobuf transport (--usb or --ble).

Selecting a device by name (--name)

With several devices plugged in, --name NAME picks the one whose name (see whoami) matches - it compares against each device's USB serial and works over USB and BLE.

fantasi --usb --name Sur1d0r

One-shot commands (-c)

-c "<command>" runs a single command and exits, saving nothing to history. Ideal for scripting:

fantasi --usb -c "version"
fantasi --usb -c "rfid read mfc"

Command history

The interactive client keeps a persistent history in ~/.fantasi/fantasi.log, so the up/down arrows recall commands from previous sessions. The rfid> sub-prompt keeps its own history file. One-shot (-c) runs are never recorded.

Themes

The client renders its output through a role-based colour theme, chosen from the device's saved theme setting at startup (see settings). The default is synthwave (Fantasi cyan / hot-pink). Set another with:

fantasi> settings set theme cyberpunk
fantasi> reload

Built-in presets:

Colour is disabled automatically when NO_COLOR is set or output is not a TTY, and settings set theme none turns it off explicitly.