📊 QuotAI

A small terminal CLI for showing Z.ai quota usage, remaining capacity, and exact reset times.

Keeping an eye on your AI quota. quotai (pronounced quota-eye) queries the Z.ai quota endpoint and renders the result in a terminal view that is easy to read at a glance. It was built because the Z.ai usage charts are useful, but they do not make the rolling five-hour reset window and exact reset time clear enough when you are trying to plan work.

The default output is for humans. JSON, JSON Lines, compact, and raw modes are available for scripts, dashboards, cron jobs, and debugging.

This is an unofficial tool and is not affiliated with Z.ai.

Quick links: Website and APT repo | Releases | Usage guide | Release flow | License

🧭 Contents

• 📖 Overview
• ✨ Capabilities
• 🚀 Installation
• ⚙️ Configuration
• 🧪 Usage
• 📋 Output Formats
• 🚪 Exit Codes
• 🛠️ Development
• 🗂️ Project Structure
• 📄 License

📖 Overview

Z.ai exposes quota information through an authenticated API endpoint. quotai turns that response into:

• the current Z.ai plan level
• the known quota windows, including the five-hour rolling token quota
• percentage used and percentage remaining
• exposed limit, used, and remaining unit counts
• exact reset time in your chosen timezone
• UTC reset timestamp and epoch milliseconds for machine-readable output

The script has no runtime dependencies outside the Python standard library.

✨ Capabilities

• Human-friendly terminal panels with colour-coded usage bars
• Compact one-line output for small terminals and status panes
• JSON output for jq, automation, and monitoring integrations
• JSON Lines output for logs and append-only collection
• Raw API response mode for debugging endpoint changes
• Watch mode for a live refreshing quota dashboard
• Threshold mode with a separate exit code for cron and shell scripts
• Timezone control through --timezone or ZAI_TIMEZONE
• Installable as a Homebrew formula, signed Debian package, single executable script, or Python package

🚀 Installation

Homebrew (macOS and Linux)

brew tap soakes/quotai
brew install quotai

Signed APT Repository

For Debian and Ubuntu hosts, use the signed GitHub Pages APT repository:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://soakes.github.io/quotai/quotai-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/quotai-archive-keyring.gpg >/dev/null

sudo tee /etc/apt/sources.list.d/quotai.sources >/dev/null <<'EOF'
Types: deb deb-src
URIs: https://soakes.github.io/quotai/
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/quotai-archive-keyring.gpg
EOF

sudo apt update
sudo apt install quotai

Download the Script

mkdir -p ~/.local/bin
curl -fsSL https://raw.githubusercontent.com/soakes/quotai/main/quotai.py -o ~/.local/bin/quotai
chmod +x ~/.local/bin/quotai

Make sure ~/.local/bin is on your PATH.

Install From Git

python3 -m pip install git+https://github.com/soakes/quotai.git

Build From Source

git clone https://github.com/soakes/quotai.git
cd quotai
python3 -m pip install .

⚙️ Configuration

Set your Z.ai API key in the environment:

export ZAI_API_KEY='your-api-key'

Supported environment variables:

Variable	Required	Description	Default
ZAI_API_KEY	yes	Bearer token used to query the quota endpoint	none
ZAI_API_URL	no	Alternate quota endpoint, mainly useful for testing	https://api.z.ai/api/monitor/usage/quota/limit
ZAI_TIMEZONE	no	Timezone used for displayed reset times	Europe/London

CLI flags take precedence over environment variables.

🧪 Usage

Run the default terminal view:

quotai

Example output:

  Z.ai plan: pro

  │  5-Hour Rolling Token Quota
  │
  │  [████████████░░░░░░░░░░░░] 50% used
  │  Remaining: 50%
  │  Limit:      1.0M
  │  Used:       500.0k
  │  Remaining: 500.0k
  │  Resets in:   30m
  │  Resets at:   2026-05-23 15:00:00 BST
  ──────────────────────────────────

Show a compact status view:

quotai --compact

Use a specific timezone:

quotai --timezone America/New_York

Refresh every 30 seconds:

quotai --watch 30

Exit with code 2 if any quota is at or above 80 percent:

quotai --threshold 80

📋 Output Formats

Format	Flag	Use case
Pretty	default	Human-readable terminal output
Compact	--compact	One line per quota
JSON	--json	Scripting, dashboards, and jq
JSON Lines	--jsonl	Logs and append-only collection
Raw	--raw	Debugging the upstream API response

JSON output includes both local and UTC reset fields:

quotai --json | jq '.quotas[] | {quota: .name_compact, local: .resets_at, utc: .resets_at_utc}'

{
  "quota": "5h-rolling",
  "local": "2026-05-23 15:00:00 BST",
  "utc": "2026-05-23T14:00:00Z"
}

🚪 Exit Codes

Code	Meaning
0	Success
1	Runtime or input error
2	Threshold exceeded when --threshold is set

The separate threshold exit code makes it safe to distinguish quota pressure from a broken API key, network failure, or invalid response.

🛠️ Development

Create a local environment and install the development tools:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e '.[dev]'

Run the local checks:

make fmt-check
make lint
make test
make smoke
make version-check

Format code:

make fmt

Build a Python package:

make build

Build the website locally:

make website-build

🗂️ Project Structure

quotai/
├── quotai.py                 # CLI application
├── tests/                    # Stdlib unittest coverage
├── debian/                   # Debian package metadata
├── homebrew/                 # Homebrew formula template
├── docs/                     # Usage and release documentation
├── scripts/                  # Release helper scripts
├── .github/
│   ├── assets/website/       # GitHub Pages landing site
│   └── workflows/            # GitHub Actions release automation
├── AGENTS.md                 # Repository rules for coding agents
├── pyproject.toml            # Packaging and tool configuration
├── Makefile                  # Local validation shortcuts
├── LICENSE                   # MIT License
└── README.md                 # Project overview

📄 License

quotai is released under the MIT License.