@ontologie/cli

dataforge -- SDK CLI for the Ontologie Platform Project scaffolding, type generation, login, and context engineering for AI agents. Also available as ontologie (alias).

Pourquoi un CLI en plus des APIs et MCP ?

Le CLI appelle le meme backend que l'API REST — il n'est pas "plus rapide". Sa valeur est ailleurs :

• Moins de friction : 1 commande = aggregation multi-source (ontologie + knowledge + graphe). Remplace 3+ appels API sequentiels.
• Composabilite shell : pipes, jq, scripts — ontologie nodes search "X" --ids-only | ontologie graph neighbors --stdin
• Integration pipeline agent : stdout alimente directement les prompts LLM — ontologie context pack "sujet" --format markdown | claude
• Simplicite E2E : ontologie context pack compile un context pack complet en une seule invocation

Cas d'usage :

• Pre-prompt context injection (ontologie context pack "sujet" | claude)
• Scripts d'automatisation batch
• CI/CD (validation schemas, health checks)
• Composition Unix : ontologie nodes search "X" --ids-only | ontologie graph neighbors --stdin

Installation

# Depuis le monorepo SDK
pnpm install
pnpm --filter @ontologie/cli build

# Link global
cd packages/cli && npm link

# Verification
dataforge --version   # -> 3.4.0
dataforge --help

Migration : Les binaires ontologie et df restent disponibles comme alias mais affichent un avertissement de deprecation. Utilisez dataforge pour tous les nouveaux projets.

Configuration

Ordre de resolution

CLI flags (--api-key, --workspace)
  |-> Variables d'environnement (ONTOLOGIE_API_KEY, ONTOLOGIE_WORKSPACE_ID)
       |-> Variables legacy (DF_API_KEY, DF_WORKSPACE_ID) -- deprecated
            |-> Fichier ~/.ontologierc (YAML, multi-profil)
                 |-> Fichier ~/.dfrc (deprecated)
                      |-> Defaut (api.dataforge.io)

Fichier ~/.ontologierc

default:
  api_url: https://api.dataforge.io
  workspace_id: <uuid>
  api_key: df_...

staging:
  api_url: https://api.dev-growthsystemes.com
  workspace_id: <uuid>
  api_key: df_...

Migration : Si vous aviez un ~/.dfrc, lancez ontologie config migrate pour le copier vers ~/.ontologierc.

Variables d'environnement

| Variable | Description | Legacy (deprecated) | |----------|-------------|---------------------| | ONTOLOGIE_API_URL | URL de base de l'API | DF_API_URL | | ONTOLOGIE_API_KEY | Cle API (prefixe df_) | DF_API_KEY | | ONTOLOGIE_WORKSPACE_ID | UUID du workspace | DF_WORKSPACE_ID | | ONTOLOGIE_SPACE_ID | UUID de l'espace (optionnel) | DF_ESPACE_ID | | ONTOLOGIE_PROFILE | Nom du profil ~/.ontologierc | DF_PROFILE |

Commandes

ontologie context pack <query> -- Killer Feature

Assemble un context pack LLM-ready avec budget tokens, en une seule requete.

# Basique
ontologie context pack "politique RGPD"

# Avec budget et profondeur custom
ontologie context pack "gestion clients" --budget 4000 --depth 1

# Sections specifiques
ontologie context pack "pipeline ETL" --include ontology,knowledge

# Format agent-optimized (Markdown)
ontologie context pack "architecture microservices" --format markdown

# JSON pour pipeline
ontologie context pack "analyse RH" --format json | jq '.sections.knowledge.results'

Options :

| Option | Default | Description | |--------|---------|-------------| | --budget <tokens> | 8000 | Budget tokens total | | --depth <n> | 2 | Profondeur traversee graphe (1-3) | | --include <sections> | ontology,knowledge,graph | Sections a inclure |

Budget allocation :

• Ontology : 20% -- resume contextuel de l'ontologie
• Knowledge : 40% -- resultats hybrid search (vector + lexical + graph)
• Graph : 30% -- voisins graphe des entites trouvees
• Reserve : 10% -- metadata, headers

Backend : POST /api/v1/context/pack | Feature flag : FEATURE_CONTEXT_PACK | Auth : API key (no RBAC scope required)

ontologie nodes -- Operations ontologie

# Lister les noeuds
ontologie nodes list
ontologie nodes list --type ObjectType --status active
ontologie nodes list --ids-only                         # IDs seulement (pipe-friendly)
ontologie nodes list --all                              # Auto-pagination

# Recuperer un noeud
ontologie nodes get <uuid>

# Recherche hybride
ontologie nodes search "Client"
ontologie nodes search "employe RH" --types ObjectType --explain
ontologie nodes search "facturation" --ids-only | ontologie graph neighbors --stdin

ontologie knowledge search -- Knowledge Library

ontologie knowledge search "politique de securite"
ontologie knowledge search "RGPD conformite" --limit 5
ontologie knowledge list
ontologie knowledge get <id>

