zerogpu-cli

The official command-line interface for ZeroGPU — run fast, edge-optimized inference models (classification, extraction, redaction, chat, summarization) right from your terminal.

Installation
Quick Start
Authentication
Commands
Environment Variables
Output
Troubleshooting
Contributing
License

Installation

npm install -g zerogpu-cli@latest

Requires Node.js 20+.

Verify the install:

zerogpu --version
zerogpu --help

Quick Start

# 1. Sign in (you'll be prompted for your API key)
zerogpu login

# 2. Check your session
zerogpu status

# 3. Run your first command
zerogpu summarize "ZeroGPU runs small, fast models at the edge so you can ship AI features without managing GPUs."

Authentication

Every inference command requires a valid API key. You can provide it in two ways:

zerogpu login — stores the credential in a local config file and exports ZEROGPU_API_KEY to your shell profile.
Environment variable — set ZEROGPU_API_KEY directly (useful for CI).

Get your API key (zgpu-api-…) from the ZeroGPU dashboard.

Commands

All commands follow the pattern:

zerogpu <command> [arguments] [options]

Run zerogpu <command> --help for command-level help.

Account

`login`

zerogpu login
zerogpu login --api-key zgpu-api-xxxxxxxx

Option	Description
`--api-key <key>`	Provide the API key directly (skips the prompt).

`status`

Check whether you're signed in and where the API key was loaded from.

zerogpu status

Chat & Generation

`chat`

Chat with a ZeroGPU text-generation model. Defaults to LFM2.5-1.2B-Instruct; use --model to reach for a larger reasoning model.

zerogpu chat "Explain edge inference in one sentence."
zerogpu chat "Translate to French: Good morning." -i "You are a precise translator."

# Frontier-grade reasoning, with the trace printed alongside the answer
zerogpu chat "Why does my API keep getting rate-limited?" -m gpt-oss-120b -r

# Multilingual reasoning
zerogpu chat "Explique la mise en cache en une phrase." -m qwen3-30b-a3b-fp8

# A 262K-token context, for whole repos and very long documents
zerogpu chat "$(cat ARCHITECTURE.md)" -m glm-5.2

# Coding and agentic work, at a fraction of the flagship price
zerogpu chat "Port this helper to async/await." -m deepseek-v4-flash-0731

Option	Description
`-i, --instructions <text>`	System instructions that steer the assistant's behavior.
`-m, --model <model>`	Model to use (default `LFM2.5-1.2B-Instruct`).
`-r, --reasoning`	Also print the reasoning trace, for models that return one.

Model	Notes
`LFM2.5-1.2B-Instruct`	Default. Fast edge chat.
`LFM2.5-1.2B-Thinking`	Compact reasoning model.
`gpt-oss-120b`	120B MoE, 131K context, reasoning + function calling.
`llama-guard-4-12b`	12B dense, 164K context, brand safety + text moderation.
`deepseek-v4.1-flash`	Sparse MoE (8B active on input, 16B on output), 1M context, long-context agentic work + function calling.
`qwen3-30b-a3b-fp8`	30B MoE, 100+ languages, reasoning + function calling.
`glm-5.2`	753B MoE, 262K context, reasoning + function calling. The platform's most capable model, and its priciest.
`deepseek-v4-flash-0731`	284B MoE (13B active), 1M context, coding and agentic workflows.

qwen3-30b-a3b-fp8, glm-5.2, and deepseek-v4-flash-0731 are served by the Chat Completions API rather than the Responses API; the CLI routes them automatically.

`chat_thinking`

Chat with the LFM2.5-1.2B-Thinking model, which returns reasoning alongside its answer.

zerogpu chat_thinking "If a train leaves at 3pm at 60mph, when does it arrive 180 miles later?"

`summarize`

Summarize text with the llama-3.1-8b-instruct-fast model.

zerogpu summarize "Long article text goes here..."

Classification

`classify_iab`

Classify text against the IAB audience and content taxonomy using the ZeroGPU IAB edge model.

zerogpu classify_iab "Tips for first-time homebuyers in 2026."

`classify_iab_enriched`

Same as classify_iab but returns enriched output: audience, topics, keywords, and intent.

zerogpu classify_iab_enriched "Best running shoes for marathon training."

`classify_domain`

Classify a domain name against the IAB taxonomy using the ZeroGPU domain edge model. Takes only the hostname — no page fetch or body text — so it suits bidstream enrichment and inventory-level targeting.

zerogpu classify_domain nytimes.com

Returns scored content categories plus topics, keywords, and inferred user intent for the domain. When you have the page text and need per-URL precision, use classify_iab instead.

`classify_structured`

Classify text against a structured schema of categories and allowed labels using GLiNER2.

zerogpu classify_structured "The product arrived broken and I want a refund." \
  --schema '{"sentiment":["positive","negative","neutral"],"intent":["complaint","praise","question"]}'

Option	Description
`-s, --schema <json>`	Required. JSON object mapping category name → allowed labels.

`classify_zero_shot`

Zero-shot classification against arbitrary candidate labels using DeBERTa v3.

