Flipper Zero命令行管理工具faf-cli：原理、安装与自动化实战

1. 项目概述：一个为Flipper Zero设计的命令行伴侣

如果你手头有一台Flipper Zero，并且已经厌倦了在图形界面和文件管理器之间来回切换，只为上传一个BadUSB脚本或者管理一下Sub-GHz的捕获文件，那么你很可能需要faf-cli。这个项目，全称是“Flipper Application Framework CLI”，直译过来就是“Flipper应用框架命令行工具”。它不是什么官方出品的重量级软件，而是一个由社区开发者Wolfe-Jam用Python编写的轻量级命令行工具，目标只有一个：让你能像操作本地文件夹一样，通过命令行来管理你的Flipper Zero设备。

简单来说，faf-cli在电脑和Flipper Zero之间架起了一座高效的桥梁。它通过USB连接，将Flipper Zero的SD卡文件系统映射到你的终端里。这意味着，你可以用熟悉的ls、cp、rm、mkdir等命令，直接操作Flipper设备里的/ext/apps、/ext/subghz、/ext/infrared等目录。对于喜欢自动化、习惯命令行工作流，或者需要批量处理大量脚本文件的极客和开发者来说，这无疑是一个效率倍增器。它尤其适合那些深度定制Flipper Zero，频繁测试不同Payload，或者需要将设备管理集成到更复杂自动化脚本中的用户。

2. 核心设计思路与工作原理拆解

2.1 为什么需要命令行工具？图形化界面的瓶颈

Flipper Zero自带的QFlipper工具提供了基础的图形化文件管理功能，对于大多数简单操作来说是足够的。然而，当你进入以下场景时，图形界面的局限性就暴露无遗：

