qzcli CLI
A CLI and MCP server for the Qizhi platform: free GPU nodes, job submission and logs, queue reasons from Claude Code
- 144 ★ on the repository
- Last commit
Extended access
Why this level
- The CAS login, password and cookie are stored locally in `~/.qzcli`.
- Submit and stop commands consume cluster quota and interrupt running jobs.
Install
- Works in
Manual install
pip install -r requirements.txt && pip install -e .The first install commands from the README, run inside the `qzcli_tool` clone folder.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The CAS login, password and cookie are stored locally in `~/.qzcli`.
- Submit and stop commands consume cluster quota and interrupt running jobs.
This is third-party code. Review the repository files before installing.
What it does
qzcli manages the Qizhi (启智) cloud model-training platform from a terminal in the style of `kubectl` or `docker`. `qzcli login` obtains a cookie through CAS authentication, `qzcli res -u` refreshes the local cache of workspaces, compute groups and projects, and `qzcli avail` shows free nodes and GPUs per group. Jobs are submitted with `qzcli create` for distributed training, `qzcli hpc` for CPU tasks on Slurm and `qzcli batch` from a JSON file. `qzcli logs <job-id>` reads logs with `tail` and `follow` modes. `qzcli events` explains why a job sits in the queue and shows a node's failure history, including GPU XID errors, so a bad machine can be excluded through `--exclude-node`. A separate `qzcli-mcp` binary opens the same abilities to an agent: it signs in to the platform, refreshes resources, finds free nodes, lists jobs and shows raw statuses. The `skills/qzcli-mcp` skill tells the agent to rely on `status_raw`, because platform status values may change.
Who it is for. Researchers and engineers training models on a Qizhi cluster who want to check the queue and free GPUs through Codex or Claude Code.
Good fit when
- Before launching training you need to know which group has four free nodes.
- A job will not start and the platform's reason for queueing is required.
- A node keeps dropping jobs and its failure history decides what to exclude.
- An agent watches jobs and reports status changes.
Not a fit when
- You have no account on the Qizhi platform: the tool works only with it.
- Workloads run on another cluster or in an ordinary cloud.
- A CAS password or cookie cannot be stored on the agent's machine.
Example request
Sign in to the Qizhi platform and find a compute group with four fully free eight-card nodes.Limitations
The tool is tied to the Qizhi platform and its API, and the documentation is in Chinese. Login goes through CAS, with the password read from the `QZCLI_PASSWORD` variable, `~/.qzcli/.env` or `~/.qzcli/config.json`. If the values differ, `qzcli login` refuses to send a request because the platform locks accounts after failed attempts. The workspace cache must be refreshed with `qzcli res -u` after new projects are added. The `create`, `hpc` and `stop` commands consume cluster quota and stop jobs, so an agent needs human confirmation.
How to disable. Run `codex mcp remove qzcli` or `claude mcp remove qzcli`, then `pip uninstall qzcli`. Clear the cookie with `qzcli cookie --clear` and remove `~/.qzcli`.
FAQ
How do I connect qzcli to Claude Code or Codex?
Install the package, then run `claude mcp add qzcli -- qzcli-mcp` or `codex mcp add qzcli -- qzcli-mcp`. Check the connection with `claude mcp list`. You do not need to start `qzcli-mcp` by hand, the client calls it.
Which tools does the agent see?
They include `qz_auth_login`, `qz_set_cookie`, `qz_refresh_resources`, `qz_get_availability`, `qz_list_jobs`, `qz_get_job_detail` and `qz_inspect_status_catalog`.
How do I find free nodes?
Run `qzcli avail`. The `-n 4 -e` flags look for groups with four free nodes and `--lp` counts nodes held by low-priority jobs.
Why does status_raw matter in MCP?
The platform may change status values. The agent reads the original `status_raw` field and treats the simplified `status_family` only as a hint.
Where is the platform password stored?
The password comes from the `QZCLI_PASSWORD` variable, the `~/.qzcli/.env` file or `~/.qzcli/config.json`, in that order of priority. If the values differ, login is blocked so account lockout attempts are not wasted.
Discussion
No questions or reviews yet.
Related
CLI toolsAn MCP server and CLI that lets an agent query and provision cloud, SaaS and API resources with plain SQL
A Go CLI: plain-language questions to AWS, GCP, Azure, Cloudflare and Kubernetes, change plans and its own MCP server
A CLI and Kubernetes operator that runs Claude Code, Codex, Gemini, OpenCode and Cursor as tasks and sessions inside a cluster
CircleCI CLI
circleci-cli
The official CircleCI CLI shows runs and failing-test logs, while skills and MCP connect it to Claude Code, Codex and Cursor.
Containarium: isolated boxes for AI agents
Containarium
A platform on your own server that gives each agent its own Linux box with SSH and MCP tools for commands and files
The official Vast.ai skill: an agent searches GPU offers, rents instances and manages them through vastai.
README in short
The repository holds the CLI, an MCP server, a `qzcli dashboard` web panel that breaks occupied GPUs down by group, project and user, and API v2 coverage reports. The repository has 54 passing tests.