Skip to content

Command Reference

This document provides a complete reference for all Zaojun command-line options and arguments.

Command Syntax

zaojun [PYPROJECT_TOML] [OPTIONS]

Arguments

PYPROJECT_TOML

Type: Path (optional) Default: ./pyproject.toml Description: Path to the pyproject.toml file to check

Examples: 

# Check current directory
zaojun

# Check specific file
zaojun /path/to/project/pyproject.toml

# Check file with different name
zaojun dependencies.toml

Options

--short, --no-short

Type: Boolean flag Default: --no-short (show full output) Description: Show only the shortest possible output

When enabled (--short): - Only shows dependencies that need updates - Omits "up to date" messages - Omits section headers - Useful for scripts and CI/CD pipelines

Examples: 

# Full output (default)
zaojun
# Output: Shows all dependencies with status

# Short output
zaojun --short
# Output: Only shows packages needing updates

--groups, --no-groups

Type: Boolean flag Default: --no-groups (check only main dependencies) Description: Check dependencies in all dependency groups

When enabled (--groups): - Checks [project.dependencies] section - Checks all [dependency-groups] sections - Shows each group separately in output - Useful for projects with development, test, or documentation dependencies

Examples: 

# Check only main dependencies (default)
zaojun
# Output: Only checks [project.dependencies]

# Check all dependency groups
zaojun --groups
# Output: Checks [project.dependencies] and all [dependency-groups]

--compat-ok, --no-compat-ok

Type: Boolean flag Default: --no-compat-ok (compatible updates cause exit code 1) Description: Treat compatible version updates as acceptable

When enabled (--compat-ok): - Compatible updates (⚠️) don't cause exit code 1 - Only incompatible updates (❌) cause exit code 1 - Useful during development or in CI/CD where you want to allow compatible updates

Examples: 

# Default: All updates cause exit code 1
zaojun
# Exit code: 1 if any ⚠️ or ❌ updates

# Compatible updates don't cause errors
zaojun --compat-ok
# Exit code: 1 only if ❌ updates, 0 if only ⚠️ updates

--cache, --no-cache

Type: Boolean flag Default: --no-cache (caching disabled) Description: Enable caching of PyPI API responses

When enabled (--cache): - PyPI API responses are cached locally for 24 hours - Subsequent runs use cached data for faster execution - Cache is stored in ~/.cache/zaojun/pypi_cache/ - Useful for repeated checks during development

Examples: 

# Default: No caching (backward compatible)
zaojun
# Always fetches fresh data from PyPI

# Enable caching for faster repeated runs
zaojun --cache
# First run: Fetches from PyPI and caches results
# Subsequent runs: Uses cached data (much faster)

# Explicitly disable caching
zaojun --no-cache
# Always fetches fresh data from PyPI

--clear-cache, --no-clear-cache

Type: Boolean flag Default: --no-clear-cache (preserve cache) Description: Clear all cache entries before checking

When enabled (--clear-cache): - All cached PyPI API responses are deleted - Fresh data is fetched from PyPI - Cache statistics are reset - Useful when you want to force fresh data or troubleshoot cache issues

Examples: 

# Clear cache and check dependencies
zaojun --clear-cache
# Output: "Cleared X cache entries" then normal output

# Clear cache with caching enabled
zaojun --cache --clear-cache
# Clears cache, then fetches fresh data and caches it

# Clear cache with groups
zaojun --groups --clear-cache
# Clears cache, then checks all dependency groups

--cache-stats, --no-cache-stats

