Justfile Commands

The project uses just as a command runner for common tasks. Think of it as shortcuts for commands you run often.

Quick Start

New to the project? Start here:

just prod-up      # Start everything
just status       # Check it's working
just prod-down    # Stop when done

That's it for basic operation. See Common Workflows for task-oriented patterns.

Command Cheat Sheet

Use this table for quick lookups. Commands are prioritized by usage frequency.

Priority	Command	Purpose	When to Use
🔴 Essential	`just prod-up [rebuild]`	Start all services	Every session start
🔴 Essential	`just status`	Check container health	Verify everything works
🔴 Essential	`just prod-down [clean]`	Stop services	End of session
🔴 Essential	`just prod-logs [service]`	View logs	Debugging issues
🟡 Common	`just dev`	Dev mode with hot reload	Active coding
🟡 Common	`just dev-watch`	Dev mode + worker reload	Full hot reload
🟡 Common	`just stop [clean]`	Stop everything	Clean up dev environment
🟡 Common	`just embed <path>`	Batch embed documents	Upload documents
🟡 Common	`just search "query"`	Run search from terminal	Test search
🟡 Common	`just test`	Run all tests	Before committing
🟢 Occasional	`just test-cov`	Tests with coverage	Coverage reports
🟢 Occasional	`just check`	All code quality checks	CI/pre-commit
🟢 Occasional	`just search-smoke`	Quick search test	Verify search works
🟢 Occasional	`just eval-retrieval`	Run retrieval evaluation	Benchmarking
🟢 Occasional	`just bench-run <label> <folder>`	Measure ingestion throughput	Benchmarking document pipelines
🟢 Occasional	`just bench-compare <baseline> <current>`	Compare throughput reports	Review benchmark regressions
🟢 Occasional	`just version`	Print the Product Version resolved by the app	Confirm the local release version
🟢 Occasional	`just version-check`	Verify Product Version consistency	Release checks and CI parity
🟢 Occasional	`just version-bump <version>`	Update the Product Version source and lock metadata	Preparing a release version bump
🟢 Occasional	`just embed test-documents/banking`	Embed demo documents	Quick testing
⚠️ Destructive	`just wipe [confirm] [relaunch]`	Clear Redis/Qdrant data	Start fresh

Legend:

🔴 Essential — Used in every session
🟡 Common — Used regularly during development
🟢 Occasional — Used for specific tasks
⚠️ Destructive — Irreversible data loss

Common Workflows

First Time Setup

just setup              # Install dependencies
just prod-up            # Start everything
just status             # Verify it's working
just search-smoke       # Test search is functional

Daily Development Loop

just dev                # Start dev mode (hot reload API + workers)
# ... edit code ...
just stop               # Clean up when done (kills background workers)

tip

Note: When using just dev, pressing Ctrl+C stops the API server but background workers may persist. Always run just stop to clean up all processes.

Production Deployment

# First deploy or after infrastructure changes
just prod-up rebuild    # Build images and start
just prod-smoke         # Verify images and the deployed API version
just status             # Confirm all services healthy

# Subsequent deploys
just prod-up            # Fast start (uses cached images)
just status             # Verify health

Embed & Search Documents

just prod-up            # Ensure services are running
just embed ./my-docs    # Upload documents from folder
just status             # Check processing status
just search "machine learning"   # Test search

Advanced search options:

# Full JSON response
just search "machine learning" -- --json

# With filters and reranking
just search "compliance" -- --limit 10 --alpha 0.6 --rerank --min-score 0.5

# Filter by document ID
just search "quarterly report" -- --filter document_id=doc-123

# Filter by multiple metadata values
just search "budget report" -- --filters '{"department":["finance","operations"]}' --json

Code Quality Checks

just lint               # Check for issues
just lint-fix           # Fix auto-fixable issues
just format             # Format code
just typecheck          # Run type checker
just version-check      # Verify Product Version consistency
just check              # Run all checks at once

Product Version Management

The Product Version identifies the running InfoConnect release. It is edited in one place, pyproject.toml, and is resolved by the Python package metadata at runtime. The API exposes the resolved value in GET /health as version and in /openapi.json as info.version.

# Show the version resolved by the local app package
just version

# Verify pyproject.toml, uv.lock, app metadata, /health runtime metadata,
# and committed openapi.json are all aligned
just version-check

# Prepare a SemVer release bump without committing or tagging
just version-bump 0.2.0

just check runs just version-check before the normal quality gates, and CI runs the same guard. If the check fails, update the single source in pyproject.toml through just version-bump <version> rather than hand-editing runtime constants.

