Command Line

CLI：给人，也给机器

lofibox CLI 分为两层：direct/durable 命令操作配置、凭据引用、媒体库、cache 等持久对象； runtime 命令连接正在运行的 LoFiBox 实例，读取播放状态或提交播放控制。默认输出给人看， --json、--porcelain、--fields 给脚本和 Agent 使用。

稳定退出码

Agent-friendly discovery

自主 Agent 不应该靠猜 help 文本。推荐入口是机器可读命令发现、字段 schema、结构化错误和嵌套字段过滤。

lofibox commands --json
lofibox help --json
lofibox help runtime playback --json
lofibox runtime playback --schema
lofibox runtime playback --fields status,title,artist,elapsed,duration --json
lofibox now --fields playback.status,playback.title,queue.active_index --json

播放与 runtime 状态

播放命令操作的是 playback session。查询命令可只取必要字段，避免拉回巨大 queue。

lofibox now
lofibox now --json
lofibox runtime playback --json
lofibox play "/home/vicliu/Music/Outkast - Hey Ya!.mp3"
lofibox play --pause
lofibox play --toggle
lofibox play --next
lofibox play --seek +10s
lofibox play --repeat off
lofibox play --shuffle on

队列

queue 是独立能力域。它支持“排队但不立即播放”，也支持查看、移除、移动、设置当前项和保存/加载命名队列。

lofibox queue show
lofibox queue add "/home/vicliu/Music/track.flac"
lofibox queue add --id 42
lofibox queue remove 3
lofibox queue move 5 2
lofibox queue set 1
lofibox queue clear
lofibox queue save evening
lofibox queue load evening

本地媒体库与搜索

library 命令操作本地索引；search 是跨本地和远程源的统一搜索入口。不要把二者混成一个巨大命令。

lofibox library scan --root ~/Music --incremental
lofibox library status --json
lofibox library list tracks
lofibox library list albums
lofibox library query tracks --artist "Outkast"
lofibox library query tracks --recently-added
lofibox search "hey ya"
lofibox search "utada" --local
lofibox search "radiohead" --source jellyfin-home

source 与 remote

source 负责配置、认证、能力、生命周期； remote 负责连接后的目录浏览、搜索、最近项目、收藏、stream resolve。

lofibox source list --json
lofibox source add jellyfin --id home --name "Home Jellyfin" \
  --base-url https://media.local:8096 \
  --username vicliu \
  --credential-ref jellyfin-home
lofibox source probe home
lofibox source capabilities home
lofibox remote browse home /albums
lofibox remote search home "radiohead"
lofibox remote resolve home item-123
lofibox remote stream-info home item-123

凭据

凭据和 profile 分开存储。默认不要把 password/token 放在命令行参数里，推荐 stdin 形式。

lofibox credentials list
lofibox credentials show-ref jellyfin-home
lofibox credentials set jellyfin-home --username vicliu
printf '%s' "$JELLYFIN_PASSWORD" | lofibox credentials set jellyfin-home --password-stdin
printf '%s' "$NAVIDROME_TOKEN" | lofibox credentials set navidrome-home --token-stdin
lofibox credentials validate jellyfin-home
lofibox credentials delete old-ref

EQ / DSP

lofibox eq show
lofibox remix
lofibox remix --json
lofibox eq enable
lofibox eq preset list
lofibox eq preset apply "Bass Boost"
lofibox eq band 31 +3
lofibox eq preamp -4.5
lofibox eq replaygain track
lofibox eq limiter on
lofibox eq loudness on
lofibox eq balance -10
lofibox eq bind device default "Podcast / Speech"

metadata / lyrics / artwork / fingerprint

补 ID3、补歌词、补封面和生成指纹都拆成 lookup、diff、apply、writeback。 这样可以先看候选和差异，再决定是否接受和写回，避免自动流程破坏用户音乐文件。

lofibox metadata lookup "/music/track.mp3"
lofibox metadata diff "/music/track.mp3"
lofibox metadata apply "/music/track.mp3"
lofibox metadata writeback "/music/track.mp3"
lofibox lyrics lookup "/music/track.mp3"
lofibox lyrics apply "/music/track.mp3"
lofibox lyrics writeback "/music/track.mp3"
lofibox artwork lookup "/music/track.mp3"
lofibox fingerprint generate "/music/track.mp3"
lofibox fingerprint match "/music/track.mp3"

cache / persistence / diagnostics

lofibox cache status
lofibox cache list
lofibox cache purge artwork
lofibox cache gc
lofibox persistence status
lofibox persistence save
lofibox persistence repair
lofibox paths --json
lofibox doctor --json