loopal

Loopal 对外命令行工具。当前版本支持技能市场、天气、音频、图片、视频与音乐生成，以及使用用户默认 API Key 上传 24 小时有效的临时文件。

安装

npm install --global loopal-cli

也可以直接使用：

npx --package loopal-cli loopal skill search "网页设计"

技能命令

# 搜索市场，可使用 --json 获取结构化结果
loopal skill search "网页设计"
loopal skill search --category front-end-design --tag design --json

# 查看详情
loopal skill info emilkowalski-design

# 下载原始 ZIP
loopal skill download emilkowalski-design --dir ./downloads

# 需要自定义文件名时，指定完整输出路径
loopal skill download emilkowalski-design --output ./downloads/design.zip

# 安装到技能根目录，实际目录为 <dir>/<slug>
loopal skill install emilkowalski-design --dir ~/.codex/skills

目标目录存在时默认拒绝覆盖；显式添加 --force 才会原子替换旧目录。

登录与临时文件

先在 Loopal 账号中心的“系统设置”中显示并复制默认 API Key，然后执行：

loopal login
loopal whoami
loopal upload ./report.pdf

login 会安全地读取并验证 API Key，再保存到 ~/.loopal/credentials.json。文件权限为 0600，不会写入项目配置。CI 或无交互环境可以直接设置：

export LOOPAL_API_KEY=sk-cc_xxx
loopal upload ./report.pdf --json

模型命令还支持 LOOPAL_MODEL_TOKEN，其优先级高于 LOOPAL_API_KEY。Loopal Agent 沙箱使用按会话挂载的 Unix Socket Broker，内部令牌不会写入 CLI 环境变量； login、whoami 等平台命令不会使用 Broker 或读取 LOOPAL_MODEL_TOKEN。

临时文件的公开 URL 有效期为 24 小时，可用于后续模型请求。loopal logout 只删除本机凭证，不会禁用平台上的默认 API Key。

音色查询

按模型和标签查询可用于音频生成的音色 ID：

loopal voice-styles minimax --language English --gender Female
loopal voice-styles doubao --language Chinese --scene "General Use"
loopal voice-styles doubao --list-filters

命令默认输出 JSON，详细参数见 docs/commands/voice-styles.md。

语音识别

查询 ASR 模型并识别本地音频：

loopal audio models --task transcribe --json
loopal audio transcribe \
  --model doubao/auc-bigmodel \
  --file packages/loopal-cli/tmp/audio.mp3 \
  --json

图片生成与编辑

loopal image models --json
loopal image generate \
  --model doubao/seedream-5-lite \
  --name "雨夜书店" \
  --prompt "电影感的雨夜街角书店，暖色灯光" \
  --json

GPT Image 2 还支持 loopal image edit。每个模型的完整参数通过 --model <模型> --help 查看，统一入口见 docs/commands/image.md。

视频生成与编辑

loopal video models --json
loopal video generate \
  --model doubao/seedance-2.0 \
  --name "产品镜头" \
  --prompt "镜头缓慢推进，产品表面出现柔和高光" \
  --json

Seedance 支持首尾帧和多模态参考，HappyHorse 提供文生视频、图生视频、参考图生视频和视频编辑模型。完整入口见 docs/commands/video.md。

音乐生成与处理

loopal music models --json
loopal music generate \
  --model mureka/mureka-9 \
  --name "夏日海边" \
  --lyrics-file ./lyrics.txt \
  --prompt "清新流行摇滚，女声，明亮吉他和轻快鼓组" \
  --json

音乐命令还支持歌词生成、续写、局部编辑、识别、描述、纯音乐和图片/视频配乐。完整入口见 docs/commands/music.md。

天气命令

天气查询基于 wttr.in，不需要 API Key：

loopal weather Beijing
loopal weather Shanghai --mode week
loopal weather Tokyo --mode json --json

服务地址

SkillHub、登录和音色查询默认使用 https://loopal.app；上传、生成和识别默认使用 https://model.loopal.app。CLI 不提供 --base-url 参数，内部按环境变量、~/.loopal/config.json、默认地址的顺序读取配置。

完整配置格式见 docs/configuration.md。

命令文档

每个命令的参数、普通输出、JSON 输出、退出码和文件行为请参阅 COMMANDS.md。

源码分层、测试约束和新增命令规范请参阅 ARCHITECTURE.md。

发布与更新

# 只检查，不会上传
pnpm --dir packages/loopal-cli release:check

# 正式发布
pnpm --dir packages/loopal-cli release

版本升级、首次登录和异常处理请参阅 RELEASING.md。