Production recipes use just prod-verify-version to guard against stale deployed images. See Deployed Version Verification.

Managing Disk Space

Over time, Docker images and build cache can consume significant disk space.

# During active development — fast restart
just prod-up
# ... work ...
just prod-down          # Preserves images for fast restart

# End of day — free disk space
just prod-down clean    # Removes images and build cache

# Next day — fresh start (rebuilds images)
just prod-up            # Takes longer but ensures clean state

Trade-offs:

just prod-down — Fast restart, but disk usage grows over time
just prod-down clean — Frees ~90% of Docker disk space, but next start takes longer

tip

If you run just prod-up rebuild frequently, you may accumulate many unused Docker image layers. Run just prod-down clean weekly to reclaim space.

Starting Fresh (⚠️ Destroys Data)

warning

This deletes ALL data including vectors, collections, and job queues. This cannot be undone.

just wipe                       # Confirm destruction interactively
just wipe -y                    # Confirm inline (one-liner)
just wipe -y relaunch           # Wipe and relaunch production
just prod-up                    # Start clean
just status                     # Verify

Command Reference by Activity

System Lifecycle

Commands for starting, stopping, and monitoring the system.

`just prod-up [rebuild]`

Start all production services via Docker Compose with auto-tuning.

# Start services (uses cached images)
just prod-up

# Rebuild and start (after code changes)
just prod-up rebuild

What it starts:

API server (FastAPI on port 8000)
Celery preprocessing workers
Celery embedding workers
Redis (task queue)
Qdrant (vector database)

Auto-tuning: Uses host CPU/RAM to determine optimal worker counts. Inspect computed values in .runtime/prod.env after startup.

Worker isolation check: Before starting the API and workers, prod-up starts Redis and Qdrant, then checks the shared Celery broker for registered workers. Startup stops if a worker belongs to another Git revision or does not use a revision-bearing node name. The error lists every offending node and the commands to stop it; stop those workers and rerun just prod-up. See Worker and Performance Settings for the revision naming contract.

Deployed version check: After all services become ready, prod-up runs just prod-verify-version and only reports startup success if that check passes.

Access points:

API Docs: http://localhost:8000/docs
Qdrant Dashboard: http://localhost:6333/dashboard

`just prod-verify-version`

Compare the Product Version in pyproject.toml with the version reported by the running API's GET /health endpoint at localhost:8000.

just prod-verify-version

The command uses a 10-second request timeout. It fails clearly if the API is unreachable, the health response is invalid, or the versions differ. On a mismatch, rebuild the production image with just prod-up rebuild.

just prod-up runs this check after its service-readiness wait, and just prod-smoke runs the same recipe after its image checks.

`just prod-down [clean]`

Stop all Docker Compose services.

# Stop services (preserves data and images)
just prod-down

# Stop and remove all data (volumes, vectors, caches, images, build cache)
just prod-down clean

warning

The clean option removes:

All Qdrant data (uploaded documents, search indexes)
All Redis data (job queues, results)
All unused Docker images (forces rebuild on next start)
All Docker build cache

This cannot be undone.

`just prod-rebuild`

Rebuild and restart all production services. Shorthand for just prod-up rebuild && just prod-smoke.

just prod-rebuild

Useful after code changes to ensure fresh images.

`just prod-logs [service]`

Follow logs from production services in real time.

# Follow all logs
just prod-logs

# Follow specific service
just prod-logs api
just prod-logs worker-embedding-1
just prod-logs worker-preprocessing-1

Available services: api, worker-embedding-1, worker-embedding-2, worker-preprocessing-1, redis, qdrant

`just status [mode]`

Check service health using a Rich terminal dashboard.

just status              # Auto-detect mode, static snapshot
just status live         # Live updating display (1s refresh)
just status docker       # Docker environment only
just status local        # Local process environment only

Use live when watching a running ingest or debugging queue pressure. Use docker for production-style Compose deployments. Use local when you started Redis/Qdrant in Docker but run the API and workers directly with just dev.

Common options include:

Flag	Description
`--iterations N`	Run N refresh cycles and exit, useful for CI or one-shot checks
`--details SERVICES CONTAINERS`	Show extra detail panels for services and containers
`--env auto\|docker\|local`	Override environment detection

The dashboard shows container or local process status, API health, Redis/Qdrant readiness, worker snapshots, queue pressure, resource usage, and recent alerts when available.

`just prod-smoke`

Run smoke tests on Docker images and verify the deployed API version.

just prod-smoke

Validates:

API image imports correctly
Worker images can load ML models
The running API's GET /health version matches pyproject.toml