1. 批量操作：你需要一次性上传几十个BadUSB脚本到不同的文件夹。在QFlipper里，你只能一个个拖拽，或者全选后上传，但无法进行条件筛选（比如只上传.txt文件）或复杂的目录结构创建。
2. 自动化集成：你编写了一个自动化脚本，用于从Git仓库拉取最新的Sub-GHz频率库，经过格式校验后，自动部署到Flipper Zero上。这个过程如果依赖图形界面，就完全无法自动化。
3. 远程与无头操作：在服务器环境或通过SSH连接的远程电脑上操作Flipper Zero，图形界面根本无法使用。
4. 效率与精准度：对于熟练的命令行用户，cp -r ./new_apps/* /mnt/flipper/apps/这样一条命令，其速度和精准度远高于鼠标点击。

faf-cli正是为了解决这些痛点而生。它的设计哲学是“Unix哲学”的体现：做好一件事，并通过管道和脚本与其他工具协同工作。

2.2 底层通信机制：并非直接文件系统挂载

一个常见的误解是，faf-cli像adb（Android Debug Bridge）或MTP（媒体传输协议）那样，在系统层面挂载了一个新的驱动器。实际上，它的工作原理更接近于一个智能的“文件同步客户端”或“远程过程调用（RPC）工具”。

Flipper Zero在通过USB连接到电脑时，会暴露一个串行通信接口（通常是/dev/ttyACM0或COMx）。官方固件内置了一个简单的文件管理协议（有时被称为“Flipper CLI Protocol”或“RPC”）。faf-cli的核心就是与这个协议进行对话。

它的工作流程可以分解为：

1. 发现与连接：工具扫描可用的串行端口，尝试与运行着支持该协议的固件的Flipper Zero建立连接。
2. 协议封装：当你执行faf ls /ext时，faf-cli并不会直接读取文件列表，而是将这个ls命令（及其参数）翻译成Flipper设备能够理解的二进制RPC指令。
3. 指令执行与回传：指令通过USB串口发送给Flipper Zero。Flipper Zero内部的固件接收到指令后，在其本地的SD卡文件系统上执行相应的操作（如列出目录），然后将结果（文件列表的文本或数据）通过同样的串口回传给电脑。
4. 结果呈现：faf-cli接收并解析回传的数据，格式化成人类可读的形式（如列表、树状图）显示在终端上。

对于文件传输（put/get），过程类似，但涉及数据分块传输和校验，以确保大文件传输的可靠性。

注意：这意味着faf-cli的功能深度完全依赖于Flipper Zero固件所暴露的RPC接口。如果官方固件更新，移除了某个文件操作接口，那么faf-cli的对应功能也会失效。因此，工具与固件版本的兼容性是需要关注的一点。

2.3 工具选型与生态定位

为什么选择Python来开发？对于这类工具，Python几乎是首选。因为它拥有极其丰富和成熟的串口通信库（如pyserial），跨平台支持完美（Windows/macOS/Linux），并且编写CLI工具非常快捷（借助argparse或click库）。这使得开发者能快速迭代，社区用户也能轻松通过pip安装。

在Flipper Zero的生态中，faf-cli填补了一个细分但重要的空白。它不像qFlipper那样提供全面的设备管理（如固件更新），也不像FlipperScripts仓库那样提供现成的攻击载荷。它专注于“文件操作”这一单一领域，并将其做到极致，成为连接其他生态工具（如本地脚本仓库、CI/CD流水线）的理想胶水。

3. 从零开始：安装、配置与基础命令实战

3.1 环境准备与安装指南

安装faf-cli的前提是你的电脑上已经安装了Python（建议3.7或更高版本）和pip包管理器。

对于macOS/Linux用户：打开终端，使用pip直接安装是最简单的方式。建议使用pipx，它能将Python应用安装到独立的环境中，避免污染系统Python包。

# 安装pipx（如果尚未安装） python3 -m pip install --user pipx python3 -m pipx ensurepath # 重新打开终端或执行 source ~/.bashrc (或 ~/.zshrc) # 使用pipx安装faf-cli pipx install faf-cli

如果不用pipx，也可以直接用pip安装到用户目录：

pip3 install --user faf-cli

安装后，确保~/.local/bin（Linux/macOS）目录在你的PATH环境变量中。

对于Windows用户：确保已安装Python并从官网添加到了PATH。然后以管理员身份打开PowerShell或CMD：

pip install faf-cli

安装完成后，你可能需要重启终端，或者手动将Python的Scripts目录（例如C:\Users\你的用户名\AppData\Local\Programs\Python\Python39\Scripts）添加到系统的PATH变量中，才能直接在命令行使用faf命令。

验证安装是否成功：

faf --version

如果显示出版本号（如faf-cli 0.4.0），说明安装成功。

3.2 首次连接与设备发现

在连接Flipper Zero之前，请确保：

1. 设备已开机。
2. 使用原装或质量可靠的USB数据线连接到电脑。
3. Flipper Zero上运行的固件版本比较新（最好是官方最新稳定版或支持RPC的社区固件），以保障CLI协议兼容性。

连接后，最基本的命令是列出可用的Flipper设备：

faf list

这个命令会扫描所有可用的串行端口，并尝试与Flipper Zero通信。如果成功，你会看到类似下面的输出：

Found 1 Flipper device: /dev/ttyACM0 - Flipper Zero s/n: 123-456-789 (Firmware: 0.80.1)

这里显示了设备路径、序列号和固件版本。记下设备路径（如/dev/ttyACM0或COM3），在有多台设备或端口冲突时可能需要指定它。

如果faf list没有找到设备，可以尝试：

• 重新插拔USB线。
• 在Flipper Zero上检查USB连接模式是否为“默认”（Serial）。
• 使用faf -p /dev/你的端口 list手动指定端口尝试。

3.3 核心文件操作命令详解

一旦连接成功，你就可以像操作本地文件一样使用以下命令。faf-cli的命令设计很大程度上模仿了标准的Unix命令，学习成本很低。

1. 导航与查看 (ls, tree, pwd)

• faf ls [路径]: 列出目录内容。不加路径则列出根目录。常用选项-l显示详情（权限、大小、时间），-a显示隐藏文件。

  faf ls /ext faf ls -la /ext/apps_data

• faf tree [路径]: 以树状图显示目录结构，非常直观。

  faf tree /ext/subghz

• faf pwd: 打印Flipper设备上的当前工作目录（注意，这是设备端的“当前目录”概念，与你的电脑终端当前目录无关）。

2. 文件传输 (put, get)这是最常用的功能。

• faf put <本地文件> <设备远程路径>: 将本地文件上传到Flipper Zero。

  # 上传单个文件到指定目录 faf put ./dolphin/manifest.txt /ext/dolphin/ # 上传并重命名 faf put ./badusb/payload.txt /ext/badusb/evil_payload.txt

• faf get <设备远程文件> [本地路径]: 从Flipper Zero下载文件到本地。

  # 下载到当前目录 faf get /ext/subghz/captures/my_capture.sub # 下载并指定本地保存路径和文件名 faf get /ext/infrared/remote.ir ./saved_remotes/living_tv.ir

  实操心得：传输大文件（如数MB的.sub文件）时，可能会稍慢，这是串口速率限制所致。传输过程中请保持设备连接稳定，避免中断。

3. 目录管理 (mkdir, rm, rmdir)

• faf mkdir <路径>: 在设备上创建新目录。

  faf mkdir /ext/apps_data/my_new_app faf mkdir -p /ext/nfc/assets/custom # -p 参数可以创建多级目录

• faf rm <文件路径>: 删除文件。

  faf rm /ext/badusb/old_payload.txt

• faf rmdir <目录路径>: 删除空目录。要删除非空目录，通常需要先递归删除里面所有文件，或者使用一些变通方法。

4. 批量操作与通配符faf-cli支持简单的通配符*，但需要注意，通配符解析是在你的电脑终端完成的，然后faf-cli将匹配到的文件列表逐个发送给设备。这意味着它并非在设备端进行通配符扩展。

# 上传当前目录下所有 .txt 文件到设备的 /ext/badusb 目录 faf put ./*.txt /ext/badusb/ # 下载设备上 /ext/subghz/assets 目录下所有文件 for file in $(faf ls /ext/subghz/assets | grep -v ^d); do faf get "/ext/subghz/assets/$file" ./local_assets/; done

上面的例子中，第二行是一个简单的Bash循环，演示了如何结合Shell脚本实现更复杂的批量下载。faf-cli与Shell的协同能力是其强大之处。

4. 高级用法与自动化脚本集成

4.1 使用配置文件简化连接

如果你经常使用同一台Flipper Zero，每次输入设备端口会很麻烦。faf-cli支持配置文件。默认的配置文件位于~/.config/faf-cli/config.toml（Linux/macOS）或%APPDATA%\faf-cli\config.toml（Windows）。

你可以手动创建并编辑这个文件：

[default] port = "/dev/ttyACM0" # 或 "COM3" # nickname = "MyFlipper" # 可以给设备起个昵称

配置好后，后续的命令如果不指定-p参数，就会自动使用配置文件中定义的端口。

4.2 编写自动化部署脚本

这才是faf-cli真正发挥威力的地方。假设你有一个本地的FlipperScripts仓库，你希望每次更新后，自动将相关的文件同步到Flipper Zero上。

下面是一个简单的Bash脚本示例deploy_to_flipper.sh：

#!/bin/bash # 定义本地仓库路径和设备目标路径 LOCAL_BADUSB_DIR="./BadUSB_Payloads/" LOCAL_SUBGHZ_DIR="./SubGHz_Collection/" FLIPPER_BADUSB_PATH="/ext/badusb/" FLIPPER_SUBGHZ_PATH="/ext/subghz/assets/" # 1. 检查faf-cli和设备连接 echo "检查Flipper Zero连接..." if ! faf list | grep -q "Flipper Zero"; then echo "错误：未检测到Flipper Zero设备。请连接设备并重试。" exit 1 fi # 2. 清空设备上旧的测试文件（谨慎操作！建议先备份） # faf shell "rm -rf ${FLIPPER_BADUSB_PATH}test_*" # 3. 同步BadUSB脚本（只同步.txt文件） echo "开始同步BadUSB脚本..." for file in ${LOCAL_BADUSB_DIR}*.txt; do if [ -f "$file" ]; then filename=$(basename "$file") echo "上传: $filename" faf put "$file" "${FLIPPER_BADUSB_PATH}${filename}" fi done # 4. 同步Sub-GHz文件（.sub和.txt文件） echo "开始同步Sub-GHz文件..." for file in ${LOCAL_SUBGHZ_DIR}*.{sub,txt}; do if [ -f "$file" ]; then filename=$(basename "$file") echo "上传: $filename" faf put "$file" "${FLIPPER_SUBGHZ_PATH}${filename}" fi done echo "部署完成！请在Flipper Zero上查看新文件。"

这个脚本完成了设备检查、批量文件筛选和上传的过程。你可以结合cron（Linux/macOS）或任务计划程序（Windows）将其设置为定时任务，实现自动同步。

4.3 与版本控制系统（Git）结合

你可以将Flipper Zero上的关键配置文件（如/ext/dolphin/manifest.txt，/ext/.bt.keys等）通过faf get下载到本地，纳入Git仓库进行版本管理。当需要恢复或迁移到新设备时，再用faf put推送回去。这为设备配置的备份和团队共享提供了极大便利。

# 备份关键配置到本地git仓库 mkdir -p ~/flipper-backup/$(date +%Y%m%d) faf get /ext/dolphin/manifest.txt ~/flipper-backup/$(date +%Y%m%d)/ faf get /ext/.bt.keys ~/flipper-backup/$(date +%Y%m%d)/ cd ~/flipper-backup && git add . && git commit -m "Backup $(date +%Y%m%d)"

5. 常见问题、故障排查与使用技巧

5.1 连接与通信故障

问题1：执行faf list或任何命令都报错，提示“无法打开端口”或“权限被拒绝”。

• Linux/macOS排查：这通常是用户没有串口设备的读写权限。你可以将用户加入dialout组（Ubuntu/Debian）或uucp组（Arch等），或者使用sudo运行命令（不推荐长期使用）。

  sudo usermod -a -G dialout $USER # 或者临时使用 sudo faf list

  执行usermod后需要注销并重新登录才能生效。
• Windows排查：检查设备管理器中的端口号，确认是否有冲突。尝试以管理员身份运行命令行。

问题2：设备被找到，但执行文件操作时超时或断开。

• 检查数据线：劣质数据线可能仅能供电，无法稳定传输数据。务必使用原装或已知良好的数据线。
• 检查设备状态：确保Flipper Zero没有进入睡眠模式，且屏幕亮起。有些操作在设备锁屏时可能会被挂起。
• 降低传输负载：如果正在传输非常大的文件，尝试将其分割成小块。串口通信速率有限，超大文件容易超时。
• 重启服务：在Flipper Zero上，尝试进入“设置” -> “系统” -> “重启为DFU模式”，然后拔插USB线重新连接。这有时能重置USB通信状态。

5.2 文件操作异常

问题3：使用通配符*上传时，只有部分文件被上传。如前所述，faf-cli的put命令通配符是在客户端展开的。如果文件数量非常多，可能会遇到命令行参数长度限制。解决方案是使用Shell循环，如前面高级用法中所示。

问题4：无法删除非空目录。faf-cli的rmdir命令标准行为是只删除空目录。要删除整个目录树，你需要递归删除所有子项。可以写一个简单的脚本：

# 递归删除设备上的 /ext/temp 目录（谨慎使用！） for item in $(faf ls /ext/temp); do if [[ $(faf ls -l "/ext/temp/$item" | cut -c1) == "d" ]]; then # 如果是目录，暂时无法直接递归，需要更复杂的逻辑或逐层删除 echo "跳过目录 /ext/temp/$item， 需要手动处理" else faf rm "/ext/temp/$item" fi done faf rmdir /ext/temp # 最后删除空目录

更优雅的方式是期待未来faf-cli版本增加rm -r功能，或者直接使用faf shell（如果固件支持）执行设备端的rm -rf命令。

5.3 性能优化与使用技巧

1. 小文件批量传输：对于大量小文件（如一堆BadUSB脚本），先在本机用tar打包，上传到设备的一个临时位置，然后（如果设备支持且你安装了相关工具）通过faf shell调用设备端的tar解压，最后删除临时压缩包。这比逐个文件传输快得多。

   # 本地打包 tar -czf badusb_payloads.tar.gz ./badusb_payloads/ # 上传压缩包 faf put badusb_payloads.tar.gz /ext/tmp/ # 假设设备已安装tar，通过shell解压 (注意：此功能依赖固件) faf shell "cd /ext/tmp && tar -xzf badusb_payloads.tar.gz -C /ext/badusb/ --strip-components=1" # 清理 faf shell "rm /ext/tmp/badusb_payloads.tar.gz" faf rm badusb_payloads.tar.gz

2. 善用-v（verbose）参数：在执行命令时加上-v，可以显示详细的调试信息，包括发送和接收的原始RPC命令，这对于排查复杂问题非常有帮助。

   faf -v put large_file.sub /ext/subghz/

3. 组合命令与脚本：将常用的操作序列封装成Shell函数或别名，放入你的.bashrc或.zshrc中。

   # 在 ~/.bashrc 中添加 alias flipper-backup='faf get /ext/dolphin/manifest.txt ~/flipper-backup/manifest_$(date +%s).txt' function flipper-upload-badusb() { for f in $@; do faf put "$f" /ext/badusb/ done }

4. 注意文件路径中的空格：如果设备上的文件或目录名包含空格，在命令中一定要用引号括起来。

   faf get "/ext/subghz/My Captures/doorbell.sub" ./

faf-cli作为一个社区驱动的工具，其功能和稳定性会随着Flipper Zero固件的更新和开发者Wolfe-Jam的维护而不断进化。遇到问题时，查阅项目的GitHub仓库的Issue页面，通常能找到解决方案或了解到最新的开发动态。将它融入你的Flipper Zero工作流，你会发现命令行带来的那种精准、高效和可编程的操控感，是图形界面难以替代的。