{"id":50154253,"url":"https://github.com/soakes/quotai","last_synced_at":"2026-05-24T10:01:21.999Z","repository":{"id":359807984,"uuid":"1247562382","full_name":"soakes/quotai","owner":"soakes","description":"A small CLI for showing Z.ai quota usage and exact reset windows.","archived":false,"fork":false,"pushed_at":"2026-05-23T16:14:36.000Z","size":158,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T16:14:42.627Z","etag":null,"topics":["apt","cli","debian","developer-tools","monitoring","python","quota","z-ai","zai"],"latest_commit_sha":null,"homepage":"https://soakes.github.io/quotai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soakes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-23T13:35:44.000Z","updated_at":"2026-05-23T16:14:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/soakes/quotai","commit_stats":null,"previous_names":["soakes/quotai"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/soakes/quotai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soakes%2Fquotai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soakes%2Fquotai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soakes%2Fquotai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soakes%2Fquotai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soakes","download_url":"https://codeload.github.com/soakes/quotai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soakes%2Fquotai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33429192,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"online","status_checked_at":"2026-05-24T02:00:06.296Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apt","cli","debian","developer-tools","monitoring","python","quota","z-ai","zai"],"created_at":"2026-05-24T10:01:18.161Z","updated_at":"2026-05-24T10:01:21.974Z","avatar_url":"https://github.com/soakes.png","language":"Python","funding_links":["https://buymeacoffee.com/soakes"],"categories":[],"sub_categories":[],"readme":"# 📊 QuotAI\n\n\u003e A small terminal CLI for showing Z.ai quota usage, remaining capacity, and exact reset times.\n\n[![Validate](https://img.shields.io/github/actions/workflow/status/soakes/quotai/build-and-validate.yml?branch=main\u0026style=flat-square\u0026label=validate)](https://github.com/soakes/quotai/actions/workflows/build-and-validate.yml)\n[![Release](https://img.shields.io/github/v/release/soakes/quotai?sort=semver\u0026style=flat-square)](https://github.com/soakes/quotai/releases)\n[![APT Repository](https://img.shields.io/badge/APT-signed%20repository-00897B?style=flat-square)](https://soakes.github.io/quotai/)\n[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB.svg?style=flat-square\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-2EA043.svg?style=flat-square)](LICENSE)\n[![Stdlib Only](https://img.shields.io/badge/runtime%20deps-zero-10B981.svg?style=flat-square)](quotai.py)\n[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-FFDD00?style=flat-square\u0026logo=buymeacoffee\u0026logoColor=000000)](https://buymeacoffee.com/soakes)\n\nKeeping 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.\n\nThe default output is for humans. JSON, JSON Lines, compact, and raw modes are available for scripts, dashboards, cron jobs, and debugging.\n\nThis is an unofficial tool and is not affiliated with [Z.ai](https://z.ai).\n\n**Quick links:** [Website and APT repo](https://soakes.github.io/quotai/) | [Releases](https://github.com/soakes/quotai/releases) | [Usage guide](docs/usage.md) | [Release flow](docs/release.md) | [License](LICENSE)\n\n\u003ca id=\"contents\"\u003e\u003c/a\u003e\n## 🧭 Contents\n\n- [📖 Overview](#overview)\n- [✨ Capabilities](#capabilities)\n- [🚀 Installation](#installation)\n- [⚙️ Configuration](#configuration)\n- [🧪 Usage](#usage)\n- [📋 Output Formats](#output-formats)\n- [🚪 Exit Codes](#exit-codes)\n- [🛠️ Development](#development)\n- [🗂️ Project Structure](#project-structure)\n- [📄 License](#license)\n\n\u003ca id=\"overview\"\u003e\u003c/a\u003e\n## 📖 Overview\n\nZ.ai exposes quota information through an authenticated API endpoint. `quotai` turns that response into:\n\n- the current Z.ai plan level\n- the known quota windows, including the five-hour rolling token quota\n- percentage used and percentage remaining\n- exposed limit, used, and remaining unit counts\n- exact reset time in your chosen timezone\n- UTC reset timestamp and epoch milliseconds for machine-readable output\n\nThe script has no runtime dependencies outside the Python standard library.\n\n\u003ca id=\"capabilities\"\u003e\u003c/a\u003e\n## ✨ Capabilities\n\n- Human-friendly terminal panels with colour-coded usage bars\n- Compact one-line output for small terminals and status panes\n- JSON output for `jq`, automation, and monitoring integrations\n- JSON Lines output for logs and append-only collection\n- Raw API response mode for debugging endpoint changes\n- Watch mode for a live refreshing quota dashboard\n- Threshold mode with a separate exit code for cron and shell scripts\n- Timezone control through `--timezone` or `ZAI_TIMEZONE`\n- Installable as a Homebrew formula, signed Debian package, single executable script, or Python package\n\n\u003ca id=\"installation\"\u003e\u003c/a\u003e\n## 🚀 Installation\n\n### Homebrew (macOS and Linux)\n\n```bash\nbrew tap soakes/quotai\nbrew install quotai\n```\n\n### Signed APT Repository\n\nFor Debian and Ubuntu hosts, use the signed GitHub Pages APT repository:\n\n```bash\nsudo install -d -m 0755 /etc/apt/keyrings\ncurl -fsSL https://soakes.github.io/quotai/quotai-archive-keyring.gpg \\\n  | sudo tee /etc/apt/keyrings/quotai-archive-keyring.gpg \u003e/dev/null\n\nsudo tee /etc/apt/sources.list.d/quotai.sources \u003e/dev/null \u003c\u003c'EOF'\nTypes: deb deb-src\nURIs: https://soakes.github.io/quotai/\nSuites: stable\nComponents: main\nSigned-By: /etc/apt/keyrings/quotai-archive-keyring.gpg\nEOF\n\nsudo apt update\nsudo apt install quotai\n```\n\n### Download the Script\n\n```bash\nmkdir -p ~/.local/bin\ncurl -fsSL https://raw.githubusercontent.com/soakes/quotai/main/quotai.py -o ~/.local/bin/quotai\nchmod +x ~/.local/bin/quotai\n```\n\nMake sure `~/.local/bin` is on your `PATH`.\n\n### Install From Git\n\n```bash\npython3 -m pip install git+https://github.com/soakes/quotai.git\n```\n\n### Build From Source\n\n```bash\ngit clone https://github.com/soakes/quotai.git\ncd quotai\npython3 -m pip install .\n```\n\n\u003ca id=\"configuration\"\u003e\u003c/a\u003e\n## ⚙️ Configuration\n\nSet your Z.ai API key in the environment:\n\n```bash\nexport ZAI_API_KEY='your-api-key'\n```\n\nSupported environment variables:\n\n| Variable | Required | Description | Default |\n|---|---:|---|---|\n| `ZAI_API_KEY` | yes | Bearer token used to query the quota endpoint | none |\n| `ZAI_API_URL` | no | Alternate quota endpoint, mainly useful for testing | `https://api.z.ai/api/monitor/usage/quota/limit` |\n| `ZAI_TIMEZONE` | no | Timezone used for displayed reset times | `Europe/London` |\n\nCLI flags take precedence over environment variables.\n\n\u003ca id=\"usage\"\u003e\u003c/a\u003e\n## 🧪 Usage\n\nRun the default terminal view:\n\n```bash\nquotai\n```\n\nExample output:\n\n```text\n  Z.ai plan: pro\n\n  │  5-Hour Rolling Token Quota\n  │\n  │  [████████████░░░░░░░░░░░░] 50% used\n  │  Remaining: 50%\n  │  Limit:      1.0M\n  │  Used:       500.0k\n  │  Remaining: 500.0k\n  │  Resets in:   30m\n  │  Resets at:   2026-05-23 15:00:00 BST\n  ──────────────────────────────────\n```\n\nShow a compact status view:\n\n```bash\nquotai --compact\n```\n\nUse a specific timezone:\n\n```bash\nquotai --timezone America/New_York\n```\n\nRefresh every 30 seconds:\n\n```bash\nquotai --watch 30\n```\n\nExit with code `2` if any quota is at or above 80 percent:\n\n```bash\nquotai --threshold 80\n```\n\n\u003ca id=\"output-formats\"\u003e\u003c/a\u003e\n## 📋 Output Formats\n\n| Format | Flag | Use case |\n|---|---|---|\n| Pretty | default | Human-readable terminal output |\n| Compact | `--compact` | One line per quota |\n| JSON | `--json` | Scripting, dashboards, and `jq` |\n| JSON Lines | `--jsonl` | Logs and append-only collection |\n| Raw | `--raw` | Debugging the upstream API response |\n\nJSON output includes both local and UTC reset fields:\n\n```bash\nquotai --json | jq '.quotas[] | {quota: .name_compact, local: .resets_at, utc: .resets_at_utc}'\n```\n\n```json\n{\n  \"quota\": \"5h-rolling\",\n  \"local\": \"2026-05-23 15:00:00 BST\",\n  \"utc\": \"2026-05-23T14:00:00Z\"\n}\n```\n\n\u003ca id=\"exit-codes\"\u003e\u003c/a\u003e\n## 🚪 Exit Codes\n\n| Code | Meaning |\n|---:|---|\n| `0` | Success |\n| `1` | Runtime or input error |\n| `2` | Threshold exceeded when `--threshold` is set |\n\nThe separate threshold exit code makes it safe to distinguish quota pressure from a broken API key, network failure, or invalid response.\n\n\u003ca id=\"development\"\u003e\u003c/a\u003e\n## 🛠️ Development\n\nCreate a local environment and install the development tools:\n\n```bash\npython3 -m venv .venv\n. .venv/bin/activate\npython3 -m pip install -e '.[dev]'\n```\n\nRun the local checks:\n\n```bash\nmake fmt-check\nmake lint\nmake test\nmake smoke\nmake version-check\n```\n\nFormat code:\n\n```bash\nmake fmt\n```\n\nBuild a Python package:\n\n```bash\nmake build\n```\n\nBuild the website locally:\n\n```bash\nmake website-build\n```\n\n\u003ca id=\"project-structure\"\u003e\u003c/a\u003e\n## 🗂️ Project Structure\n\n```text\nquotai/\n├── quotai.py                 # CLI application\n├── tests/                    # Stdlib unittest coverage\n├── debian/                   # Debian package metadata\n├── homebrew/                 # Homebrew formula template\n├── docs/                     # Usage and release documentation\n├── scripts/                  # Release helper scripts\n├── .github/\n│   ├── assets/website/       # GitHub Pages landing site\n│   └── workflows/            # GitHub Actions release automation\n├── AGENTS.md                 # Repository rules for coding agents\n├── pyproject.toml            # Packaging and tool configuration\n├── Makefile                  # Local validation shortcuts\n├── LICENSE                   # MIT License\n└── README.md                 # Project overview\n```\n\n\u003ca id=\"license\"\u003e\u003c/a\u003e\n## 📄 License\n\n`quotai` is released under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoakes%2Fquotai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoakes%2Fquotai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoakes%2Fquotai/lists"}