CLI Command Reference¶
The syntax shown here matches the executable QLens 3.1 CLI.
Global help and version¶
qlens --help
qlens --version
qlens doctor¶
Run repository diagnostics.
qlens doctor
qlens doctor --root /path/to/repository
Use this first when a build or validation command fails.
qlens repo validate¶
Validate the complete canonical repository, graph references, lifecycle metadata, and reasoning integrity.
qlens repo validate
qlens repo validate --root /path/to/repository
Exit code 0 means success. Exit code 1 means validation failed.
qlens validate PATH¶
Validate one canonical YAML object against repository rules and its JSON Schema.
qlens validate repository/objects/evidence/evd-000001.yml
qlens validate ../another-repo/repository/objects/questions/qst-000004.yml --root ../another-repo
qlens oid PREFIX NUMBER¶
Format an OID.
qlens oid EVD 12
Output:
EVD-000012
qlens new TYPE TITLE¶
Create a canonical object.
qlens new question "What does this evidence establish?" --space RSP-000001
qlens new evidence "Primary source observation" --space RSP-000001
qlens new reasoning "Reasoning from EVD-000001" --space RSP-000001
qlens new explanatory_model "Possible explanation" --space RSP-000001
qlens new current_understanding "Current working understanding" --space RSP-000001
See supported type names:
qlens new --help
When --space is omitted, object creation follows repository defaults. Explicit space membership is recommended.
qlens list¶
List canonical records.
qlens list
qlens list --type evidence
qlens list --status active
qlens list --space RSP-000001
qlens list --type question --status active --space RSP-000001
qlens show OID¶
Show one object.
qlens show EVD-000001
qlens show EVD-000001 --json
YAML is the default human-readable output. JSON is useful for scripts.
qlens search TEXT¶
Perform case-insensitive full-record text search.
qlens search "reality"
qlens search "RSP-000001"
This is a simple repository text search, not semantic AI search.
qlens query EXPRESSION¶
Run deterministic structural queries.
qlens query "type=evidence"
qlens query "space=RSP-000001 and status=active"
qlens query "type=reasoning and space=RSP-000001" --limit 20
qlens query "tag=foundation" --json
Supported indexed fields include oid, type, status, space, tag, version, path, created, and updated. Expressions use equality filters joined by and.
Examples:
qlens query "oid=QST-000001"
qlens query "version=1"
qlens query "path=repository/objects/questions/qst-000001.yml"
qlens transition OID STATUS¶
Move an object through an allowed lifecycle transition.
qlens transition QST-000001 collecting --note "Evidence collection started"
qlens transition QST-000001 review --note "Ready for review"
QLens rejects invalid transitions and records valid transitions in history.
Inspect allowed status names and transitions in the lifecycle specification before changing canonical records.
qlens graph OID¶
Inspect the graph neighborhood around an object.
qlens graph RSN-000001
qlens graph RSN-000001 --depth 2
The command returns JSON with graph nodes and edges reachable within the requested depth, including reverse traversal where available.
qlens index¶
Rebuild disposable indexes.
qlens index
The command prints object counts. Index files are stored under repository/indexes/.
qlens registry¶
Build or check the deterministic registry.
qlens registry
qlens registry --check
Use --check in CI to detect stale registry files without modifying them.
qlens render¶
Regenerate NUR workspace Markdown views.
qlens render
Generated views are written under docs/workspace/ and remain noncanonical.
qlens build¶
Run the normal synchronization pipeline.
qlens build
Equivalent high-level sequence:
- validate canonical objects and relationships;
- rebuild indexes;
- rebuild the deterministic registry;
- render NUR views.
qlens propose TITLE PATCH¶
Stage a noncanonical proposal for human review.
qlens propose \
"Suggested relationship" \
"add RSN-000001 supports EVD-000001"
A proposal does not modify canonical objects or graph relationships.
qlens plugins¶
Discover installed QLens plugins.
qlens plugins
qlens plugins --json
An empty result is valid when no plugins are installed.
qlens pack OUTPUT¶
Create a portable knowledge package.
qlens pack dist/all-research.zip
qlens pack dist/foundation-space.zip --space RSP-000001
qlens pack dist/two-spaces.zip --space RSP-000001 --space RSP-000002
qlens pack dist/with-history.zip --space RSP-000001 --include-history
The package includes selected canonical objects, schemas, a manifest, and integrity information. It does not replace the full Git repository.
Root selection¶
Most repository commands accept --root:
qlens doctor --root ../qlens-project
qlens query "type=evidence" --root ../qlens-project
qlens build --root ../qlens-project
QLens 5 platform commands¶
Research Query Language¶
qlens rql 'FIND evidence WHERE status = verified RETURN oid,title,status' --json
qlens rql 'FROM RSP-000001 FIND reasoning FOLLOW outgoing DEPTH 2 RETURN oid,type,title'
Immutable events¶
qlens events list
qlens events list --oid QST-000001
qlens events verify
qlens events replay --oid QST-000001
Research workflows¶
qlens workflow start --title "Foundation research" --space RSP-000001
qlens workflow list
qlens workflow show WFL-1234ABCD
qlens workflow advance WFL-1234ABCD --object QST-000001
Import¶
qlens import notes.md --type observation --space RSP-000001
qlens import evidence.json --type evidence --space RSP-000001