qzcli

사용 방법

설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.

npx skills add https://github.com/wanshuiyin/auto-claude-code-research-in-sleep --skill qzcli

시작 전 확인

설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.

원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

qzcli — 启智平台任务管理

A kubectl/docker-style CLI for managing GPU compute jobs on the Qizhi (启智) platform.

GitHub: tianyilt/qzcli_tool

Environment contract

Qizhi is the scheduler-cluster shape of ../shared-references/compute-env-contract.md: images are built OFF-platform and referenced at submit time, so the declarative env spec + env:<name>@<specHash> ledger (.aris/compute/qizhi.md) is what keeps "which image has which stack" answerable. Run the kernel witness inside a submitted job (not on the login side) before trusting an image for a long run.

Installation

bash

pip install rich requests prompt_toolkit mcp
git clone https://github.com/tianyilt/qzcli_tool
cd qzcli_tool && pip install -e .

MCP Integration (optional)

To use qzcli as an MCP tool directly from Claude Code or Codex:

bash

# Claude Code
claude mcp add qzcli -- qzcli-mcp

# Codex
codex mcp add qzcli -- qzcli-mcp

Configuration

Credentials are read in this priority order: CLI args > --password-stdin > env vars > QZCLI_ENV_FILE (.env) > ~/.qzcli/config.json > interactive input

bash

# Option A: env file (recommended)
mkdir -p ~/.qzcli
cat > ~/.qzcli/.env <<'EOF'
QZCLI_USERNAME="your_username"
QZCLI_PASSWORD="your_password"
EOF

# Option B: environment variables
export QZCLI_USERNAME="your_username"
export QZCLI_PASSWORD="your_password"
export QZCLI_API_URL="https://qz.yourorg.edu.cn"

Config files are stored in ~/.qzcli/: config.json, .cookie, resources.json, jobs.json.

Quick Start

bash

# 1. Login
qzcli login

# 2. Discover and cache workspaces/compute groups (run once, re-run after joining new workspaces)
qzcli res -u

# 3. Check available nodes
qzcli avail

# 4. List running jobs
qzcli ls -c -r

Authentication

bash

# Interactive login
qzcli login

# With credentials
qzcli login -u YOUR_USERNAME -p 'YOUR_PASSWORD'

# Read password from stdin (for scripts)
echo 'YOUR_PASSWORD' | qzcli login -u YOUR_USERNAME --password-stdin

# Check current cookie
qzcli cookie --show

# Clear cookie
qzcli cookie --clear

Note: qzcli avail auto-refreshes the cookie if it expires and credentials are configured.

Resource Discovery

bash

# List cached workspaces
qzcli res --list

# Refresh all workspace resource cache (run this first!)
qzcli res -u

# Refresh a specific workspace
qzcli res -w MY_WORKSPACE -u

# Set a human-readable alias for a workspace
qzcli res -w ws-xxxxxxxx --name "My Workspace"

Check Available Nodes

bash

# All workspaces
qzcli avail

# Including low-priority task nodes (slower but more accurate)
qzcli avail --lp

# Specific workspace
qzcli avail -w MY_WORKSPACE

# Find compute groups with N free nodes
qzcli avail -n 4

# Export IDs for scripting
qzcli avail -n 4 -e

# Show idle node names
qzcli avail -w MY_WORKSPACE -v

Job Submission

Interactive (recommended for first-time use)

bash

# Full interactive selection: workspace → project → compute group → spec
qzcli create -i

# Interactive for a specific workspace only
qzcli create -i -w "My Workspace"

The TUI shows GPU type, availability, and spec status at each level. Press Enter/→ to go deeper, ← to go back.

Non-interactive

bash

# Using names (resolved from qzcli res cache)
qzcli create \
  --name "my-training-job" \
  --command "bash /path/to/train.sh" \
  --workspace "My Workspace" \
  --compute-group "My Compute Group" \
  --image YOUR_REGISTRY/team/image:tag \
  --instances 4 \
  --priority 10

# Using IDs directly
qzcli create \
  --name "my-job" \
  --command "bash /path/to/train.sh" \
  --workspace ws-YOUR_WORKSPACE_ID \
  --compute-group lcg-YOUR_LCG_ID \
  --spec YOUR_SPEC_ID \
  --image YOUR_REGISTRY/team/image:tag \
  --instances 4

Key parameters:

Parameter	Default	Description
`--name` / `-n`	required	Job name
`--command` / `-c`	required	Command to run
`--workspace` / `-w`		Workspace name or ID (`ws-...`)
`--compute-group` / `-g`	auto	Compute group name or ID (`lcg-...`)
`--spec` / `-s`	auto	Resource spec ID
`--image` / `-m`		Docker image
`--instances`	1	Number of instances
`--shm`	1200	Shared memory (GiB)
`--priority`	10	Priority (1–10)
`--dry-run`		Preview only, don't submit
`--json`		JSON output for scripting

