CLI Reference — topo

Load a Turtle, JSON-LD, or N-Triples file into the local Oxigraph store and count what it contains. Projects the graph to report concepts, relationships, specializations, instances, and instance links — the same projection pipeline as the browser import (ADR-020). Charge un fichier Turtle, JSON-LD ou N-Triples dans le store Oxigraph local et compte son contenu. Projette le graphe pour rapporter concepts, relations, spécialisations, instances et liens d'instances — même pipeline de projection que l'import navigateur (ADR-020).

$ pnpm topo import si-model.ttl
Loaded 142 triples from si-model.ttl
  37 concepts, 18 relationships, 12 specializations
  41 instances, 34 instance links

Execute a SPARQL query against loaded data. Accepts a .sparql file or an inline SPARQL string. Supports SELECT, CONSTRUCT, ASK, DESCRIBE. SELECT results print as TSV (tab-separated), CONSTRUCT as N-Triples. Exécute une requête SPARQL sur les données chargées. Accepte un fichier .sparql ou une chaîne SPARQL inline. Supporte SELECT, CONSTRUCT, ASK, DESCRIBE. Résultats SELECT en TSV (tabulations), CONSTRUCT en N-Triples.

# Inline SPARQL
$ pnpm topo query "SELECT (COUNT(*) AS ?n) WHERE { ?s ?p ?o }" --data data.ttl

# From a file, over multiple data sources
$ pnpm topo query queries/01-obsolete-apps.sparql \
    --data si-model.ttl --data vocab.ttl --data shapes.ttl

Merge one or more files into the store and dump the whole graph. Output goes to stdout (the triple count goes to stderr), so the result pipes cleanly to a file. Default format is N-Quads; pass --format turtle for Turtle or --format jsonld for JSON-LD (DP-3, via jsonld.fromRDF over an N-Quads dump). Fusionne un ou plusieurs fichiers dans le store et exporte tout le graphe. La sortie va sur stdout (le compte de triples sur stderr), donc le résultat se redirige proprement vers un fichier. Format par défaut : N-Quads ; --format turtle pour Turtle ou --format jsonld pour JSON-LD (DP-3, via jsonld.fromRDF sur un dump N-Quads).

$ pnpm topo export si-model.ttl --data vocab.ttl --format turtle > merged.ttl
Loaded 160 triples

Mint a typed entity and print its generated IRI to stdout. class/property/instance use OWL types with rdfs:label; concept/scheme use SKOS with skos:prefLabel. --parent adds rdfs:subClassOf (classes) or skos:broader (concepts). Crée une entité typée et affiche son IRI généré sur stdout. class/property/instance utilisent les types OWL avec rdfs:label ; concept/scheme utilisent SKOS avec skos:prefLabel. --parent ajoute rdfs:subClassOf (classes) ou skos:broader (concepts).

$ pnpm topo create class --label "Application Server" \
    --parent urn:bra0:local:SystemComponent
urn:bra0:local:ApplicationServer
Created class "Application Server" → urn:bra0:local:ApplicationServer
  parent: urn:bra0:local:SystemComponent

Run OWL 2 RL forward-chaining inference and add the materialized triples to the store. Applies all 9 rules by default (subclass/subproperty transitivity, domain/range, inverse, symmetric, etc.); restrict with --rules. Iterates to a fixpoint. Exécute l'inférence OWL 2 RL en chaînage avant et ajoute les triples matérialisés au store. Applique les 9 règles par défaut (transitivité subclass/subproperty, domain/range, inverse, symétrique, etc.) ; restreindre avec --rules. Itère jusqu'au point fixe.

$ pnpm topo materialize ontology.ttl --data data.ttl
Loaded 142 triples from 2 file(s).

OWL 2 RL Materialization:
  Rules applied: 9
  Iterations: 3
  Triples added: 57
  Total triples: 142 → 199

