nfctl

nf-server CLI — 面向生信工程师和 AI Agent 的命令行工具。

nfctl 2.x 对应 nf-server 4.x；旧版 server/client 的 API 与 pipeline 归档配置契约不兼容。

安装

pip install nfctl

配置

# 设置服务地址（未配置时命令报 CONFIG_ERROR 并给出提示）
nfctl config set url http://nf-server:8000

# 或通过环境变量直连（解析优先级：--profile/NFCTL_PROFILE > NFCTL_URL > 当前 profile）
export NFCTL_URL=http://nf-server:8000

# 多环境用 profile 管理
nfctl config set url http://test-server:8000 --profile test
nfctl config use test        # 切换当前 profile
nfctl --profile prod list    # 单条命令临时指定

命令

查询

nfctl overview                           # 系统概览
nfctl list [--status running] [-n 20]    # 分析列表
nfctl list --all                         # 获取全部分析（自动翻页）
nfctl list --sort created_at --sort-order asc  # 按创建时间升序
nfctl list --pp failed                   # 按归档/后处理轴过滤（与 --status 正交）
nfctl list --pipeline WGS --env prod     # 按 Pipeline / 环境过滤
nfctl list --project-sn P2026001         # 按 LIMS 项目编号过滤
nfctl list --data-number D001            # 按数据编号过滤
nfctl list --query sample1               # 按 workflow_id / launch_dir / data_number 搜索
nfctl status <id>                        # 分析详情
nfctl progress <id>                      # 进度（含 process 级别明细）
nfctl tasks <id> [--status failed]       # 子任务列表
nfctl tasks <id> --sort duration --sort-order desc  # 按耗时排序
nfctl task <id> <task_id>                # 子任务详情
nfctl log <id> [--grep ERROR]            # 日志查看
nfctl resources <id>                     # 资源统计

管理

nfctl submit <dir> -p <name> -S P2026001                 # 提交分析（--project-sn 必填）
nfctl submit <dir> -p <name> -S P2026001 --env prod      # 指定环境（test/gray/prod）
nfctl submit <dir> -p <name> -S P2026001 --dry-run       # 仅验证，不实际投递
nfctl resume <id>                                        # 重跑失败/取消的分析
nfctl cancel <id> [--reason "原因"]                      # 取消整个分析（running/succeeded 均可，会通知 LIMS 作废）
nfctl delete <id>                                        # 删除分析（succeeded 不可删）

归档 / 后处理

nfctl archive status <id>                # 归档信息（产物位置/倒计时）+ 最近一次解压任务状态
nfctl archive start <id>                 # 立即启动归档（支持 skipped/等待归档；只归档、不迁移）
nfctl archive now <id>                   # start 的 deprecated 兼容别名
nfctl archive resume <id>                # 恢复失败/取消的归档或后处理（分析须已成功）
nfctl archive restore <id> [--wait]      # 解压归档产物回 launch_dir 原位（大归档可达小时级）
nfctl archive cancel <id>                # 仅取消后处理/归档，保留分析结果

其他

nfctl pipeline list/get/create/update/delete   # Pipeline 配置（并发/归档策略/飞书通知/超时覆盖）
nfctl config show/set/use/list/remove          # 配置与多 profile 管理
nfctl -v <命令>                                # 调试：stderr 显示 HTTP 请求/状态/耗时

启用 pipeline 归档后，范围固定为 launch_dir 下所有一级非隐藏真实目录；不能按 pipeline 选择目录。大文件迁移与归档使用同一范围。

手动 submit 场景

LIMS 本身就是通过 nfctl submit 通道向 nf-server 投递 nextflow 任务的。日常分析任务由 LIMS 自动触发,无需手动操作。以下两种情况需要手动 submit:

1. LIMS 未正常触发投递:作为应急补投手段。
2. 本地独立流程:不需要同步到 LIMS2 云平台的分析任务。

只有走过 submit 通道的任务(LIMS 自动触发或手动补投均可),nf-server 才会记录这个任务,才能监控状态、查日志、续跑。

用法

# 场景 1:LIMS 应急补投(同步到云平台)
nfctl submit /path/to/launch_dir -p WGS -S P2026001 -e prod

# 场景 2:本地独立流程(不同步云平台)
nfctl submit /path/to/launch_dir -p WGS -S P2026001

resume 与 qsub 的衔接

• ✅ 走过 submit → 失败后可 nfctl resume <workflow_id> 续跑;手动 qsub run.sh 接管也能被识别为同一任务。
• ❌ 没走过 submit、直接 qsub → nf-server 无记录,无法 resume,也无法监控,且没有补救路径。

AI Agent 使用

所有命令支持 --format json，输出标准信封格式：

nfctl -f json list
# {"ok": true, "data": {"total": 5, "items": [...]}}

使用 --jq 过滤 JSON 输出：

nfctl --jq '.data.items[].workflow_id' list
nfctl --jq '.data.items[] | select(.status=="failed")' list

安装 Agent Skills：

npx skills add huangzhibo/nfctl

开发

uv sync
uv run nfctl --help
uv run pytest

提交前自动跑 ruff（首次 clone 后执行一次）：

uv tool install pre-commit   # 或 brew install pre-commit / pipx install pre-commit
pre-commit install