bash

# Preview before submitting
qzcli create --name test --command "echo hi" --workspace "My Workspace" \
  --image YOUR_IMAGE --dry-run

Env-var passthrough (for existing submission scripts)

bash

# Pass vars directly — do NOT use "export VAR; bash script.sh"
WORKSPACE_ID="ws-YOUR_WORKSPACE_ID" \
LCG_ID="lcg-YOUR_LCG_ID" \
SPEC_ID="YOUR_SPEC_ID" \
CHECKPOINT_DIR="/path/to/checkpoint" \
bash YOUR_SUBMIT_SCRIPT.sh

HPC / CPU jobs (Slurm)

bash

qzcli hpc \
  --name "my-cpu-job" \
  --workspace ws-YOUR_WORKSPACE_ID \
  --compute-group lcg-YOUR_LCG_ID \
  --predef-quota-id YOUR_QUOTA_ID \
  --cpu 55 --mem-gi 300 --instances 30 \
  --image YOUR_REGISTRY/team/cpu-image:tag \
  --entrypoint "cd /path/to/dir && bash run.sh"

Batch Submission

bash

# Submit from config file
qzcli batch batch_config.json --delay 3

# Preview all jobs
qzcli batch batch_config.json --dry-run

# Continue on error
qzcli batch batch_config.json --continue-on-error

Config format (batch_config.json):

json

{
  "defaults": {
    "workspace": "ws-YOUR_WORKSPACE_ID",
    "compute_group": "lcg-YOUR_LCG_ID",
    "spec": "YOUR_SPEC_ID",
    "image": "YOUR_REGISTRY/team/image:tag",
    "instances": 4,
    "priority": 10
  },
  "matrix": {
    "checkpoint": ["/path/to/ckpt1", "/path/to/ckpt2"],
    "step": [50000, 100000]
  },
  "name_template": "eval-{checkpoint_basename}-step{step}",
  "command_template": "bash eval.sh --checkpoint {checkpoint} --step {step}"
}

Matrix keys are Cartesian-producted (2×2 = 4 jobs above). Use {key_basename} for path basenames.

Shell loop (alternative)

bash

for step in 040000 050000 060000; do
  qzcli create \
    --name "eval-step${step}" \
    --command "bash eval.sh --step $step" \
    --workspace "My Workspace" \
    --compute-group "My Compute Group" \
    --instances 4
  sleep 3
done

Job Management

bash

# List jobs
qzcli ls -c -w MY_WORKSPACE          # specific workspace
qzcli ls -c --all-ws                 # all workspaces
qzcli ls -c -w MY_WORKSPACE -r       # running only
qzcli ls -c -w MY_WORKSPACE -n 50    # show 50

# Stop a job
qzcli stop JOB_ID

# Job status / details
qzcli status JOB_ID

# Watch all running jobs (refresh every 10s)
qzcli watch -i 10

# Workspace view with GPU utilization
qzcli ws
qzcli ws -a           # all projects
qzcli ws -p "My Project"

Troubleshooting

Problem	Cause	Fix
Cookie expired	Session gap	Re-run `qzcli login`
`未找到名称为 'xxx' 的工作空间`	Stale cache	Run `qzcli res -u`
No resources in `create -i`	Cache empty	Run `qzcli login && qzcli res -u`
`qzcli-mcp` not found	Not installed	`cd qzcli_tool && pip install -e .`
Spec not in workspace	ID mismatch	Match spec ID to the correct workspace
Silent job failure	Script `sys.exit(0)`	Check job logs directly
zsh glob errors	Remote shell is zsh	Wrap commands in `bash -c` or use Python

사용 방법

시작 전 확인

qzcli — 启智平台任务管理

Environment contract

Installation

MCP Integration (optional)

Configuration

Quick Start

Authentication

Resource Discovery

Check Available Nodes

Job Submission

Interactive (recommended for first-time use)

Non-interactive

Env-var passthrough (for existing submission scripts)

HPC / CPU jobs (Slurm)

Batch Submission

Shell loop (alternative)

Job Management

Troubleshooting

관련 작업

더 많은 Skills

monitor-experiment

ablation-planner

alphaxiv

analyze-results

qzcli

사용 방법

시작 전 확인

qzcli — 启智平台任务管理

Environment contract

Installation

MCP Integration (optional)

Configuration

Quick Start

Authentication

Resource Discovery

Check Available Nodes

Job Submission

Interactive (recommended for first-time use)

Non-interactive

Env-var passthrough (for existing submission scripts)

HPC / CPU jobs (Slurm)

Batch Submission

Shell loop (alternative)

Job Management

Troubleshooting

관련 작업

automation-audit-ops

customer-billing-ops

data-scraper-agent

subagent-driven-development

더 많은 Skills

monitor-experiment

ablation-planner

alphaxiv

analyze-results