SHACL validation delegated to rudof (Rust) — the only SHACL/ShEx engine in bra0, no JS validators. Exits 0 on Conforms, 1 on violations, so it gates CI. Add --details for the full violation table. Requires cargo install rudof_cli. Validation SHACL déléguée à rudof (Rust) — seul moteur SHACL/ShEx de bra0, aucun validateur JS. Sort 0 si Conforms, 1 si violations, donc intégrable en CI. --details pour la table complète des violations. Nécessite cargo install rudof_cli.

$ pnpm topo validate data.ttl --shapes shapes.ttl
Conforms

$ pnpm topo validate data.ttl --shapes shapes.ttl --details
# full violation table when it does not conform

Extract the PROV-O provenance trail (activities, entities, agents, qualified associations) via SPARQL CONSTRUCT and emit it as N-Triples. The audit backbone for traceability (P12, EU AI Act Art. 12). Extrait la chaîne de provenance PROV-O (activités, entités, agents, associations qualifiées) via SPARQL CONSTRUCT et l'émet en N-Triples. La colonne vertébrale d'audit pour la traçabilité (P12, EU AI Act Art. 12).

$ pnpm topo provenance edcc-demo.ttl
<urn:act:pemd-scan> <http://www.w3.org/ns/prov#wasAssociatedWith> <urn:agent:diagnostician> .
<urn:report:01> <http://www.w3.org/ns/prov#wasGeneratedBy> <urn:act:pemd-scan> .
24 PROV-O triples extracted

Promote a KnowledgeSpace along its lifecycle (draft → review → published). The target stage's SHACL promotion gate runs first (via rudof); on conformance the new adms:status is written and the updated graph is dumped to stdout, otherwise the blocking violations print to stderr and it exits non-zero. The current stage is inferred when --from is omitted. Promeut un KnowledgeSpace le long de son cycle de vie (draft → review → published). La porte de promotion SHACL de l'étape cible s'exécute d'abord (via rudof) ; si conforme, le nouveau adms:status est écrit et le graphe mis à jour est exporté sur stdout, sinon les violations bloquantes s'affichent sur stderr et la commande sort non-zéro. L'étape courante est inférée si --from est omis.

$ pnpm topo kspace promote ks.ttl --kspace urn:ks:demo: --to review
Promoted urn:ks:demo: draft → review

Detect knowledge gaps (Gaur taxonomy) by running a suite of diagnostic SPARQL queries: agents without capabilities, orphan capabilities, agents without policy, unscoped agents, missing labels, disconnected entities, missing provenance, unreferenced shapes, dangling collaboration URIs. Override the built-ins with --queries. Détecte les lacunes de connaissances (taxonomie Gaur) via une suite de requêtes diagnostiques : agents sans capacités, capacités orphelines, agents sans politique, agents non scopés, labels manquants, entités déconnectées, provenance manquante, shapes non référencées, URIs de collaboration pendantes. Remplacer les requêtes intégrées avec --queries.

$ pnpm topo gaps all-agents.ttl --data agent-service-contract.ttl
Q1   missing   Agents without capabilities   0
Q2   orphan    Orphan capabilities           2 gap(s)
  → urn:cap:legacy-export
  → urn:cap:adhoc-merge
Q3   missing   Agents without policy         0
...
Q9c  dangling  Dangling collaboration URIs   1 gap(s)

The Symbolic Cascade (ADR-027): materialize → analyze → validate in one pass. Stage 1 runs OWL 2 RL inference; stage 2 analyses entity types, verification status, provenance links, and gaps; stage 3 runs SHACL validation when --shapes is given. Symbolic first, validated by SHACL. La Cascade Symbolique (ADR-027) : matérialiser → analyser → valider en une passe. Étape 1 : inférence OWL 2 RL ; étape 2 : analyse des types d'entités, statut de vérification, liens de provenance et lacunes ; étape 3 : validation SHACL si --shapes est fourni. Symbolique d'abord, validé par SHACL.

$ pnpm topo cascade retroeng-data.ttl --shapes shapes.ttl
# topo cascade — Symbolic Cascade (NS-5)