The production API must already be running on localhost:8000. See Deployed Version Verification for failure behavior.

`just stop [clean]`

Stop all services including local processes (dev mode).

# Stop everything (preserves data)
just stop

# Stop and wipe all data
just stop clean

Kills:

Docker Compose services
Uvicorn processes on port 8000
Celery worker processes
watchfiles processes

warning

The clean option also removes generated files (*.json) and Python cache files.

`just wipe [confirm] [relaunch]`

Destructive Command

This stops everything and permanently destroys application data including:

All Qdrant vectors and collections
All Redis job queues and results
Generated result files (*.json)
Python cache files

Preserved:

Local ./models embedding/reranker caches

# Interactive confirmation (default)
just wipe

# Inline confirmation for scripts/one-liners
just wipe -y

# Wipe and relaunch production immediately
just wipe -y relaunch

Use this when you want to start completely fresh or when troubleshooting persistent issues. Pass -y to skip the interactive prompt, and relaunch to bring production back up automatically after wiping.

Development Commands

Commands for local development with hot reload.

`just dev`

Start development environment with hot reload for API.

just dev

Starts:

Redis and Qdrant containers
Celery preprocessing worker (4 concurrent)
2x Celery embedding workers (1 concurrent each)
FastAPI server with hot reload on port 8000

Prerequisites: Run just setup-dev first on fresh clone.

caution

Pressing Ctrl+C stops the API server but background workers may persist. Run just stop to clean up all processes.

`just dev-watch`

Full hot reload mode including workers.

just dev-watch

Uses watchfiles to monitor Python files and restart workers automatically when code changes. More resource-intensive than just dev but provides complete reload.

`just setup`

Install minimal production dependencies (embedding extras only).

just setup

For full development dependencies, use just setup-dev instead.

`just setup-dev`

Install full development dependencies including pytest, ruff, mypy, and pre-commit.

just setup-dev

Run this first on a fresh clone.

`just setup-models`

Create the models directory structure without installing dependencies.

just setup-models

Useful if dependencies are already installed but model directory is missing.

Code Quality Commands

Commands for linting, formatting, and type checking.

`just test [args]`

Run all tests. Automatically exports API_KEY_CLIENTS and CORS_ORIGINS from .env.

# Run all tests
just test

# Run specific test file
just test tests/parsers

# Run with verbose output
just test -v

# Run specific test
just test tests/parsers/test_pdf.py::test_parse_pdf -v

`just test-cov`

Run tests with coverage report (terminal output).

just test-cov

`just test-cov-xml`

Run tests with coverage report in XML format for CI integration.

just test-cov-xml

`just lint`

Check code with ruff linter.

just lint

`just lint-fix`

Fix auto-fixable lint issues with ruff.

just lint-fix

`just format`

Format code with ruff formatter.

just format

`just typecheck`

Run mypy type checker on the app directory.

just typecheck

`just check`

Run all code quality checks in sequence:

Format check
Lint check
Type check

just check

`just pre-commit`

Run format + lint + typecheck + fast tests (excludes slow/integration tests).

just pre-commit

Ideal for running before committing code.

Search & Retrieval Commands

Commands for testing and evaluating search functionality.

`just search "query" [-- options...]`

Run a search query from the terminal with full parameter support.

Set INFOCONNECT_API_KEY once if you do not want to pass --api-key on every command:

export INFOCONNECT_API_KEY=super-secret-key

# Basic search (concise summary)
just search "machine learning"

# Full JSON response
just search "machine learning" -- --json

# With options
just search "machine learning" -- --limit 5 --alpha 0.8

# With a simple key=value filter
just search "project management" -- --filter document_id=doc-123

# With JSON filters, including list-valued metadata filters
just search "budget report" -- --filters '{"tenant_id":"tenant-a","department":["finance","operations"]}' --json

# Enable reranking
just search "neural networks" -- --rerank --top-k-rerank 30

# Field selection (only requested top-level result fields are returned)
just search "quarterly report" -- --field document --field chunk

# Combine multiple options
just search "compliance requirements" -- --limit 10 --alpha 0.6 --rerank --min-score 0.5

Available options:

Option	Description	Example
`--limit N`	Number of results (1-100)	`--limit 20`
`--alpha 0.X`	Semantic weight 0.0-1.0	`--alpha 0.8`
`--offset N`	Pagination offset	`--offset 10`
`--filter key=value`	Simple scalar metadata filter (repeatable)	`--filter document_id=doc-1`
`--filters JSON`	Full JSON filters, including list values	`--filters '{"department":["finance","operations"]}'`
`--rerank` / `--no-rerank`	Enable/disable reranking	`--rerank`
`--top-k-rerank N`	Candidates to rerank (1-200)	`--top-k-rerank 50`
`--min-score X`	Minimum score threshold	`--min-score 0.5`
`--field NAME`	Include a top-level result field (`id`, `score`, `document`, `chunk`, `classification`, `entities`, `metadata`, `highlights`); legacy aliases like `document_id` still map to nested sections	`--field document`
`--api-base URL`	Custom API base URL	`--api-base http://api.example.com`
`--api-key KEY`	Custom API key	`--api-key my-secret-key`
`--json`	Print the full JSON response	`--json`

Supporting scripts

Most users should prefer just recipes, but a few scripts are useful for specific operational tasks:

Script	Use When
`scripts/download_models.py`	Pre-download model caches for slow, rate-limited, or offline deployments
`scripts/verify_hybrid_collection.py`	Check that the Qdrant hybrid collection can upsert and search dense/sparse vectors
`scripts/benchmark_pr_classification.py`	Measure ModernBERT classification latency and category quality against benchmark data
`scripts/generate_ndcg_toy_dataset.py`	Generate a small graded retrieval-evaluation dataset from existing Qdrant chunks
`scripts/batch_embed_resumes.py`	Legacy resume batch uploader; prefer `just embed` for new workflows

Run any script with --help before use to see required arguments and environment assumptions.

`just search-smoke`

Quick test of the search endpoint with a sample query.

just search-smoke

Sends a test query to verify the search API is working. The API must be running first (start with just prod-up or just dev).

`just eval-retrieval`

Run the retrieval evaluation harness.

just eval-retrieval

Requires a test-documents/eval-queries.json file. Creates a sample file if none exists. Runs evaluation across all retrieval modes and saves results to eval_results.json.

`just bench-run <label> <folder>`

Measure ingestion throughput for a document corpus against a running API.

just bench-run baseline test-documents/banking

Writes a benchmark JSON report named from the label, for example bench-baseline.json. Use UAT-like services rather than a hot-reload development process when collecting release evidence.

`just bench-compare <baseline> <current>`

Compare two benchmark reports and summarize throughput changes.

just bench-compare bench-baseline.json bench-current.json

Use this after a tuning change to show whether ingestion throughput improved or regressed.

Document Processing Commands

Commands for embedding documents and running demos.

`just embed <path> [-- options...]`

Embed a supported file or batch embed all supported documents from a folder recursively.

# Embed all documents in a folder
just embed my-documents

# Embed a single file
just embed ./resume-collection/resume.pdf

# Limit PDF to first N pages (useful for testing with large documents)
just embed ./resume-collection --max-pages 5

# Attach the same metadata to every uploaded document
just embed ./resume-collection --metadata '{"tenant_id":"tenant-a","department":"finance"}'

# Full example with options
just embed ./resume-collection --poll-interval 1.5

Supported file types: PDF, DOCX, PPTX, PPT, XLSX, XLS, TXT, MD, PNG, JPG, JPEG, TIF, TIFF

Options:

Option	Description	Example
`--max-pages N`	Limit PDF uploads to first N pages	`--max-pages 5`
`--poll-interval SEC`	Seconds between status polls	`--poll-interval 1.5`
`--max-wait-seconds SEC`	Max polling time per document	`--max-wait-seconds 300`
`--metadata JSON`	Metadata attached to every uploaded document	`--metadata '{"tenant_id":"tenant-a","department":"finance"}'`

Prerequisites:

Run just prod-up first to start the API and workers
The .runtime/prod.env file must exist (auto-generated by just prod-up)

What it does:

Discovers all supported documents recursively
Uploads documents concurrently (respecting API/worker capacity)
Polls for processing status on each document
Prints a summary with timing and success/failure counts

`just embed test-documents/banking [--max-pages N]`

Quick way to test the system with sample banking documents.

# Process all pages in banking documents
just embed test-documents/banking

# Limit to first 5 pages (useful for quick testing)
just embed test-documents/banking --max-pages 5

# Process first 10 pages
just embed test-documents/banking --max-pages 10

# Quick test with just 3 pages
just embed test-documents/banking --max-pages 3

Documentation Commands

Commands for building and previewing documentation.

`just docs-setup`

Install documentation dependencies (Node.js packages).

just docs-setup

`just docs-dev`

Start the documentation preview server with live reload.

just docs-dev

Opens the docs site at http://localhost:3000. Changes are reflected automatically.

`just docs-build`

Build documentation for production.

just docs-build

Creates a static site in the docs-site/build directory.

`just docs-serve`

Serve built documentation locally.

