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-rebuild`	Rebuild images, start, key Console, smoke	Tagged deploys and infra changes
🟡 Common	`just failed-tasks`	List individual failed background tasks	Triage after a failed ingest or update
Essential	`just prod-ui-up`	Recreate Console with a validated API key	When the Console proxy is unconfigured or its key rotated
🔴 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 nightly-issue-203`	Run isolated four-store recovery acceptance	Publication cutover evidence
🟢 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

Copy .env.example to .env before just prod-up or any authenticated API call. Empty API_KEY_CLIENTS fails closed: every authenticated request returns 401 until you set keys.

cp .env.example .env    # Required. Empty API_KEY_CLIENTS fails closed (401)
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

Tagged staging/production deploys pin a Git tag, then run just prod-rebuild, which resolves the Console key and gates on readiness. See Production and Staging Deploy and Recovery.

# Tagged release (API + workers + Console readiness)
git fetch --tags
git checkout <release-tag>
just prod-rebuild

# First deploy or after infrastructure changes (no tag pin)
just prod-up rebuild    # Build images and start
just prod-ui-up         # Recreate Console with the validated effective key
just prod-smoke         # Verify images and the deployed API version

# Resolve the effective console key only (prints the key to stdout):
just prod-console-key    # fails before any Compose mutation on missing/invalid key
just prod-ui-check       # bounded /api/ready wait + authenticated read (also gates prod-up/prod-ui-up/prod-smoke)
just status             # Confirm all services healthy

# Subsequent starts (API image built for guard; other images may be cached)
just prod-up
just prod-ui-up
just status

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" -- --scope Content

Search scope and options:

# Full Content Evidence Result JSON
just search "machine learning" -- --scope Content --json

# Metadata and Both are explicit opt-ins
just search "Apollo" -- --scope Metadata --json
just search "project management" -- --scope Both --json

# Exact filters and reranking
just search "compliance" -- --scope Content --limit 10 --alpha 0.6 \
  --rerank --filter document_id=doc-123

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

Every just search request carries an explicit scope; Content is the default and every scope requires active publication authority. Metadata/Both additionally require a ready Client. Exact filters constrain the candidate set without affecting rank. Search output is one Evidence Result language: rows are Document Versions with nested document_version, canonical_metadata, lane-local retrieval_contributions, and bounded Content/Metadata Evidence Sets.

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.

Build first, then recreate: just prod-up rebuild runs just prod-build (every image: API, both embedding workers, preprocessing, models, and Console) before it creates, stops, or recreates any container, so a failed build aborts with the running stack untouched and the outage window is only stop-swap-start. The whole-stack compose up -d is called with --force-recreate and no --build: containers are recreated, never merely restarted, which is also what applies the json-file log-rotation options. A bare just prod-up skips the pre-build (it still rebuilds the API image for the worker-guard check) and reuses the existing worker images.

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. Stderr prints Celery worker revision conflict detected before startup. plus Expected deployment revision: and Offending worker node(s): (no exception class name). Recover with just prod-down (data preserved), then retry — not just prod-down clean or just wipe. See Celery worker revision conflict recovery and Worker and Performance Settings.

The check runs in a one-shot API container with the workers' authenticated broker settings. prod-up builds that image before checking, uses the Compose network rather than host DNS, publishes no service ports, and starts no dependencies for the check. DNS, unreachable-broker, authentication, and authorization failures have separate diagnostics and all block startup. prod-up resolves and injects the Console key before Compose changes state, then gates success with prod-ui-check.

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: http://localhost:8000
Swagger UI (/docs) and ReDoc (/redoc): only when DEBUG=true (code/Compose default is false)
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. Recovery from Celery worker revision conflict detected before startup. uses just prod-down without clean so qdrant_data and redis_data survive. See Production and Staging Deploy and Recovery.

`just prod-rebuild`

Rebuild images, start production with a keyed Console, and smoke. Runs just prod-up rebuild, just prod-ui-up, then just prod-smoke (prod-up resolves the Console key and runs prod-ui-check itself).

just prod-rebuild

Useful after code changes to ensure fresh images: just prod-build runs first, before any container is created, stopped, or recreated, so the outage window is only stop-swap-start and a failed build leaves the running stack untouched. It resolves the operators Console key before Compose mutation and gates smoke on /api/ready plus an authenticated read. A missing or rejected key fails the rebuild. See Production and Staging Deploy and Recovery.

`just prod-build`

Build every production image — API, both embedding workers, preprocessing, models, and the operators Console — without touching a single container.

just prod-build

