CLI API Reference
Auto-generated API documentation for VBAgent CLI modules.
Main Entry Point
main
Main CLI entry point for VBAgent.
VBAgent - Multi-subject question processing pipeline.
Uses lazy loading to speed up CLI startup time by deferring heavy imports (openai, agents, mcp, etc.) until commands are actually invoked.
main
VBAgent - Multi-subject question processing pipeline.
Process question images across physics, chemistry, and mathematics with AI-powered classification, scanning, diagram generation, solution orchestration, and variant creation.
Quick Start: vbagent run -i question.png # Full pipeline vbagent scan -i question.png # Extract problem-only LaTeX vbagent classify -i question.png # Classify only vbagent batch init -i ./images # Batch processing
Classification Commands
classify
CLI command for classifying question images.
Stage 1: Classify question image and detect subject (physics/chemistry/mathematics).
classify
classify(input_path: str, from_index: int | None, to_index: int | None, item: int | None, output: str | None, output_format: str, verbose: bool)
Stage 1: Classify one image or a numbered image range.
Analyzes a question image and extracts metadata including: - Subject (physics, chemistry, mathematics) - Question type (mcq_sc, mcq_mc, subjective, etc.) - Diagram presence and type - Difficulty level
The subject is automatically detected from the image content.
Examples: # Basic classification vbagent classify -i question.png # Numbered image range vbagent classify -i images/problem_1.png --from 1 --to 12 # One numbered item vbagent classify -i images/problem_1.png --item 5 # Output as JSON vbagent classify -i question.png --format json # Save to file vbagent classify -i question.png -o result.json # Chemistry question vbagent classify -i chemistry/thermodynamics.png # Mathematics problem vbagent classify -i math/calculus.png
Supported Subjects: - Physics: mechanics, electromagnetism, optics, thermodynamics, etc. - Chemistry: organic, inorganic, physical chemistry, etc. - Mathematics: algebra, calculus, geometry, trigonometry, etc.
Scanning Commands
scan
CLI command for extracting problem-only LaTeX from question images.
display_scan_result
Display scan result with syntax highlighting.
scan
scan(input_path: str | None, from_index: int | None, to_index: int | None, item: int | None, question_type: str | None, subject: str | None, output: str | None, do_compile: bool, verbose_compile: bool, verbose: bool)
Extract problem-only LaTeX from one image or a numbered image range.
Automatically detects subject and applies appropriate formatting: - Chemistry: \ce{} notation for chemical formulas - Mathematics: Proof structure and set notation - Physics: Vector notation and SI units
Uses the canonical problem stage: classify, extract the question, and reconstruct any diagram. Solution generation is never run by this command. With no --output, results use the same agentic/scans workspace as run.
Examples: vbagent scan -i question.png vbagent scan -i images/problem_1.png --from 1 --to 12 vbagent scan -i images/problem_1.png --item 5 vbagent scan -i question.png -o output.tex vbagent scan -i question.png --type mcq_sc --subject physics vbagent scan -i question.png -v -c
See Also: vbagent run --help Full pipeline with solution generation vbagent classify --help Classification only
Processing Commands
process
CLI command for full pipeline processing.
Thin CLI wrapper that delegates to vbagent.pipeline for actual processing.
run
run(input_path: Optional[str], from_index: Optional[int], to_index: Optional[int], item: Optional[int], variant_types_str: Optional[str], alternate: bool, ideas: bool, ref_dirs: tuple[str, ...], output: str, context: bool, parallel: str, do_compile: bool, verbose_compile: bool, assess_difficulty: bool, solve: bool, merge_metadata: bool, no_cache: bool, clear_cache: bool, animate: bool, verbose: bool)
Full pipeline: Classify → Scan → TikZ → Solve.
Processes question images through the canonical pipeline with solution generation enabled by default. Use --no-solve to skip solutions.
Pipeline: 1. Unified Classification — subject + type + diagram (1 API call) 2. Problem Orchestrator — scan ∥ TikZ (parallel, deterministic) 3. Solution Orchestrator — subject agent → diagram dispatch → stitch 4. Ideas — Extract key concepts (--ideas) 5. Alternates — Generate recommended alternates (--alternate) 6. Variants — Generate problem variants (--variants)
Examples: vbagent run -i question.png vbagent run -i question.png --no-solve vbagent run -i question.png --ideas --alternate vbagent run -i question.png --variants numerical,context vbagent run -i question.png --from 1 --to 5 vbagent run -i question.png --item 3 vbagent run -i question.png -p 4 -c vbagent run -i problems.tex --from 1 --to 5 -p 4
See Also: vbagent scan --help Extract LaTeX only (no solution) vbagent classify --help Classify only vbagent batch --help Batch processing with resume
TikZ Commands
tikz
CLI command for generating TikZ diagram code.
Generates TikZ/PGF code for physics diagrams from images or descriptions.
tikz
tikz(image: str | None, description: str | None, tex: str | None, ref_dirs: tuple[str, ...], output: str | None, do_compile: bool, verbose_compile: bool)
Generate TikZ code for physics diagrams.
Can generate TikZ code from: - An image (-i/--image) - A text description (-d/--description) - A problem text file (-t/--tex) - Any combination of the above
Optionally searches reference files (STY, TeX, PDF) for syntax examples.
Examples: vbagent tikz -d "Free body diagram with gravity and normal force" vbagent tikz -i diagram.png -o diagram.tex vbagent tikz -t problem.tex -o diagram.tex vbagent tikz -t problem.tex -i reference.png -o diagram.tex vbagent tikz -d "RC circuit" --ref refs/circuitikz/ -o circuit.tex
Variant Commands
variant
Durable, accepted-parent problem variants.
extract_items_from_tex
Extract individual items from a TeX file.
filter_items_by_range
Filter items by the specified range.
variant
variant(parent_spec_id: str, variant_types: tuple[str, ...], count: int, output: str, seed: int, max_attempts: int, concurrency: int, max_lineage_depth: int, max_per_parent: int, human_review: bool, start: bool)
Create controlled variants only from an accepted canonical parent.
Every variant is independently solved, answer-adjudicated, syllabus checked, compiled, reviewed, and novelty checked. Raw TeX/image transformation is no longer a creation path; first author or ingest an accepted parent.
Example
vbagent variant --parent-spec-id
Batch Processing
batch
CLI commands for batch processing with resume capability.
Provides init and continue commands for processing multiple images
with SQLite-based state tracking and caffeinate support.
SleepInhibitor
batch
Batch processing commands with resume capability.
Process multiple images through the full pipeline with SQLite-based state tracking and automatic resume on interruption.
Commands: init - Initialize and start batch processing continue - Resume from where you left off status - Show current progress
Examples: vbagent batch init -i ./images vbagent batch continue vbagent batch status
continue_batch
Continue batch processing from where it left off.
Resumes processing using the existing SQLite database. Use --reset-failed to retry previously failed images.
Examples: vbagent batch continue vbagent batch continue --reset-failed
Tip: Run 'vbagent batch status' to see current progress.
discover_images
Discover all images in a directory matching the pattern.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
images_dir
|
str
|
Directory to search |
required |
pattern
|
str
|
Glob pattern for images (default: *.png) |
'*.png'
|
Returns:
| Type | Description |
|---|---|
list[str]
|
Sorted list of image paths |
init
Initialize batch processing for all images in a directory.
Scans the images directory, creates a SQLite database to track progress, and starts processing all images through the full pipeline.
Examples: vbagent batch init vbagent batch init -i ./my_images vbagent batch init --images-dir ./images --output ./results vbagent batch init --variants numerical,context --no-alternate vbagent batch init --variants numerical,cross_topic vbagent batch init -i ./images -o ./output --no-context
process_single_image
process_single_image(db: 'BatchDatabase', record: 'ImageRecord', variant_types: list[str], generate_alternates: bool, output_dir: str, use_context: bool = True, max_retries: int = 2) -> bool
Process a single image through the pipeline with state tracking.
Returns True if successful, False if failed.
Quality Assurance
check
CLI commands for QA review with interactive approval workflow.
Provides check command for random spot-checking of processed physics
questions with AI-powered quality review and diff-based suggestions.
apply
Apply a previously rejected suggestion.
Retrieves a stored suggestion by ID and applies its diff. Use --edit to review/modify the suggested content in your editor first.
Examples: vbagent check apply 42 vbagent check apply 42 -e vbagent check apply 42 --edit
apply_suggestion
Apply an approved suggestion to the file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
suggestion
|
'Suggestion'
|
The suggestion to apply |
required |
problem_id
|
str
|
Problem ID for path resolution |
''
|
Returns:
| Type | Description |
|---|---|
'DiffResult'
|
DiffResult with success status and error details if failed |
check
QA review commands for spot-checking processed problems.
Commands: run - Start a random QA review session init - Initialize problem tracking database continue - Continue from where you left off status - Show check progress recheck - Reset problems for rechecking alternate - Generate alternate solutions idea - Generate idea summaries solution - Check solution correctness grammar - Check grammar and spelling clarity - Check clarity and conciseness edit - Apply an explicit instruction to selected scanned TeX format - Check formatting and structure tikz - Check/generate TikZ diagrams apply - Apply a stored suggestion history - View suggestion history resume - Resume interrupted session stats - View review statistics
Examples: vbagent check run vbagent check init -d ./agentic vbagent check continue -c 10 vbagent check status vbagent check alternate -d ./src_tex/ vbagent check idea -d ./src_tex/ vbagent check solution -d ./src_tex/ vbagent check grammar -d ./src_tex/ vbagent check clarity -d ./src_tex/ vbagent check edit -d ./scans --from 1 --to 5 --instruction "Add the question instruction" vbagent check tikz -d ./scans/ # Check/generate TikZ vbagent check tikz --patch --ref-type circuit
check_alternate
check_alternate(output_dir: str, count: int, min_alternates: int, problem_id: Optional[str], images_dir: Optional[str], prompt: Optional[str], auto_approve: bool)
Check and generate alternate solutions for problems.
Scans all .tex files in the specified directory (or subdirectories), checks if they have alternate solutions, and generates new ones with interactive approval.
The alternate solution is appended to the problem file using the \begin{alternatesolution}...\end{alternatesolution} environment.
Images are matched by filename (e.g., problem_1.tex -> problem_1.png). Use --prompt to add specific instructions for generating alternates.
Supports: - Direct directory with .tex files (e.g., ./src/src_tex/) - Agentic folder structure (scans/, variants/) - Single .tex file
Examples: vbagent check alternate vbagent check alternate -d ./src/src_tex/ vbagent check alternate -d ./src/src_tex/ -i ./src/src_images/ vbagent check alternate --dir ./problem_1.tex vbagent check alternate -c 10 vbagent check alternate --count 10 --min-alternates 2 vbagent check alternate -p Problem_1 vbagent check alternate --prompt "Use energy conservation method" vbagent check alternate -d ./agentic/scans -p Problem_5
check_clarity_cmd
check_clarity_cmd(output_dir: str, count: int, problem_id: Optional[str], prompt: Optional[str], reset: bool, auto_approve: bool)
Check content for clarity and conciseness.
Reviews text for unclear statements, verbose explanations, and pedagogical improvements. Prompts for approval to apply changes.
Use --prompt to add specific instructions for the checker.
Examples: vbagent check clarity vbagent check clarity -d ./src/src_tex/ vbagent check clarity -c 10 vbagent check clarity -p Problem_1 vbagent check clarity --prompt "Keep explanations brief for JEE level" vbagent check clarity --reset vbagent check clarity -y -c 56
check_edit_cmd
check_edit_cmd(output_dir: str, from_index: Optional[int], to_index: Optional[int], item: Optional[int], problem_id: Optional[str], instruction: str, all_items: bool, allow_math_changes: bool, auto_approve: bool)
Apply one explicit editing instruction to selected scanned TeX files.
Mathematical expressions are protected by default. Proposed changes are shown for approval unless --yes is supplied. The editor never infers the academic task: state it once with --instruction and apply it to a range.
Examples: vbagent check edit --from 1 --to 5 \ --instruction 'Prefix each item with "Find the period of the function"' vbagent check edit --item 7 \ --instruction 'Replace "Calculate" with "Find"' --yes vbagent check edit --all \ --instruction 'Make every question statement concise'
check_format_cmd
check_format_cmd(output_dir: str, count: int, problem_id: Optional[str], prompt: Optional[str], reset: bool, auto_approve: bool)
Check and fix formatting issues specific to problem types.
Reviews content for: - Metadata cleanup (example numbers, exam years) - LaTeX structure issues - Problem-type specific formatting (MCQ, subjective, etc.) - Common OCR errors and truncated words
Use --prompt to add specific instructions for the checker.
Examples: vbagent check format vbagent check format -d ./src/src_tex/ vbagent check format -c 10 vbagent check format -p Problem_1 vbagent check format --prompt "Focus on MCQ option formatting" vbagent check format --reset vbagent check format -y -c 56
check_grammar_cmd
check_grammar_cmd(output_dir: str, count: int, problem_id: Optional[str], prompt: Optional[str], reset: bool, auto_approve: bool)
Check content for grammar and spelling errors.
Reviews text for grammar, spelling, punctuation, and awkward phrasing issues. Prompts for approval to apply fixes.
Use --prompt to add specific instructions for the checker.
Examples: vbagent check grammar vbagent check grammar -d ./src/src_tex/ vbagent check grammar -c 10 vbagent check grammar -p Problem_1 vbagent check grammar --prompt "Use British English spelling" vbagent check grammar --reset vbagent check grammar -y -c 56
check_idea
Generate and append idea summaries to problems.
Scans .tex files, extracts key concepts/formulas/techniques,
and appends them in a \begin{idea}...\end{idea} environment.
Supports: - Direct directory with .tex files - Agentic folder structure (scans/, variants/) - Single .tex file
Examples: vbagent check idea vbagent check idea -d ./src/src_tex/ vbagent check idea -c 10 vbagent check idea -p Problem_1
check_solution_cmd
check_solution_cmd(output_dir: str, count: int, problem_id: Optional[str], images_dir: Optional[str], prompt: Optional[str], reset: bool, auto_approve: bool)
Check or create solutions for physics problems.
If a solution EXISTS: Verifies calculations, physics principles, and final answers. If a solution is MISSING: Creates a complete solution using the problem context.
Prompts for approval before applying corrections or new solutions. Images are matched by filename (e.g., problem_1.tex -> problem_1.png). Use --prompt to add specific instructions for the checker.
Examples: vbagent check solution vbagent check solution -d ./src/src_tex/ vbagent check solution -d ./src/src_tex/ -i ./src/src_images/ vbagent check solution -c 10 vbagent check solution -p Problem_1 vbagent check solution --prompt "Focus on unit consistency" vbagent check solution --reset vbagent check solution -y -c 56
check_status
Show check progress and status.
Displays statistics for problem checking in the specified directory.
Examples: vbagent check status vbagent check status -d ./my_output vbagent check status -s pending vbagent check status --show failed vbagent check status --dir ./agentic --show all
check_tikz_cmd
check_tikz_cmd(output_dir: str, count: int, problem_id: Optional[str], images_dir: Optional[str], prompt: Optional[str], only_tikz: bool, reset: bool, patch: bool, use_context: bool, ref_type: Optional[str], auto_approve: bool)
Check and generate TikZ diagram code.
This command has two modes:
-
CHECK MODE: Reviews existing TikZ/PGF code for syntax errors, missing libraries, and physics diagram conventions.
-
GENERATE MODE: If a file has \input{diagram} placeholder but no TikZ code, automatically generates TikZ from the corresponding image (auto-discovered in images/ directory).
Images are auto-discovered by filename (e.g., Problem_1.tex -> images/Problem_1.png) or can be specified with --images-dir.
Reference examples are matched by diagram type from classification metadata, or can be filtered manually with --ref-type.
Use --patch to enable apply_patch mode for more precise edits.
Examples: vbagent check tikz # Check/generate in agentic/ vbagent check tikz -d ./scans/ # Check specific directory vbagent check tikz -d ./scans/Problem_1.tex # Check single file vbagent check tikz -c 10 # Process 10 files vbagent check tikz -p Problem_1 # Check specific problem vbagent check tikz -i ./images/ # Explicit images directory vbagent check tikz --only-tikz # Skip files without TikZ vbagent check tikz --reset # Re-check all files vbagent check tikz --patch # Use apply_patch mode vbagent check tikz --ref-type circuit # Use only circuit references vbagent check tikz --prompt "Use circuitikz" # Add instructions
continue_check
Continue checking from where you left off.
Picks up pending problems from the tracking database and runs AI-powered quality review with interactive approval.
Examples: vbagent check continue vbagent check continue -c 10 vbagent check continue --count 10 --dir ./my_output
display_suggestion
Display a suggestion with all details.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
suggestion
|
'Suggestion'
|
The suggestion to display |
required |
console
|
'Console'
|
Rich console for output |
required |
format_diff_error
Format a diff error for display.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
result
|
'DiffResult'
|
DiffResult with error information |
required |
Returns:
| Type | Description |
|---|---|
str
|
Human-readable error message |
history
Display rejected suggestion history.
Shows previously rejected suggestions that can be applied later.
Examples: vbagent check history vbagent check history -p Problem_42 vbagent check history --problem-id Problem_42 --limit 50 vbagent check history -f conceptual_variant.tex -n 10
init_check
init_check(output_dir: str, from_index: Optional[int], to_index: Optional[int], item: Optional[int], legacy_range: Optional[tuple[int, int]], reset: bool)
Initialize problem check tracking.
Discovers all problems in the output directory and adds them to the tracking database. Use --from and --to to limit to specific problems.
Examples: vbagent check init vbagent check init -d ./my_output vbagent check init --dir ./agentic --from 1 --to 50 vbagent check init --from 1 --to 50 vbagent check init --item 5 vbagent check init --reset
prompt_review_action
Display suggestion and prompt user for action.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
suggestion
|
'Suggestion'
|
The suggestion to review |
required |
console
|
'Console'
|
Rich console for output |
required |
Returns:
| Type | Description |
|---|---|
ReviewAction
|
The user's chosen action |
recheck
Reset problems for rechecking.
Resets the status of problems to pending so they can be checked again.
Examples: vbagent check recheck vbagent check recheck --failed vbagent check recheck -p Problem_1 vbagent check recheck -p Problem_1 -p Problem_2 vbagent check recheck --dir ./output --failed
resolve_file_path
Resolve a stored file path to an actual file.
Tries multiple strategies to find the file: 1. Direct path (if absolute or exists relative to cwd) 2. Look in common output directories (agentic/, output/) 3. Search for problem_id directory and find file within
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stored_path
|
str
|
The path stored in the database |
required |
problem_id
|
str
|
The problem ID associated with this file |
required |
Returns:
| Type | Description |
|---|---|
Optional[str]
|
Resolved path if found, None otherwise |
resume
Resume an interrupted review session.
If no session ID is provided, shows a list of incomplete sessions. Session IDs can be shortened (prefix match).
Examples: vbagent check resume vbagent check resume abc12345 vbagent check resume abc
run_check
Start a QA review session.
Randomly selects problems from the output directory and runs AI-powered quality review with interactive approval.
Examples: vbagent check run vbagent check run -c 10 vbagent check run --count 10 --dir ./output vbagent check run -p Problem_42 vbagent check run --problem-id Problem_42 -d ./my_output
run_review_session
run_review_session(problems: list, store: 'VersionStore', console: 'Console', output_dir: str = 'agentic', session_id: Optional[str] = None) -> dict
Run an interactive review session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problems
|
list
|
List of problem contexts to review |
required |
store
|
'VersionStore'
|
Version store for saving rejected suggestions |
required |
console
|
'Console'
|
Rich console for output |
required |
output_dir
|
str
|
Output directory being reviewed (for resume capability) |
'agentic'
|
session_id
|
Optional[str]
|
Optional existing session ID (for resume) |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with session statistics |
MCP Authoring Interface
chat
Clean, transparent natural-language CLI for MCP-backed authoring.
ChatPrompt
Interactive input with private, session-local message history.
ask
Read one message; Up selects older history and Down selects newer.
RichChatRenderer
Render complete controller-tool traces and compact model telemetry.
mcp
CLI command for the authoring-focused MCP server.
mcp
Serve durable problem authoring through Model Context Protocol.
The MCP host supplies the natural-language model. VBAgent exposes typed
catalog, plan, start, status, pagination, cancellation, review, variant,
and artifact operations backed by the same ledger as vbagent author.
Stdio example for an MCP client configuration:
{ "mcpServers": { "vbagent-authoring": { "command": "vbagent", "args": ["mcp", "--output", "agentic/authoring"] } } }
Database Management
db
CLI commands for database management.
db
Database management for question bank.
Commands: init - Initialize database from directory insert - Insert problems into database update - Update existing question query - Query questions with filters stats - Show database statistics export - Export questions from database delete - Delete question by ID
delete
Delete question by ID (cascade deletes children).
Examples: vbagent db delete 42
init
Initialize empty database.
Creates database schema without inserting any questions. Use 'vbagent db insert' to add questions later.
Examples: vbagent db init # Create default database vbagent db init --db-path custom.db # Create custom database vbagent db init --force # Recreate existing database
insert
Insert problems into database.
Examples: vbagent db insert ./new_questions vbagent db insert ./questions --update-existing vbagent db insert ./questions --classify
query
query(db_path: str, subject: str, chapter: str, topic: str, difficulty: str, question_type: str, limit: int, output_format: str)
Query questions with filters.
Examples: vbagent db query --topic Kinematics vbagent db query --difficulty medium --subject physics vbagent db query --type passage --format json
Reference Management
ref
CLI commands for managing reference context files.
Provides commands to add, remove, list, and configure reference files stored in ~/.config/vbagent for use as context in LLM prompts.
add
Add a reference file to a category.
Arguments: CATEGORY Category to add to (tikz, latex, variants, problems) FILE Path to the file to add
Examples: vbagent ref add tikz my_diagram.tex vbagent ref add variants example.tex -n "numerical_example.tex" vbagent ref add latex formatting.tex -d "Standard formatting template"
disable
Disable context usage in prompts.
When disabled, reference files will not be included in prompts.
enable
Enable context usage in prompts.
When enabled, reference files will be included as examples in LLM prompts to improve output quality.
list_refs
List all reference files.
Examples: vbagent ref list vbagent ref list -c tikz
ref
Manage reference files for context.
Reference files are stored in ~/.config/vbagent/references/ and can be used as examples to improve LLM output quality.
Categories: tikz - TikZ/PGF code examples latex - LaTeX formatting examples variants - Variant generation examples problems - Example physics problems
Examples: vbagent ref add tikz diagram.tex vbagent ref add variants example.tex -d "Numerical variant" vbagent ref list vbagent ref list -c tikz vbagent ref remove tikz diagram.tex vbagent ref enable vbagent ref disable vbagent ref status
remove
Remove a reference file.
Arguments: CATEGORY Category of the reference NAME Name of the reference file
Examples: vbagent ref remove tikz diagram.tex vbagent ref remove variants example.tex
set_max
Set maximum examples per category.
Controls how many reference files from each category are included in prompts.
Arguments: MAX_EXAMPLES Maximum number of examples (1-20)
Examples: vbagent ref set-max 3 vbagent ref set-max 10
show
Show the content of a reference file.
Arguments: CATEGORY Category of the reference NAME Name of the reference file
Examples: vbagent ref show tikz diagram.tex
tikz_group
Manage TikZ references with metadata-based context.
TikZ references are stored with classification metadata (diagram_type, topic, subtopic) for intelligent context matching.
Commands: import - Import TikZ from processed problem list - List TikZ references remove - Remove a TikZ reference show - Show TikZ reference content status - Show TikZ reference statistics
Examples: vbagent ref tikz import agentic/scans/Problem_5.tex vbagent ref tikz import -d agentic/scans -r 1 10 vbagent ref tikz list vbagent ref tikz list --diagram-type pulley vbagent ref tikz status
tikz_import
tikz_import(path: str, from_index: Optional[int], to_index: Optional[int], item: Optional[int], legacy_range: tuple | None, tikz_dir: str, class_dir: str)
Import TikZ references from processed problems.
Extracts TikZ code and loads classification metadata automatically. Can import a single file or a range of problems from a directory.
Arguments: PATH Path to scan file or scans directory
Examples: # Import single problem vbagent ref tikz import agentic/scans/Problem_5.tex
# Import range from directory
vbagent ref tikz import agentic/scans --from 1 --to 10
# Import single item
vbagent ref tikz import agentic/scans --item 5
# Import with custom tikz/classification directories
vbagent ref tikz import agentic/scans/Problem_5.tex -t agentic/tikz -c agentic/classifications
tikz_list
List TikZ references.
Examples: vbagent ref tikz list vbagent ref tikz list --diagram-type pulley vbagent ref tikz list -t mechanics
tikz_remove
Remove a TikZ reference.
Arguments: REF_ID ID of the reference to remove
Examples: vbagent ref tikz remove Problem_5
tikz_show
Show TikZ reference content.
Arguments: REF_ID ID of the reference to show
Examples: vbagent ref tikz show Problem_5
Configuration
config
CLI commands for configuring vbagent models.
Provides commands to view and set model configurations for different agents.
config
Configure models, providers, and pipeline settings.
Quick Start: vbagent config show View current config vbagent config set tikz -m gpt-5.6-sol Set model for an agent vbagent config provider xai Switch provider vbagent config subject chemistry Change subject
Config Files: Global: ~/.config/vbagent/models.json Workspace: .vbagent.json (overrides global)
Agent Groups: Classification classifier, diagram_classifier, ... Extraction scanner, converter Diagram tikz, fbd, circuit, graph, optics, ... Generation idea, alternate, variant, solution Quality reviewer, solution_checker, format_checker, ...
Use -w/--workspace on any set/provider/subject command to save to .vbagent.json instead of the global config.
debug
Enable or disable DEBUG agent logging.
This is an alias for switching log-level between DEBUG and INFO.
Debug mode prints detailed input/output for all agent calls.
Examples: vbagent config debug on # Enable debug mode vbagent config debug off # Disable debug mode vbagent config debug status # Show current status vbagent config debug on -w # Enable in workspace config
init
Initialize workspace config interactively.
Creates .vbagent.json in current directory with customized settings.
This is an alias for vbagent init.
Examples: vbagent config init # Interactive setup vbagent config init --quick # Only ask for subject vbagent config init --yes # Use all defaults vbagent config init --force # Overwrite existing
log_level
Set logging level for agent operations.
Controls the verbosity of logging output.
Levels: DEBUG - Detailed debug information INFO - General informational messages (default) WARNING - Warning messages only ERROR - Error messages only CRITICAL - Critical errors only
Examples: vbagent config log-level DEBUG # Enable debug logging vbagent config log-level INFO # Set to info level vbagent config log-level status # Show current level vbagent config log-level DEBUG -w # Set in workspace config
model_group
View or apply a model group.
Model groups are pre-configured sets of models for each agent, optimized per provider. Switching providers auto-applies the matching group, but you can also apply one manually.
Examples: vbagent config model-group # List all groups vbagent config model-group openai # Apply OpenAI group vbagent config model-group xai # Apply xAI group vbagent config model-group google -w # Apply Google group to workspace
provider
Set the API provider (openai, xai, google, or custom URL).
Switching providers auto-applies the matching model group so every agent gets the right model. Use --no-models to skip this.
Known Providers: openai - OpenAI (default, no base_url needed) xai - xAI Grok (https://api.x.ai/v1) google - Google Gemini (OpenAI-compatible endpoint)
Examples: vbagent config provider openai vbagent config provider xai --api-key xai-xxx vbagent config provider xai --workspace vbagent config provider xai --no-models # keep current models vbagent config provider --base-url https://custom.api/v1
set_agent
Set model configuration for an agent type.
Arguments: AGENT_TYPE Agent to configure (or 'default' for global defaults)
Agent Types (by group): Classification: classifier, diagram_classifier, taxonomy_classifier, ... Extraction: scanner, converter Diagram: tikz, fbd, circuit, graph, optics, organic_structure, ... Generation: idea, alternate, variant, solution Quality: reviewer, solution_checker, format_checker, ...
Examples: vbagent config set default -m gpt-5.6-luna Global default vbagent config set classifier -m gpt-5.6-luna -r medium Classification vbagent config set scanner -m gpt-5.6-terra -r medium Extraction vbagent config set tikz -m gpt-5.6-sol -r high Diagram vbagent config set circuit -m gpt-5.6-sol -r high Diagram (specialist) vbagent config set idea -m gpt-5.6-terra -r high Generation vbagent config set alternate -m gpt-5.6-terra -r high Generation vbagent config set solution -m gpt-5.6-sol -r high Generation vbagent config set variant -m gpt-5.6-terra -r high Generation vbagent config set format_checker -m gpt-5.6-luna Quality vbagent config set scanner -m gpt-5.6-terra -w Save to workspace
set_model
Set a single model for ALL agents, or revert to auto (two-tier).
In single-model mode every agent uses the same model while per-category reasoning effort tiers are preserved (medium for classifiers and scanner, high for diagrams/solutions).
Use 'auto' to clear single-model mode and revert to the configured per-category defaults (Luna for classification, Terra for scanning).
Examples: vbagent config set-model gpt-5.6-terra # Everything uses Terra vbagent config set-model gpt-5.6-luna # Everything uses Luna vbagent config set-model auto # Revert to two-tier vbagent config set-model gpt-5.6-terra -w # Workspace only
show
Show current model configuration for all agents.
Examples: vbagent config show Full grouped table vbagent config show --compact One-line summary per group
subject
Set the subject for prompts.
Subjects: physics - Physics problems (default) chemistry - Chemistry problems mathematics - Mathematics problems biology - Biology problems
Examples: vbagent config subject chemistry vbagent config subject physics --workspace
Utilities
util
Utility commands for file management.
Provides helper commands for organizing and managing question files.
clean
Remove generated files and directories.
Examples: vbagent util clean --output # Remove agentic/ directory vbagent util clean --config # Remove .vbagent.json vbagent util clean --all # Remove everything vbagent util clean -a -y # Remove all without confirmation
count
Count files by type in a directory.
Examples: vbagent util count images/ vbagent util count . --recursive
list
List files ready for processing.
Shows files that can be processed with vbagent run.
Examples: vbagent util list images/ vbagent util list . --ext .tex
rename
rename(directory: str, prefix: str, start: int, ext: tuple, dry_run: bool, yes: bool, preserve_order: bool, shuffle: bool, lowercase: bool, uppercase: bool, pad: int)
Rename files to serialized format.
Renames files in a directory to a consistent format like: problem_1.png, problem_2.png, problem_3.png, etc.
Examples: vbagent util rename images/ # Rename to problem_N.png vbagent util rename . --prefix Q # q_1.png, q_2.png, ... vbagent util rename . --ext .tex # Rename .tex files vbagent util rename . --start 10 # Start from problem_10.png vbagent util rename images/ --dry-run # Preview changes vbagent util rename . --preserve-order # Keep existing numbers vbagent util rename . --shuffle # Randomize order vbagent util rename . --uppercase # Problem_1.png vbagent util rename . --pad 3 # problem_001.png
util
Utility commands for file management.
Commands: rename - Rename files to serialized format (Problem_1.png, etc.) count - Count files by type in a directory clean - Remove generated files (agentic/, .vbagent.json)
Examples: vbagent util rename images/ vbagent util rename . --prefix Question --ext .tex vbagent util count images/ vbagent util clean
Common Utilities
common
Common CLI utilities for interactive sessions.
Provides shared functionality for: - Diff display with Rich color coding - Interactive action prompts - Session summary display - Signal handling for graceful shutdown - LaTeX formatting - Editor integration