dataforge query <type> -- Query instances

# Basique
dataforge query Contract --limit 20
dataforge query Contract --where status=active --order-by created_at --order desc

# Filtre JSON avance
dataforge query Invoice --filter-json '{"status":"pending","amount_gt":1000}'

# Estimation de cout (sans executer)
dataforge query Contract --explain-cost --format json

# IDs ou count seuls
dataforge query Contract --ids-only
dataforge query Contract --count

Options :

| Option | Default | Description | |--------|---------|-------------| | --filter-json <json> | — | JSON filter expression | | --where <expr> | — | Simple key=value filter | | --order-by <field> | — | Sort field | | --order <dir> | asc | Sort direction: asc|desc | | --select <fields> | — | Comma-separated field list | | --ids-only | — | Output only IDs | | --count | — | Return only count | | --cursor <cursor> | — | Pagination cursor | | --explain-cost | — | Show estimated cost without executing |

Limit: Max --limit is 10,000. Use --cursor for larger datasets.

dataforge search <query> -- Search entities

dataforge search "Acme" --types Company,Contract --limit 20
dataforge search "facturation" --mode deterministic --explain
dataforge search "Client" --ids-only

Options :

| Option | Default | Description | |--------|---------|-------------| | --types <types> | — | Comma-separated entity types | | --limit <n> | 10 | Max results | | --explain | — | Include score breakdown | | --ids-only | — | Output only IDs | | --mode <mode> | auto | Search mode: auto or deterministic (exact/fuzzy only, no semantic) |

ontologie graph -- Traversee graphe

# Voisins directs (depth capped at 3)
ontologie graph neighbors <node-id>
ontologie graph neighbors <node-id> --depth 2 --direction outbound
ontologie graph neighbors <node-id> --edge-types "manages,owns" --ids-only

# N-hop traversal (depth capped at 5)
ontologie graph traverse <node-id> --depth 3 --direction outbound

# Shortest path (max-hops capped at 10)
ontologie graph path <from> <to> --max-hops 5

# Pipe composition
ontologie nodes search "Client" --ids-only | ontologie graph neighbors --stdin --depth 2

Depth limits (V1 stable) :

| Subcommand | Max depth | Default | |------------|-----------|---------| | neighbors | 3 | 1 | | traverse | 5 | 2 | | path (max-hops) | 10 | 5 |

dataforge schema -- Schema operations

# Export full schema (raw JSON/YAML dump)
dataforge schema export
dataforge schema export --format yaml

# Compare local dataforge.schema.ts vs remote ontology
dataforge schema diff
dataforge schema diff --schema ./custom-schema.ts

# Push local schema changes to remote
dataforge schema push --dry-run          # preview plan
dataforge schema push --yes              # apply changes

# Generate dataforge.schema.ts from remote ontology
dataforge schema pull
dataforge schema pull --output ./src/schema.ts

# Compile schema + verify lockfile integrity
dataforge schema check

Schema workflow :

dataforge init         ->  Edit dataforge.schema.ts  ->  dataforge schema diff
                                                          |
                                              dataforge schema push --yes
                                                          |
                                              dataforge generate

ontologie whoami -- Connection info

ontologie whoami
# -> Workspace: xxx | API: https://api... | Health: OK

ontologie doctor -- Diagnostics

ontologie doctor
# Checks: config, rc file, env vars, API connectivity, cache, Node.js version

ontologie config -- Configuration

ontologie config list
# -> Affiche la config resolue (profil, URL, workspace, key masquee)

ontologie config set api_key df_xxx
ontologie config get workspace_id
ontologie config migrate           # ~/.dfrc -> ~/.ontologierc

Options globales

| Flag | Description | |------|-------------| | -w, --workspace <id> | Override workspace ID | | -s, --space <id> | Override space ID | | --api-url <url> | Override API URL | | --api-key <key> | Override API key | | --profile <name> | Profil ~/.ontologierc (defaut: "default") | | -f, --format <fmt> | Format: json, table, csv, yaml, markdown, jsonl, raw | | --raw | Alias pour --format raw (sans envelope _meta) | | -n, --limit <n> | Nombre max de resultats | | -q, --quiet | Supprimer les diagnostics stderr | | -v, --verbose | Diagnostics detailles sur stderr | | --no-cache | Bypass cache local | | --cache <ttl> | TTL cache (ex: 60s, 5m, 1h) | | --keychain | Force keychain credential resolution |

Formats de sortie

| Format | Usage | Destination | |--------|-------|-------------| | json | Default (pipe) | Machine, jq, scripts | | table | Default (TTY) | Humain, terminal | | markdown | Agent-optimized | LLM, context injection | | csv | Import | Tableurs, analyse | | yaml | Config | Documentation, IaC | | jsonl | Streaming | Logs, traitement ligne par ligne | | raw | Sans envelope | Quand _meta n'est pas voulu |

--format plain est un alias de --format markdown pour la retrocompatibilite.