## Stage 1: OWL 2 RL Materialization
  Loaded: 312 triples from 1 file(s)
  Inferred: 88 new triples (2 iteration(s))
  Total: 312 → 400

## Stage 2: Structural Analysis
  Verification status:
    Verified: 41
    Claimed: 12
    Coverage: 77% verified (41/53)

## Stage 3: SHACL Validation
  SHACL: Conforms ✓ (0 violations)

Generate token-budgeted context subgraphs for AI agents via SPARQL CONSTRUCT, with PROV-O provenance attached. Six built-in templates: class-summary, instance-detail, gap-analysis, capability-map, neighborhood (blast radius), ranked-summary (degree centrality). Override with an inline --query. Génère des sous-graphes de contexte à budget de tokens pour les agents IA via SPARQL CONSTRUCT, avec provenance PROV-O attachée. Six templates intégrés : class-summary, instance-detail, gap-analysis, capability-map, neighborhood (rayon d'impact), ranked-summary (centralité de degré). Remplacer avec un --query inline.

$ pnpm topo context --list-templates
  class-summary        All classes with labels, types, and property counts
  instance-detail      All instances with their types and properties
  gap-analysis         Classes without instances, properties without domain/range
  capability-map       EDGY capabilities, processes, and their relationships
  neighborhood         N-hop neighborhood of a seed node (blast radius)
  ranked-summary       Top entities by connectivity (degree centrality)

$ pnpm topo context si-model.ttl --template capability-map --budget 4000

Digital Perception: scan a project directory and emit Turtle describing its structure (files, formats, sizes, dates) as ArchiMate artifacts. Honours common ignores (.git, node_modules, target, dist). Turtle goes to stdout, the summary to stderr. Perception Numérique : scanne un répertoire projet et émet du Turtle décrivant sa structure (fichiers, formats, tailles, dates) comme artefacts ArchiMate. Respecte les ignores courants (.git, node_modules, target, dist). Turtle sur stdout, résumé sur stderr.

$ pnpm topo capture ./my-project --adapter generic > capture.ttl
## Capture Summary
  Directory: /path/to/my-project
  Files: 84
  Triples: ~507
  Types:
    .ts: 41 files (210.4 KB)
    .md: 18 files (62.1 KB)

Social Perception: extract EDGY entities (Person, Organisation, Capability) from markdown documents via pattern matching, each tagged re:Claimed and linked to its source via prov:wasDerivedFrom. Emits Turtle; the summary goes to stderr. Perception Sociale : extrait les entités EDGY (Person, Organisation, Capability) de documents markdown par motifs, chacune marquée re:Claimed et reliée à sa source via prov:wasDerivedFrom. Émet du Turtle ; le résumé sur stderr.

$ pnpm topo social ./interviews > social.ttl
## Social Perception Summary
  Documents scanned: 12
  Persons: 7
  Organizations: 4
  Capabilities: 9
  Total entities: 20

Continuous Reflection: confront the KnowledgeSpace with physical reality and report discrepancies. Corroborates modelled events against IoT traces (--iot), runs clinical gap analysis, and validates with SHACL (--shapes). Exits non-zero when findings remain — a PROV-O-traceable feedback loop. Réflexion Continue : confronte le KnowledgeSpace à la réalité physique et rapporte les écarts. Corrobore les événements modélisés avec les traces IoT (--iot), exécute une analyse de lacunes cliniques et valide avec SHACL (--shapes). Sort non-zéro s'il reste des constats — une boucle de rétroaction traçable en PROV-O.

$ pnpm topo reflect care-data.ttl --iot iot-traces.ttl --shapes shapes.ttl
# topo reflect — Continuous Reflection Report

## Phase 1: IoT Corroboration (TP-3 × SL)
  Encounters with IoT corroboration: 38

## Summary
  Triples analyzed: 642
  Findings: 2
  Status: 2 discrepancies — review recommended