# Repeat --label for each candidate
zerogpu classify_zero_shot "The stock market dropped 3% today." \
  --label finance --label sports --label politics

# Or pass them as a comma-separated list
zerogpu classify_zero_shot "The stock market dropped 3% today." \
  --labels finance,sports,politics

Option	Description
`-l, --label <label>`	Candidate label (repeatable).
`--labels <a,b,c>`	Comma-separated list of candidate labels.

Extraction

`extract_entities`

Extract named entities from text using GLiNER2 with custom labels.

zerogpu extract_entities "Tim Cook visited the Cupertino campus on Tuesday." \
  --label person --label organization --label location --threshold 0.4

Option	Default	Description
`-l, --label <label>`	—	Entity label to extract (repeatable).
`--labels <a,b,c>`	—	Comma-separated entity labels.
`-t, --threshold <number>`	`0.3`	Confidence threshold between 0 and 1.

`extract_json`

Extract structured JSON from text against a provided schema using GLiNER2.

zerogpu extract_json "Email Jane Doe at jane@example.com or call 555-0100." \
  --schema '{"contact":["name::str::Full name","email::str::Email address","phone::str::Phone number"]}'

Option	Description
`-s, --schema <json>`	Required. Schema as a JSON string. Field format: `name::type::description`.

`extract_pii`

Extract PII entities (persons, emails, phone numbers, etc.) using gliner-multi-pii-v1.

zerogpu extract_pii "Contact John Smith at john@acme.com or +1-415-555-0100." \
  --threshold 0.5 --categories identity,contact

Option	Default	Description
`-t, --threshold <number>`	`0.5`	Confidence threshold.
`-c, --categories <list>`	`identity,contact`	Comma-separated PII categories.

`redact_pii`

Detect and redact PII in text — returns the input with sensitive spans masked by label.

zerogpu redact_pii "Call Sarah at 415-555-0100 or email sarah@acme.com."

Endpoints

Call a ZeroGPU API endpoint directly, with any model. These commands keep no model list: the model you pass is sent as-is, so a model the platform adds or renames works without a CLI update. They are the stable surface the ZeroGPU agent plugins build on.

Text comes from the positional argument, or from stdin when there isn't one, which keeps very large prompts off the command line.

Option	Applies to	Description
`-m, --model <model>`	all	Required. Model id, sent exactly as given.
`-i, --instructions <text>`	`responses`, `chat_completions`	`responses`: the `instructions` field. `chat_completions`: a system message ahead of the text.
`--metadata <json>`	`responses`, `chat_completions`	JSON object sent as `metadata` — the per-model options such as `usecase`, `labels`, `schema`, `threshold`.
`--body <json>`	all	Extra top-level request fields, e.g. `'{"max_output_tokens":256}'`. Fields set by the other options take precedence.
`--raw`	`responses`, `chat_completions`	Print the full API response instead of only the model's text.

responses and chat_completions print the model's text, pretty-printed when it is JSON. moderations and embeddings print the full response. Every call is recorded for cost_savings, like the task commands.

`responses`

POST to /v1/responses.

zerogpu responses "Email John Smith at john@acme.com." -m gliner-multi-pii-v1 \
  --metadata '{"usecase":"redact","mask":"label"}'

# Long input from a file, on stdin
zerogpu responses -m gpt-oss-120b -i "Summarize this report." < report.txt

`chat_completions`

POST to /v1/chat/completions. Also available as chat-completions.

zerogpu chat_completions "Explique la mise en cache en une phrase." -m qwen3-30b-a3b-fp8

zerogpu chat_completions "The app uses Python 3.11 and PostgreSQL 15." -m gliner2-base-v1 \
  --metadata '{"usecase":"ner","labels":["programming language","database"],"threshold":0.3}'

`moderations`

POST to /v1/moderations.

zerogpu moderations "Screen this comment before we publish it." -m zlm-v1-moderation-edge

`embeddings`

POST to /v1/embeddings.

zerogpu embeddings "ZeroGPU runs small models at the edge." -m all-minilm-l6-v2

Environment Variables

Variable	Purpose
`ZEROGPU_API_KEY`	Overrides the API key from the config file. Set automatically by `zerogpu login` for your default shell.

Output

Inference commands print the model's response to stdout. When the response is valid JSON, it is pretty-printed.
Errors and diagnostic messages are written to stderr.
All commands exit with code 0 on success and 1 on failure — safe to use in pipelines and scripts.

Example:

zerogpu classify_iab "Tips for first-time homebuyers." > result.json

Troubleshooting

You're not fully signed in yet. Run zerogpu login again, or check zerogpu status.
That doesn't look like a valid API key Keys must start with zgpu-api-.
ZEROGPU_API_KEY not picked up in a new shell: open a new terminal, or source your shell config file (the login command prints the path).
HTTP errors are surfaced with the response status and body — inspect them to debug request issues.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md and our Code of Conduct.

Security concerns? See SECURITY.md.

git clone https://github.com/zerogpu/cli.git
cd cli
npm install
npm run build
npm test

License

Released under the MIT License.

zerogpu/cli

Details