The SCRP cluster provides a list of CLI tools to SCRP-Assistant, its built-in AI assistant. This page describes each one and lists its command-line options.

Websearch

Vision Understanding

PDF Processing

Image Generation

For a head-to-head comparison of the PDF processing tools’ speed and output quality, see the comparison report.

websearch

A web search client. websearch runs a query through Brave and returns a list of results. Use it to look up documentation, packages, or current information that is not already in your context.

Usage:

websearch [options] <query>

Examples:

# Simple search
websearch "pandas read_csv dtype specification"

# More results, as JSON for programmatic use
websearch "slurm gpu partition" -n 20 --json

Options:

Option Description
query (Positional) Search query.
-n COUNT, --count COUNT Number of results (1–50). Default 10.
--server SERVER Server URL (default https://websearch.econ.cuhk.edu.hk, or env SCRP_WEBSEARCH_SERVER).
--json Print raw JSON response instead of formatted text.
--health Check server health and exit.
--show-key Print the resolved API key (for debugging) and exit.
-h, --help Show help.

Accessing the server from off-cluster (within the department)

The server is reachable at https://websearch.econ.cuhk.edu.hk from anywhere on the department network (it is not accessible outside the department) with your SCRP-Chat API key.

Set it once:

export SCRP_CHAT_KEY="sk-..."   # your SCRP-Chat API key
BASE="https://websearch.econ.cuhk.edu.hk"
curl
# Search (POST /search, bearer token)
curl -sS -X POST "$BASE/search" \
  -H "Authorization: Bearer $SCRP_CHAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest inflation report", "count": 5}' | jq

# Check your remaining quota (GET /quota, non-consuming)
curl -sS "$BASE/quota" -H "Authorization: Bearer $SCRP_CHAT_KEY" | jq

# Health check (no auth needed)
curl -sS "$BASE/health"

A rate-limited request returns HTTP 429 with retry_in_seconds, limit, window_seconds, group; a bad key returns 401. curl’s -sS stays quiet on success but still shows errors.

Python
import os, requests

BASE = "https://websearch.econ.cuhk.edu.hk"
headers = {"Authorization": f"Bearer {os.environ['SCRP_CHAT_KEY']}"}

# Search
r = requests.post(
    f"{BASE}/search",
    headers=headers,
    json={"query": "latest inflation report", "count": 5},
    timeout=60,
)
if r.status_code == 429:
    b = r.json()
    raise SystemExit(f"rate limited; retry in {b.get('retry_in_seconds')}s")
r.raise_for_status()
for item in r.json()["results"]:
    print(item["title"], "-", item["url"])

# Remaining quota (non-consuming)
q = requests.get(f"{BASE}/quota", headers=headers, timeout=60).json()
print(q["rate_limit"])  # {group, limit, window_seconds, remaining, ...}

For interactive use on the cluster itself, scrp-websearch "query" does all of this for you; the examples above are for scripts/notebooks running off-cluster but inside the department.

scrp-vision

A remote vision model. scrp-vision sends up to three images (file paths, URLs, PDFs, or base64 strings) to a vision API and returns a natural-language answer to your prompt. It is the only tool on the cluster that actually reads charts (chart type, axes, takeaways) and, with a “transcribe verbatim” prompt, the only one that recovers display equations as LaTeX.

Large PDFs must be split into ≤8-page chunks first.

Usage:

scrp-vision [prompt] <image> [<image> <image>] [options]

Examples:

# Describe a single image
scrp-vision "Describe this chart" figure.png

# Compare two images
scrp-vision "What's the difference?" a.png b.png

# Transcribe a PDF (chunk large PDFs first)
scrp-vision "Transcribe these pages verbatim, including equations as LaTeX" chunk.pdf

Options:

Option Description
prompt (Positional, optional) Text prompt for the model; defaults to a context-aware prompt.
images (Positional) 1–3 image file paths, URLs, PDFs, or base64-encoded strings.
--model <MODEL>, -m Vision model to use (default from SCRP_VISION_MODEL/OPENAI_VISION_MODEL, config, or vision).
--base-url <URL>, -b API base URL (default from SCRP_BASE_URL/OPENAI_BASE_URL, config, or the SCRP chat API).
--thinking Enable thinking mode (disabled by default).
--max-pages <N> Maximum number of PDF pages to process (unlimited if omitted).
-h, --help Show help.

docling

A layout-aware document converter. docling runs layout, table-structure, and (optionally) OCR models to produce clean, reading-order Markdown with properly reconstructed tables and inline base64 figure images. Run it on the GPU partition via the gpu docling wrapper for roughly 2× the speed of a CPU run. On a born-digital PDF with a clean text layer, OCR is usually unnecessary; display equations are dropped as <!-- formula-not-decoded --> placeholders.

Usage:

gpu docling convert [options] <PDF-file>
# the older `docling <file>` form is also accepted

Examples:

