qzcli
/qzcli
Manage GPU compute jobs on the Qizhi (Xinji!) platform using qzcli — a kubectl-style CLI tool. Use when user says "qzcli", "Platform for enlightenment", "submit job", "stop job", "Check Calculator", "avail", "list jobs", "batch submit", or needs to manage distributed training jobs on a Qizhi instance.
- Author
- jiangfeng-strathclyde ↗
- Repository
- Athena ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Manage GPU compute jobs on the Qizhi (Xinji!) platform using qzcli — a kubectl-style CLI tool. Use when user says "qzcli", "Platform for enlightenment", "submit job", "stop job", "Check Calculator", "avail", "list jobs", "batch submit", or needs to manage distributed training jobs on a Qizhi instance.
Triggers from the description
Arguments
/qzcli [login|avail|list|create|stop <job-id>|batch|status|watch]
Original author description
Manage GPU compute jobs on the Qizhi (Xinji!) platform using qzcli — a kubectl-style CLI tool. Use when user says "qzcli", "Platform for enlightenment", "submit job", "stop job", "Check Calculator", "avail", "list jobs", "batch submit", or needs to manage distributed training jobs on a Qizhi instance.
How it works
- Environment contract
- Installation
- Configuration
- Quick Start
- Authentication
- Resource Discovery
- Check Available Nodes
- Job Submission
- Batch Submission
- Job Management
SKILL.md preview
---
name: qzcli
description: Manage GPU compute jobs on the Qizhi (Xinji!) platform using qzcli — a kubectl-style CLI tool. Use when user says "qzcli", "Platform for enlightenment", "submit job", "stop job", "Check Calculator", "avail", "list jobs", "batch submit", or needs to manage distributed training jobs on a Qizhi instance.
argument-hint: "[login|avail|list|create|stop <job-id>|batch|status|watch]"
allowed-tools: Bash(*), Read, Write
---
# qzcli — Mission management of the enlightenment platform
A kubectl/docker-style CLI for managing GPU compute jobs on the Qizhi (Xinji!) platform.
**GitHub:** [tianyilt/qzcli_tool](https://github.com/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` |
| `No name found 'xxx' Workspace` | 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 |
## Mirror description (additional to this open warehouse)
- This document is considered upstream. ARIS mirrors in original;support files (scripts/、references/、../shared-references/)Not distributed with mirrors, full originals can be found at the upstream warehouse https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep 。
- If supporting documents are cited for implementation skills, then the relative path should be parsed from the upstream warehouse.
Versions
The database has no other skills named qzcli.
Database snapshot: 13.11.2026 · package version e2c58cb9c0c3 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90REPLACE-WITH-PLATFORM-NAME
Where and how GPU jobs run on this platform. One-to-three-sentence summary. Use when the user asks to "deploy on REPLACE-PLATFORM", "run on REPLACE-PLATFORM", or mentions the platform's distinctive concepts (e.g., resource shape, instance, node group). - 100schedule-cron-jobs
Manage scheduled automation jobs - list, add, remove, enable, disable, run now, status. Use when user says "schedule cron", "add cron job", "list cron jobs", "run job now". - 100compshare-cli
Manage CompShare GPU cloud resources and MiniMax H3 video, image, and speech tasks through the compshare CLI. Use when Codex needs to install or configure compshare-cli, search GPU specifications and inventory, inspect pricing, create or manage instances, connect over SSH,… - 95lightning-jobs
Launch and manage batch jobs on Lightning AI - run commands on cloud CPUs/GPUs from a Docker image or a Studio snapshot, monitor status, show live progress with an ETA and setback tracking (status-line bar + Monitor events), fetch logs, SSH into a running job or multi-machine… - 100tao-run-on-kubernetes
Kubernetes execution platform — submits TAO container jobs as k8s Jobs with NVIDIA GPU scheduling; single-pod for one node, Indexed Jobs for multi-node distributed training. Use when running on EKS / GKE / AKS / on-prem clusters with the NVIDIA GPU Operator installed, or when… - 100mila-run-jobs
Use this skill when the user asks about running jobs or code on the Mila cluster. Trigger phrases include: "How do I run a job", "How do I run my first job", "How do I train a model", "mila code", "sbatch", "salloc", "VSCode on the cluster", "How do I use a GPU", "How do I…