Jutge Toolkit

A powerful command-line toolkit for creating and managing programming problems on the Jutge.org platform.

Key Features

• 📝 Create new problems from scratch or using templates
• 🤖 Generate problems using JutgeAI
• 🔧 Compile and test solutions in multiple programming languages
• 📄 Generate statements in PDF, HTML, Markdown and text formats automatically
• ✅ Verify solutions against test cases
• 🎬 Stage problems matching Jutge.org specifications
• ☁️ Upload and update problems directly to Jutge.org
• ✨ Beautiful terminal interface with color output and help

Documentation

• Getting Started Guide - Complete guide to using the toolkit
• Problem Anatomy - Understanding problem structure and files
• Quiz Anatomy - Understanding quiz problems and question types
• JutgeAI Features - Using AI to generate content
• Command Reference - Complete reference of all commands and options

Installation

The toolkit requires Bun as a JavaScript runtime. Follow the installation guides for your platform:

• Linux Installation Guide
• macOS Installation Guide
• Windows Installation Guide

Quick Install

If you already have Bun installed:

bun install --global @jutge.org/toolkit

Verify the installation:

jtk --version

Getting Started

Quick Start

# Get help
jtk
jtk --help

# Check system dependencies
jtk doctor

# Ask JutgeAI for help (requires API key setup)
jtk ask "How do I create a problem?"

# Clone a template problem interactively
jtk clone

# Generate a new problem with AI
jtk generate problem

# Build problem files
cd my-problem.pbm
jtk make

# Verify a solution (locally)
jtk verify candidate.py

# Upload to Jutge.org
jtk upload

# Submit a solution to Jutge.org
jtk submit candidate.py

For a complete walkthrough, see the Getting Started Guide.

Flow Overview

1. Create a problem

   • Use jtk clone to start from a template
   • Use jtk generate problem to create with JutgeAI
   • Create problem structure manually if preferred

2. Edit the problem

   • Modify statements, test cases, and solutions as needed
   • Use jtk generate translations to add multilingual support
   • Use jtk generate solutions to add alternative solutions
   • Use jtk generate generate tests to create test cases generator

3. Build the problem

   • Run jtk make to build all problem elements (statements, solutions, correct test cases)

4. Optional: Locally verify candidate solutions

   • Use jtk verify <solution> to test candidate solutions for correctness

5. Optional: Stage the problem

   • Run jtk stage to stage the files as will be used by Jutge.org

6. Upload the problem

   • Use jtk upload to publish the problem on Jutge.org

     Remember that Jutge.org does not generate the correct test cases; you must provide them.

7. Optional: Test a candidate solution by submitting it to Jutge.org

   • Use jtk submit -l <language> <solution> to submit the solution to Jutge.org in a specific language

     In order to submit a candidate solution, you need to have the problem uploaded to Jutge.org. This solution will be judged by Jutge.org and you will get its verdict.

Common Commands

# Configuration
jtk config show                     # View current configuration
jtk config set <key> <value>        # Set a configuration value
jtk config edit                     # Edit configuration file

# Problem Creation
jtk clone [template]                # Clone a template problem
jtk generate problem                # Generate problem with AI
jtk generate translations en es ca  # Add statement translations
jtk generate solutions python cpp   # Generate solutions in other languages

# Building and Testing
jtk make                            # Build all problem elements
jtk make pdf                        # Generate PDF statements only
jtk verify <program>                # Test a solution
jtk lint                            # Lint (analyze for errors and warnings) the problem
jtk clean                           # Clean temporary files

# Staging
jtk stage                           # Stage problem for Jutge.org

# Publishing
jtk upload                          # Upload problem to Jutge.org

# Removing
jtk remove                          # Remove problem from Jutge.org

# Testing
jtk submit -l en candidate.py       # Submit a candidate solution to Jutge.org

# Sharing settings
jtk share                           # Show and update sharing settings (passcode, testcases, solutions)
jtk share --passcode <code>         # Set a passcode
jtk share --no-passcode             # Clear the passcode
jtk share --testcases               # Share testcases
jtk share --solutions               # Share solutions

# Maintenance
jtk upgrade                         # Update to latest version
jtk doctor                          # Check system dependencies
jtk about                           # Show toolkit information

Requirements

Core Requirements

• Bun - JavaScript runtime (required)

Optional Dependencies

• LaTeX (for PDF generation) - texlive-xetex, texlive-fonts-recommended
• Pandoc (for format conversion)
• Programming language compilers/interpreters - Python, GCC/G++, Java, etc. (depending on your needs)

Run jtk doctor to check which dependencies are installed on your system.

Support

• Documentation: Check the docs folder for detailed guides
• Get Help: Use jtk ask "your question" to get AI-powered assistance
• Issues: Report bugs and feature requests on GitHub Issues
• Community: Visit Jutge.org for the problem platform

License

Apache License 2.0

Credits

• Jordi Petit
• Pau Fernández

© Universitat Politècnica de Catalunya - BarcelonaTech (UPC), 2026.