# Fast path: Markdown without OCR (recommended for born-digital PDFs)
gpu docling convert --to md --output out/ --no-ocr paper.pdf

# With OCR (for scanned/image PDFs)
gpu docling convert --to md --output out/ --ocr paper.pdf

Options (docling convert):

Option Description
--from <TEXT> Input formats to accept.
--to [md\|json\|yaml\|html\|...] Output format(s).
--output <PATH> Output directory.
--ocr / --no-ocr Enable/disable OCR of bitmap regions.
--force-ocr / --no-force-ocr (Deprecated) replace existing text with full-page OCR.
--ocr-mode [full_page\|layout_regions] Which document regions to OCR.
--ocr-engine <TEXT> OCR engine to use (e.g. rapidocr, tesseract).
--ocr-lang <TEXT> OCR language(s).
--tables / --no-tables Enable the table-structure model.
--table-mode [fast\|accurate] Table-extraction mode.
--image-export-mode [placeholder\|embedded\|referenced] How images appear in the output.
--enrich-formula / --no-enrich-formula Enable formula enrichment (LaTeX).
--enrich-code / --no-enrich-code Enable code enrichment.
--enrich-picture-classification / --no-... Enable picture classification.
--enrich-picture-description / --no-... Enable picture description.
--enrich-chart-extraction / --no-... Enable chart-data extraction.
--pipeline [legacy\|standard\|vlm\|...] Choose the processing pipeline.
--vlm-model <TEXT> VLM preset to use with the vlm pipeline.
--pdf-backend [pypdfium2\|docling_page\|...] PDF backend.
--pdf-password <TEXT> Password for protected PDFs.
--artifacts-path <PATH> Location of model artifacts.
--device [auto\|cpu\|cuda\|mps\|...] Accelerator device.
--num-threads <INT> Number of threads.
--page-batch-size <INT> Number of pages processed per batch.
--document-timeout <FLOAT> Per-document timeout.
--abort-on-error / --no-abort-on-error Abort on first error.
--verbose / -v Increase verbosity.
--quiet / -q Suppress per-file progress.
--version Show version.
--help Show help.

pdftotext

The fastest option. pdftotext is a local Poppler binary that reads the PDF’s embedded text layer and writes it to a plain-text file. It loads no model and runs anywhere, but it cannot interpret figures or table structure, and on manuscript drafts it leaves margin line-number artifacts in the output.

Usage:

pdftotext [options] <PDF-file> [<text-file>]

Example:

pdftotext -layout paper.pdf paper.txt

Options:

Option Description
-f <int> First page to convert.
-l <int> Last page to convert.
-r <fp> Resolution, in DPI (default 72).
-x <int> x-coordinate of the crop area top-left corner.
-y <int> y-coordinate of the crop area top-left corner.
-W <int> Width of crop area in pixels (default 0).
-H <int> Height of crop area in pixels (default 0).
-layout Maintain original physical layout.
-fixed <fp> Assume fixed-pitch (tabular) text.
-raw Keep strings in content stream order.
-nodiag Discard diagonal text.
-htmlmeta Generate a simple HTML file, including meta information.
-enc <string> Output text encoding name.
-listenc List available encodings.
-eol <string> Output end-of-line convention (unix, dos, or mac).
-nopgbrk Don’t insert page breaks between pages.
-bbox Output bounding box for each word and page size to HTML (sets -htmlmeta).
-bbox-layout Like -bbox but with extra layout bounding-box data (sets -htmlmeta).
-cropbox Use the crop box rather than the media box.
-opw <string> Owner password (for encrypted files).
-upw <string> User password (for encrypted files).
-q Don’t print any messages or errors.
-v Print copyright and version info.
-h, -help, --help, -? Print usage information.

scrp-image

An image generation and editing client. scrp-image sends a text prompt to a ComfyUI server and saves the resulting image to the current directory (or a path you specify). Give an optional input image to edit it instead of generating from scratch.

Usage:

scrp-image [options] <prompt> [<image>]

Examples:

# Generate an image
scrp-image "A watercolor of Victoria Harbour at sunset"

# Edit an existing image
scrp-image "Make it night, add neon reflections" input.png

# Generate at a custom size, saved to a specific path
scrp-image "scatter plot, blue points" --width 1024 --height 768 --save-path out/plot.png

Options:

Option Description
prompt (Positional) Text prompt for generation or editing (not required in test mode).
image (Positional, optional) Image file path, URL, or base64 for editing.
--host HOST Server address as {address}:{port} (default localhost:8100).
--height HEIGHT Height of the output image (default 512).
--width WIDTH, -w WIDTH Width of the output image (default 512).
--url Return the URL instead of downloading the image.
--save-path SAVE_PATH Path to save the downloaded image (default: current directory).
--no-delete Do not delete the image from the server after downloading.
--test Test connection to the server without generating an image.
--test-comfyui Test the server’s connection to ComfyUI.
--verbose, -v Print verbose debug information.
-h, --help Show help.