system · Command reference
qzx explainFileWithGemini
What it does
Previews and optionally sends bounded file samples to Google Gemini for explanation
Command maturity: Alpha
Available for real use and feedback while its interface and behavior can still evolve. This is the current development-checkout assessment. Every future immutable release tag preserves the exact assessment shipped by that version. Available in PyPI 0.2.2.0.9. This page documents the 0.2.2.0.9 alpha development checkout.
Behavior and built-in protections
Live mode applies the changes you request
Preview mode available
Works without invoking native programs
Uses network access for the documented task
No elevation required by design
Preview is the default and never reads credentials, contacts Gemini, or shares content. A real request requires dry_run=false plus apply=true, enforces file, prompt, and per-section sample limits, rejects binary data, authenticates with the x-goog-api-key header, and reports the exact source-character count shared without exposing secrets or upstream error bodies.
Uses the documented external service and shares only the data described below.
This safety classification was reviewed by OpenAI GPT-5.6 Pro against implementation digest sha256:ddc5d31a339e89383a9157b28bf5aae6e5d38a23b501f9728c1df1bab5d2e571 on 2026-08-25.
Exact syntax
qzx explainFileWithGemini <file_path> [sample_size] [model] [custom_prompt] [max_file_size_mb] [dry_run] [apply] --jsonParameters
Swipe or use the horizontal scrollbar to see every column.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| file_path | str | Yes | Not declared | Path to the text file to explain |
| sample_size | int | No | 500 | Characters sampled from the beginning, middle, and end (10-100000; default: 500) |
| model | str | No | "" | Gemini model to use; empty selects a compatible available model |
| custom_prompt | str | No | "" | Custom instruction sent to Gemini before the bounded sample |
| max_file_size_mb | int | No | 10 | Maximum local file size accepted in mebibytes (1-100; default: 10) |
| dry_run | bool | No | true | Preview exactly what kind of data would be shared without contacting Gemini |
| apply | bool | No | false | Authorize the external request; requires dry_run=false |
Input examples
qzx explainFileWithGemini "path/to/file.txt"Preview the bounded sample and external service without sending file content
qzx explainFileWithGemini "path/to/file.txt" 1000 "" "" 10 --dry-run false --applySend up to 1000 characters from each sampled section to Google Gemini
qzx explainFileWithGemini "path/to/file.txt" 500 "gemini-2.5-flash" "" 10 --dry-run false --applyUse a specific available Gemini model after explicit authorization
For the complete structured payload, add --json: qzx explainFileWithGemini <file_path> [sample_size] [model] [custom_prompt] [max_file_size_mb] [dry_run] [apply] --json
Representative output example
This illustrative JSON is derived from the current implementation-backed result contract. It shows what the command can return without claiming a recorded execution; values vary with inputs, host, permissions, and optional tools.
Example command: qzx explainFileWithGemini "path/to/file.txt" --json
{
"success": true,
"message": "Previews and optionally sends bounded file samples to Google Gemini for explanation. In this illustrative example, the command completed successfully.",
"meta": {
"command": "explainFileWithGemini",
"command_maturity": {
"stage": "alpha",
"label": "Alpha",
"sequence": 2,
"public_executable": true,
"stability": "interface_may_change",
"summary": "Available for real use and feedback while its interface and behavior can still evolve.",
"promotion_review_required": false,
"assessment_scope": "development_checkout"
},
"duration_ms": 0,
"schema_version": 1
},
"details": {
"dry_run": true,
"content_shared": true,
"external_service": "Example value"
},
"encoding": "Example value",
"explanation": "Example value",
"external_service": "Example value",
"file_path": "C:\\project\\example.txt",
"file_sha256": "C:\\project\\example.txt",
"file_size_bytes": 4096,
"model_used": "Example value",
"next_step": "Example value",
"sample_size": "Example value",
"usage": "Example value"
}View the JSON result contract
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"success",
"message",
"meta"
],
"properties": {
"success": {
"type": "boolean"
},
"message": {
"type": "string"
},
"meta": {
"type": "object",
"required": [
"command",
"command_maturity",
"duration_ms",
"schema_version"
],
"properties": {
"command": {
"type": "string"
},
"command_maturity": {
"type": "object",
"required": [
"stage",
"label",
"sequence",
"public_executable",
"stability",
"summary",
"promotion_review_required",
"assessment_scope"
],
"properties": {
"stage": {
"type": "string"
},
"label": {
"type": "string"
},
"sequence": {
"type": "integer"
},
"public_executable": {
"type": "boolean"
},
"stability": {
"type": "string"
},
"summary": {
"type": "string"
},
"promotion_review_required": {
"type": "boolean"
},
"assessment_scope": {
"type": "string"
},
"note": {
"type": "string"
},
"review": {
"type": "object",
"required": [
"reviewed_on",
"rationale",
"evidence"
],
"properties": {
"reviewed_on": {
"type": "string",
"format": "date"
},
"rationale": {
"type": "string"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
}
},
"replacement": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"duration_ms": {
"type": "number"
},
"schema_version": {
"type": "integer"
}
},
"additionalProperties": true
},
"details": {
"type": "object",
"properties": {
"dry_run": {
"type": "boolean"
},
"content_shared": {
"type": "boolean"
},
"external_service": []
},
"additionalProperties": true
},
"encoding": [],
"error": [],
"error_code": [],
"explanation": [],
"external_service": [],
"file_path": [],
"file_sha256": [],
"file_size_bytes": [],
"model_used": [],
"next_step": {
"type": "string"
},
"sample_size": [],
"usage": []
},
"additionalProperties": true
}Errors and limits
The public contract requires success=false and a descriptive message on failure. This catalog does not yet declare a command-specific error taxonomy; inspect the result and do not invent error codes.
QZX is alpha software. Optional dependencies, permissions, and host capabilities can change the result.
Evidence workflow: requires an authorized endpoint or reviewed fixture.
Evidence and provenance
- Implementation
- src/qzx/commands/system/explain_file_with_gemini.py
- Documentation channel
- Development documentation 0.2.2.0.9 · main · sha256:cfba936e39931c286ca23add0ae546693db17d8b316e7cbc3891d26642d9b7e8
- Availability
- 0.2.2.0.9 or earlier
Keep exploring
Related commands
These commands also belong to the system category. Compare them to choose the operation that best fits your task.
qzx diagnoseStorageDiagnoses storage pressure by combining disk capacity, large-file discovery, and byte-verified duplicate analysis without deleting anythingqzx getCpuLoadGets information about current CPU usageqzx clearScreenClears an interactive terminal directly without spawning cls, clear, or a command shellqzx getCurrentDateTimeReports the current local date and time with timezone, calendar, ISO-week, and timestamp details