CLI 参考

gpuctl 是 GPUPlane 的控制台入口，命令与 REST API 一一对应。除 server、agent、backup-agent、event-hook 外，其余命令都是 Server 的客户端。

连接 Server

CLI 按以下优先级解析 Server 地址和 token：

命令行选项：--server、--token
环境变量：GPUCTL_SERVER、GPUCTL_TOKEN
配置文件：~/.gpuctl/cli.yaml
同机回退：读取 ~/.gpuctl/server.yaml 中第一个 scope=write 的 token
默认地址：http://127.0.0.1:8600

server: http://192.168.1.10:8600
token: gpt_xxxxxxxxxxxxxxxxxxxxxxxx

守护进程与备份

命令	用途	关键选项
`gpuctl server`	前台启动 Server	无
`gpuctl agent`	前台启动 Agent	无
`gpuctl backup`	Server 在线 SQLite 备份	无
`gpuctl backup-agent`	Agent 本地打包 job 日志与 spool	`--config`, `--output`

gpuctl server
gpuctl agent
gpuctl backup
gpuctl backup-agent --output /mnt/backup/agent-20260825.tar.gz

总览与节点

`gpuctl status`

Server 健康、节点在线状态、各状态 job 数量。

gpuctl status

`gpuctl node list`

列出所有节点及 GPU、CPU、内存、最后心跳。

gpuctl node list

`gpuctl node show <node_id>`

打印节点完整 JSON，含 slots 与硬件信息。

gpuctl node show 01J9...

任务（job）

`gpuctl job submit`

提交一个 job。命令放在 -- 之后，或用 --script 简写。

选项	默认	说明
`--name, -n`	脚本/命令名	job 名称
`--dir, -d`	`.`	工作目录（Agent 主机路径）
`--gpu, -g`	`1`	GPU 数量
`--cpu-only`	`False`	仅 CPU
`--priority, -p`	`100`	数字越小越优先
`--env, -e`	无	可多次，格式 `KEY=VAL`
`--project`	`default`	所属 project
`--experiment`	`''`	所属 experiment
`--node`	`''`	固定节点名称
`--max-attempts`	`1`	最大重试次数
`--watch`	无	checkpoint 监听目录，可多次
`--tb-dir`	`''`	TensorBoard event 目录
`--script, -s`	无	Python 脚本简写

gpuctl job submit -n mnist -g 1 --project cv --experiment mnist-v1 -- python train.py --epochs 5
gpuctl job submit -n mnist --script train.py --epochs 5

`gpuctl job list`

选项	默认	说明
`--status, -s`	`''`	状态过滤
`--limit`	`50`	返回条数上限

gpuctl job list -s RUNNING --limit 10

`gpuctl job show <job_id>`

打印 job 完整 JSON。

gpuctl job show 01J9...

`gpuctl job cancel <job_id>`

请求取消 job。取消是危险操作，CLI 不二次确认。

gpuctl job cancel 01J9...

`gpuctl job retry <job_id>`

将 terminal / LOST job 重新置为 QUEUED。OOM/NaN 失败后请先修复配置再重试。

gpuctl job retry 01J9...

日志

`gpuctl logs <job_id>`

选项	默认	说明
`--stream`	`combined`	`combined` / `stdout` / `stderr`
`--tail, -n`	`200`	最近行数
`--follow, -f`	`False`	SSE 持续跟随

gpuctl logs 01J9... -f --stream stderr

Server 只存日志 tail，完整日志在 Agent 主机的 jobs_dir。

运行（run）与指标

`gpuctl run list`

选项	默认	说明
`--experiment`	`''`	按 experiment 过滤
`--limit`	`50`	返回条数上限

gpuctl run list --experiment mnist-v1

`gpuctl run show <run_id>`

打印 run 详情及其 summary。

gpuctl run show 01J9...

`gpuctl metrics <run_id>`

查看 run 的指标序列最近若干点。

选项	默认	说明
`--names`	`''`	逗号分隔，如 `train/loss,eval/loss`
`--window-s`	`0`	只返回最近 N 秒
`--tail, -n`	`5`	每个 series 展示最近 N 个点

gpuctl metrics 01J9... --names train/loss,eval/loss --tail 10

Checkpoint

`gpuctl checkpoints <run_id>`

列出 run 下的所有 checkpoint。

gpuctl checkpoints 01J9...

导入

`gpuctl import-run <path>`

将已有训练输出目录导入为 IMPORTED run，自动识别 TB events、config、argv、log 和 checkpoint。

选项	默认	说明
`--name, -n`	目录名	run 名称
`--project`	`default`	所属 project
`--experiment`	`''`	所属 experiment
`--tb-dir`	`''`	强制指定 TB event 目录
`--force-new`	`False`	即使已导入也新建 run

gpuctl import-run ./outputs/mnist-v1 --project cv --experiment mnist-v1

事件钩子

`gpuctl event-hook <cmd...>`

订阅 Server 事件流，每来一个事件就本地执行一次命令。事件 JSON 通过 stdin 传入，并通过 GPUCTL_EVENT_* 环境变量暴露。

选项	默认	说明
`--severity, -s`	`''`	只转发指定 severity 的事件

gpuctl event-hook --severity CRITICAL -- /usr/local/bin/wake-me.sh

暴露的环境变量：

GPUCTL_EVENT_TYPE
GPUCTL_EVENT_SEVERITY
GPUCTL_EVENT_MESSAGE
GPUCTL_EVENT_RUN_ID
GPUCTL_EVENT_JOB_ID
GPUCTL_EVENT_NODE_ID
GPUCTL_EVENT_JSON

CLI 参考

连接 Server

守护进程与备份

总览与节点

gpuctl status

gpuctl node list

gpuctl node show <node_id>

任务（job）

gpuctl job submit

gpuctl job list

gpuctl job show <job_id>

gpuctl job cancel <job_id>

gpuctl job retry <job_id>

日志

gpuctl logs <job_id>