CLI & Scripts
Installed ragspine commands and source-checkout Make/script entry points.
The ragspine console command ships in the wheel. scripts/ and the root Makefile are
development conveniences available only in a source checkout.
Installed console command
| Command | Purpose |
|---|---|
ragspine quickstart | deterministic offline demonstration |
ragspine ask --db PATH "question" | one question through the mock/offline path |
ragspine version | installed distribution version |
ragspine dify analyze FILE | parse and statically analyze a Dify workflow; no code generation or execution |
ragspine dify compile FILE | compile Dify workflow configuration to Python source; does not execute it |
ragspine workflow list | list bundled template metadata |
ragspine workflow show ID --format yaml|json | print one bundled workflow |
ragspine workflow preview ID | emit the versioned display-only graph projection |
ragspine workflow create DESCRIPTION | match a template or generate a base Dify 0.6 workflow |
This shorthand is equivalent to workflow create:
ragspine "A RAG form-understanding paper workflow using CNN"Workflow-create options
| Option | Meaning |
|---|---|
--template ID | select an exact catalog template and skip matching |
--no-reuse | always generate the fixed base workflow |
--matcher lexical|auto|onnx | choose deterministic lexical matching, automatic ONNX/fallback, or required ONNX |
--format yaml|json | serialized output format; default YAML |
-o, --output PATH | output path |
--stdout | write only the workflow document to standard output |
--force | replace an existing normal file; links and special files remain forbidden |
The ONNX matcher requires [embed-onnx]; first use may download and cache its model. auto
falls back to lexical matching when ONNX is unavailable, while explicit onnx reports an error.
dify compile and dify analyze accept .json, .yaml, .yml, and .toml paths. Parsing
normalizes them to a JSON-compatible mapping before Dify validation. Compilation generates code;
only the separately gated service run endpoint executes compiled output.
Source-checkout Make targets
Run all of these from the repository root.
| Target | Purpose |
|---|---|
make venv | create .venv with uv |
make install | editable [dev,service,vector] install |
make install-all | editable [dev,service,vector,llm,embed] install; not identical to [all] |
make test | pytest excluding GPU/network tests |
make ci | blocking eight-stage documentation, typing, lint, test, QA, and demo gate |
make lint | informational scripts/lint.sh; the CI gate invokes strict mypy and ruff separately |
make fmt | ruff fixes and formatting |
make drift | documentation-to-code drift check |
make demo, make ask Q="…" | deterministic demo and single question |
make eval-qa, make eval-retrieval | QA and retrieval evaluation |
make serve, make worker | FastAPI server and Redis-backed RQ worker |
make build, make publish-test, make publish | build and Twine upload workflow |
The local CI script is the authoritative gate. The eight stages are documentation-reference
integrity, documentation drift, mypy --strict, ruff, the normal test suite, isolated Docling
tests, QA ratchets in tool and agent modes, and the demo smoke test.
Important scripts
scripts/ask.py: one-shot question interface.--provider mockis deterministic; the real Anthropic adapter requires[llm]and credentials. The project author cannot access the Anthropic API, so that provider path has not received the same hands-on integration coverage.scripts/run_demo.py: fully offline fixture-to-answer smoke test.scripts/run_server.py: uvicorn launcher with--hostand--port.scripts/run_worker.py: RQ consumer;--queuedefaults toragspine-ingest.scripts/topology.py: exports static engine topology as Mermaid, DOT, or JSON.
There are intentionally no ragspine serve, ragspine worker, or ragspine topology console
subcommands at present; those remain source-checkout scripts.