Type: Boolean flag Default: --no-cache-stats (don't show statistics) Description: Show cache statistics after checking

When enabled (--cache-stats): - Shows cache hit/miss statistics - Displays cache configuration and status - Useful for monitoring cache effectiveness - Only shows when --short is not used

Examples: 

# Show cache statistics
zaojun --cache-stats
# Output: Normal output followed by cache statistics

# Enable caching and show statistics
zaojun --cache --cache-stats
# Output: Normal output with cache hits/misses

# Clear cache and show statistics
zaojun --clear-cache --cache-stats
# Output: Shows cleared entries, normal output, then statistics

--help, -h

Type: Boolean flag Description: Show help message and exit

Displays usage information, available options, and examples.

Example: 

zaojun --help

Cache Management

Zaojun includes a powerful caching system to improve performance for repeated dependency checks.

Cache Location

Cache files are stored in a platform-appropriate location: - Linux/Unix: ~/.cache/zaojun/pypi_cache/ (respects XDG_CACHE_HOME) - macOS: ~/Library/Caches/zaojun/pypi_cache/ - Windows: %LOCALAPPDATA%\zaojun\pypi_cache\

Cache Expiration

  • Cache entries expire after 24 hours (configurable)
  • Expired entries are automatically removed on access
  • Manual clearing via --clear-cache option

Cache Contents

Each cached package includes: - Package metadata (name, version, release info) - Timestamp for TTL calculation - Full PyPI response data

Cache Performance

  • First run with --cache: Cache misses (fetches from PyPI)
  • Subsequent runs: Cache hits (uses local data)
  • Performance improvement: 10-100x faster for repeated checks

--version

Type: Boolean flag Description: Show version information and exit

Displays the current Zaojun version.

Example: 

zaojun --version
# Output: zaojun 1.0.3

Exit Codes

Zaojun uses the following exit codes to indicate results:

Code Meaning Description
0 Success All dependencies are up to date (or only compatible updates with --compat-ok)
1 Updates needed Updates are available (incompatible or compatible without --compat-ok)
2 Error Invalid arguments, file not found, or other errors

Environment Variables

Zaojun respects the following environment variables:

HTTP_PROXY, HTTPS_PROXY

Type: URL Description: Proxy server for HTTP/HTTPS requests

Use these variables if you need to access PyPI through a proxy server.

Example: 

export HTTPS_PROXY="http://proxy.example.com:8080"
zaojun

NO_PROXY

Type: Comma-separated list Description: Hosts that should not use the proxy

Example: 

export NO_PROXY="localhost,127.0.0.1,.internal"
zaojun

Common Option Combinations

CI/CD Pipeline Check

zaojun --short --groups
- Minimal output for clean logs - Checks all dependency groups - Exit code 1 if any updates needed

Development with Caching

zaojun --cache --cache-stats --groups
- Enables caching for faster repeated checks - Shows cache statistics to monitor effectiveness - Checks all dependency groups - Ideal for development workflows

Cache Management

zaojun --clear-cache --cache --cache-stats
- Clears existing cache entries - Enables caching for future runs - Shows cache statistics - Useful for forcing fresh data

Development Environment

zaojun --groups --compat-ok --cache
- Checks all dependencies - Allows compatible updates - Enables caching for faster repeated checks - Warns about incompatible updates

Quick Status Check

zaojun --short --cache
- Fast, minimal output - Quick overview of update status - Enables caching for repeated checks - Easy to parse in scripts

Comprehensive Check

zaojun --groups --cache --cache-stats
- Full detailed output - Checks everything - Enables caching for performance - Shows cache statistics - Complete dependency status

Option Precedence

When multiple options conflict or interact:

  1. File path is always processed first
  2. Output format (--short) affects all output
  3. Scope (--groups) determines what to check
  4. Tolerance (--compat-ok) affects exit code

Examples with Multiple Options

Complete Project Check

zaojun /path/to/project/pyproject.toml --groups --compat-ok --cache
- Checks specific file - Includes all dependency groups - Compatible updates don't cause errors - Enables caching for faster future checks

Script-Friendly Output

zaojun --short --groups --cache
- Minimal, parseable output - Includes all groups - Enables caching for performance - Clear exit code for automation

Development Workflow with Caching

# Initial check with caching
zaojun --groups --cache --cache-stats

# If updates needed, check with compat-ok
zaojun --groups --compat-ok --cache

# Update if only compatible updates
zaojun --short --compat-ok --cache
if [ $? -eq 0 ]; then
    uv sync -U --all-groups
fi

# Clear cache periodically
zaojun --clear-cache --cache-stats
```

Cache Option Interactions

Cache options interact with other options in specific ways:

  1. --cache with --clear-cache: Cache is cleared, then new data is fetched and cached
  2. --cache-stats with --short: Statistics are not shown (short output suppresses them)
  3. --no-cache with --clear-cache: Cache is cleared, but no new data is cached
  4. --cache with network errors: Falls back gracefully, doesn't affect cached data

Deprecated Options

No options are currently deprecated. All options shown here are supported in the current version.

Version Compatibility

  • Cache options: Available in Zaojun 1.0.0 and later
  • Other options: Available in Zaojun 0.9.0 and later
  • Earlier versions: May not support cache options

Cache Version History

  • 1.0.0: Initial cache implementation with TTL-based expiration (✅ COMPLETED)
  • Future considerations: Configurable TTL, cache size limits, and other enhancements

zaojun vs pip list --outdated

  • Zaojun: Checks against version constraints in pyproject.toml
  • pip: Shows all installed packages with newer versions available

zaojun vs uv pip compile --upgrade

  • Zaojun: Reports what updates are available, supports caching
  • uv pip compile: Generates updated lock files

zaojun Cache vs Other Tools

  • Zaojun cache: Project-specific, respects version constraints
  • pip cache: Package installation cache
  • HTTP cache: General HTTP response caching

Getting Help

For more information or to report issues:

See Also