Skip to content
Skills Library
DevOps & cloud · Automation

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.

Repository
Athena ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

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

qzcliPlatform for enlightenmentsubmit jobstop jobCheck Calculatoravaillist jobsbatch submit

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

  1. Environment contract
  2. Installation
  3. Configuration
  4. Quick Start
  5. Authentication
  6. Resource Discovery
  7. Check Available Nodes
  8. Job Submission
  9. Batch Submission
  10. Job Management
Original SKILL.md headings · 323 lines, 1,146 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.