Auto-detection : si stdout est un TTY -> table, sinon -> json.

Pipe composition

Le CLI est concu pour la composition Unix :

# Rechercher -> explorer le graphe
ontologie nodes search "Client" --ids-only | ontologie graph neighbors --stdin --depth 2

# Context pack -> injection prompt
ontologie context pack "architecture" --format markdown | pbcopy

# Schema -> analyse jq
ontologie schema export --format json | jq '.objectTypes | length'

# Batch node details
cat node-ids.txt | ontologie graph neighbors --stdin --ids-only | sort -u

Architecture

+---------------------------------------------------------+
|  $ ontologie context pack "query" --budget 4000          |
|                                                         |
|  CLI (Commander.js)                                     |
|  +-- config.ts     -- Resolution chaine (flag>env>file) |
|  +-- client.ts     -- Factory @ontologie/sdk-client      |
|  +-- stdin.ts      -- Support pipe Unix                 |
|  +-- cache/        -- Cache local SHA256 + TTL          |
|  +-- output/       -- 7 formatters (json,table,csv,...) |
|  +-- commands/     -- 9 commandes enregistrees          |
|         |                                               |
|         v HTTP                                          |
|  @ontologie/sdk-client                                  |
|  +-- ContextOperations.pack()                           |
|         |                                               |
|         v POST /api/v1/context/pack                     |
|  Backend                                                |
|  +-- Route: context-pack.ts (Zod validation)            |
|  +-- Service: ContextPackService.ts                     |
|       +-- OntologyContextService (20% budget)           |
|       +-- HybridSearchService    (40% budget)           |
|       +-- ArangoDBService        (30% budget)           |
+---------------------------------------------------------+

Contrat JSON (dataforge.cli.v1)

Quand --format json est utilise, toutes les commandes retournent une enveloppe stable :

{
  "ok": true,                    // boolean
  "data": [...],                 // resultat (null si erreur)
  "error": null,                 // CliError (null si succes)
  "page": null,                  // pagination cursor-based (si applicable)
  "meta": {
    "schemaVersion": "dataforge.cli.v1",
    "command": "nodes.list",
    "requestId": "local_req_...",
    "workspaceId": "...",
    "environment": "staging",    // detecte depuis apiUrl
    "warnings": []
  }
}

Specification complete : produit/02-cli/cli-contract.md

Codes de sortie

| Code | Error Code | Signification | |------|-----------|--------------| | 0 | (succes) | Commande reussie | | 1 | NOT_FOUND, UNAVAILABLE, INTERNAL_ERROR | Ressource introuvable / erreur serveur | | 2 | INVALID_USAGE | Arguments CLI invalides | | 3 | AUTHENTICATION_ERROR | Credentials invalides ou manquants | | 4 | AUTHORIZATION_ERROR | Permissions insuffisantes | | 5 | VALIDATION_ERROR | Validation schema/payload echouee | | 6 | SCHEMA_DRIFT_ERROR | Manifeste local != schema distant | | 7 | QUOTA_EXCEEDED | Quota workspace epuise | | 8 | RATE_LIMITED | Trop de requetes (retryable) | | 9 | CONFLICT_ERROR | Conflit OCC (retryable) | | 10 | PRECONDITION_FAILED, CONFIRMATION_REQUIRED | Precondition non remplie / --yes requis | | 11 | NETWORK_ERROR | Connexion refusee / DNS (retryable) | | 12 | TIMEOUT_ERROR | Timeout (retryable) |

Developpement

# Mode dev (sans build)
cd sdk/packages/cli
npx tsx src/cli.ts whoami --api-key df_... --workspace <uuid>

# Build
pnpm build

# Tests
pnpm test

Dependances

| Package | Role | |---------|------| | @ontologie/schema | Schema DSL, compiler, diff, push/pull | | @ontologie/sdk-client | Client HTTP type-safe | | @ontologie/sdk-types | Types runtime | | commander | Framework CLI | | yaml | Parsing ~/.ontologierc | | keytar | (optional) Keychain credential storage |

Migration depuis v0.1.0

| v0.1.0 | v0.2.0 | Notes | |--------|--------|-------| | df | ontologie | Binaire df est un shim deprece | | ~/.dfrc | ~/.ontologierc | ontologie config migrate | | DF_API_KEY | ONTOLOGIE_API_KEY | Legacy vars still work (with warning) | | DF_WORKSPACE_ID | ONTOLOGIE_WORKSPACE_ID | Legacy vars still work (with warning) | | -e, --espace | -s, --space | --espace still works (hidden) | | docs search | knowledge search | docs still works (hidden alias) | | --format plain | --format markdown | plain still works (alias) | | ~/.df/cache/ | ~/.ontologie/cache/ | Old cache auto-detected |

Voir aussi

• SDK README -- Vue d'ensemble du SDK
• ContextPackService -- Service backend
• Route API -- Endpoint REST
• ContextCompiler -- Compilateur contexte agent avance