prod-up rebuild and prod-rebuild call it before their first Compose mutation, which is what keeps image builds out of the outage window (issue #531). It sources .runtime/prod.env (running just prod-runtime-plan first when missing) and passes a placeholder Console key purely to satisfy the Console overlay's interpolation guard; nothing is started. Run it on its own to warm the image cache before a maintenance window.

`just prod-ui-up`

Build and launch (or recreate) only the operators Console.

just prod-ui-up

Requires a running production API and a configured key in API_KEY_CLIENTS. Resolves the effective key (an explicit INFOCONNECT_API_KEY is used only when configured), injects it as INFOCONNECT_API_KEY, and recreates console (--build --no-deps). The Console is operators-only at http://127.0.0.1:3000: it binds loopback by default (CONSOLE_PUBLISH_ADDR=0.0.0.0 opts in to LAN), and starting it without a key fails closed. Reach remote hosts through an SSH tunnel — see Console access.

Confirm the proxy, not just the HTML shell:

curl -fsS http://127.0.0.1:3000/api/ready

`just prod-ui-down`

Stop and remove only the operators Console. API, workers, Redis, and Qdrant stay up.

just prod-ui-down

`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 failed-tasks [options]`

List individual failed background tasks from the worker-maintained failure log: failure time, task id (the API job_id for client jobs), Celery task name, Client, document/version, and error.

just failed-tasks                                  # newest first
just failed-tasks --limit 50 --client <client-id>  # bound and filter
just failed-tasks --json                           # machine-readable

GET /metrics counts failures per task name; this lookup names the individual failures, which the celery Redis ACL user cannot get by scanning celery-task-meta-* (scans stay denied). Run it on the deployment host, or point --redis-url at the broker. The log keeps the most recent 200 entries. See Failed background tasks.

`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 nightly-issue-203`

Run the issue #203 four-store publication and recovery acceptance suite in a unique Compose project. The harness allocates non-shared host ports and tears down only its own Redis and Qdrant containers. CircleCI runs it nightly on main and on every v* release tag; the issue #108 corpus is not part of this recipe because the GitHub test job already runs it on every PR.

just nightly-issue-203

`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 client-scoped search query from the terminal. Every request includes an explicit --scope; Content is the default, while Metadata and Both are opt-in and additionally require Discovery Readiness for the Client. Every scope requires active publication authority.

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 Content search (concise Evidence Result summary)
just search "machine learning" -- --scope Content

# Full nested Evidence Result JSON
just search "machine learning" -- --scope Content --json

# Metadata and Both opt-in scopes
just search "Apollo" -- --scope Metadata --json
just search "project management" -- --scope Both --json

# Exact filter and reranking
just search "project management" -- --scope Content \
  --filter document_id=doc-123 --rerank

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

Available options:

Option	Description	Example
`--scope SCOPE`	`Content` (default), `Metadata`, or `Both`	`--scope Content`
`--limit N`	Number of Evidence Results (1-100)	`--limit 20`
`--alpha 0.X`	Dense/semantic weight 0.0-1.0	`--alpha 0.8`
`--offset N`	Document Version pagination offset	`--offset 10`
`--filter key=value`	Exact scalar filter (repeatable)	`--filter document_id=doc-1`
`--filters JSON`	Exact filters, including list values	`--filters '{"metadata.custom.department":["finance","operations"]}'`
`--rerank` / `--no-rerank`	Enable/disable Content reranking	`--rerank`
`--top-k-rerank N`	Requested Content rerank prefix (1-200 accepted); see the API clamp contract	`--top-k-rerank 50`
`--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 complete nested API response	`--json`

The concise view renders a Document Version's rank, identity, lane-local retrieval_contributions, and bounded Content/Metadata Evidence Sets. --json preserves nested objects and arrays, including each Evidence Set's items, total, and truncated values and all pagination metadata. Filters constrain candidates but do not affect rank.

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/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 with explicit scope: "Content" 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`
Console HTML loads, API views fail	Run `just prod-ui-up`, then inspect `/api/ready`. See FAQ
`.env` change ignored	Do not `docker compose restart`; run `just prod-up` / `just prod-ui-up`. See FAQ
`Celery worker revision conflict detected before startup.`	`just prod-down` (not `clean`/`wipe`), then `just prod-rebuild`. See FAQ
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: http://localhost:8000
Swagger UI / ReDoc: http://localhost:8000/docs and /redoc only when DEBUG=true (not on by default after just prod-up)
Qdrant Dashboard: http://localhost:6333/dashboard

What's Next

Learn about the Architecture
Try the Quick Start Guide
Read about Configuration
Follow Production and Staging Deploy and Recovery for tagged deploys
See Troubleshooting and FAQ for Console key, .env recreate, and worker-revision failures

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-build​

just prod-ui-up​

just prod-ui-down​

just prod-logs [service]​

just status [mode]​

just failed-tasks [options]​

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 nightly-issue-203​

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-build`

`just prod-ui-up`

`just prod-ui-down`

`just prod-logs [service]`

`just status [mode]`

`just failed-tasks [options]`

`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 nightly-issue-203`

`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