just docs-serve

Serves the built docs at http://localhost:3000.

`just docs`

Full documentation workflow: setup, build, and provide next steps.

just docs

Frontend Commands

For operator console setup, development, and checks, see the authoritative frontend/README.md.

Utility Commands

Miscellaneous helper commands.

`just help`

Display all available recipes with descriptions.

just help

Tips & Troubleshooting

Quick Diagnostics

Problem	Solution
Services not starting	Run `just status` → `just prod-down && just prod-up`
Port 8000 occupied	Run `just prod-down` or `just stop`
Model permission errors	Run `just setup` to fix models directory permissions
Workers seem stuck	Full restart: `just stop && just dev`
Want to start fresh	Run `just wipe` (or `just wipe -y` for scripts) (⚠️ clears Redis/Qdrant)

Getting Help

# List all commands
just

# Or explicitly
just help

# Show recipe descriptions
just --list --unsorted

Environment Variables

Test commands automatically export API_KEY_CLIENTS and CORS_ORIGINS from your .env file. For other commands, ensure your .env file is properly configured.

Default development authentication uses an API key to client mapping such as:

API_KEY_CLIENTS={"super-secret-key":"demo-client"}

CLI helpers such as just search, just embed, scripts/search.py, and scripts/embed_folder.py read INFOCONNECT_API_KEY when you do not pass --api-key directly:

export INFOCONNECT_API_KEY=super-secret-key

Service URLs

Once running:

API Docs: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
Qdrant Dashboard: http://localhost:6333/dashboard

What's Next

Learn about the Architecture
Try the Quick Start Guide
Read about Configuration

Quick Start​

Command Cheat Sheet​

Common Workflows​

First Time Setup​

Daily Development Loop​

Production Deployment​

Embed & Search Documents​

Code Quality Checks​

Product Version Management​

Managing Disk Space​

Starting Fresh (⚠️ Destroys Data)​

Command Reference by Activity​

System Lifecycle​

just prod-up [rebuild]​

just prod-verify-version​

just prod-down [clean]​

just prod-rebuild​

just prod-logs [service]​

just status [mode]​

just prod-smoke​

just stop [clean]​

just wipe [confirm] [relaunch]​

Development Commands​

just dev​

just dev-watch​

just setup​

just setup-dev​

just setup-models​

Code Quality Commands​

just test [args]​

just test-cov​

just test-cov-xml​

just lint​

just lint-fix​

just format​

just typecheck​

just check​

just pre-commit​

Search & Retrieval Commands​

just search "query" [-- options...]​

Supporting scripts​

just search-smoke​

just eval-retrieval​

just bench-run <label> <folder>​

just bench-compare <baseline> <current>​

Document Processing Commands​

just embed <path> [-- options...]​

just embed test-documents/banking [--max-pages N]​

Documentation Commands​

just docs-setup​

just docs-dev​

just docs-build​

just docs-serve​

just docs​

Frontend Commands​

Utility Commands​

just help​

Tips & Troubleshooting​

Quick Diagnostics​

Getting Help​

Environment Variables​

Service URLs​

What's Next​

Quick Start

Command Cheat Sheet

Common Workflows

First Time Setup

Daily Development Loop

Production Deployment

Embed & Search Documents

Code Quality Checks

Product Version Management

Managing Disk Space

Starting Fresh (⚠️ Destroys Data)

Command Reference by Activity

System Lifecycle

`just prod-up [rebuild]`

`just prod-verify-version`

`just prod-down [clean]`

`just prod-rebuild`

`just prod-logs [service]`

`just status [mode]`

`just prod-smoke`

`just stop [clean]`

`just wipe [confirm] [relaunch]`

Development Commands

`just dev`

`just dev-watch`

`just setup`

`just setup-dev`

`just setup-models`

Code Quality Commands

`just test [args]`

`just test-cov`

`just test-cov-xml`

`just lint`

`just lint-fix`

`just format`

`just typecheck`

`just check`

`just pre-commit`

Search & Retrieval Commands

`just search "query" [-- options...]`

Supporting scripts

`just search-smoke`

`just eval-retrieval`

`just bench-run <label> <folder>`

`just bench-compare <baseline> <current>`

Document Processing Commands

`just embed <path> [-- options...]`

`just embed test-documents/banking [--max-pages N]`

Documentation Commands

`just docs-setup`

`just docs-dev`

`just docs-build`

`just docs-serve`

`just docs`

Frontend Commands

Utility Commands

`just help`

Tips & Troubleshooting

Quick Diagnostics

Getting Help

Environment Variables

Service URLs

What's Next