CLI (enterprise-ai)

Ce guide montre comment installer la ligne de commande enterprise-ai, configurer un profil, puis l'utiliser pour créer, valider, tester, déployer et exécuter des agents, depuis un poste de travail ou un pipeline de CI. La CLI repose sur le SDK Python (sdks/python/src/enterprise_ai/cli). Chaque commande, option et code de sortie figure dans la référence de la CLI générée (python tools/cli/gen_reference.py, vérifiée en CI avec --check).

English version: cli.md

Vue d'ensemble

Besoin	Commandes
Configurer l'accès	login, config, doctor
Créer un projet ou un manifeste	create, init, plugin create
Vérifier des documents	validate, test, plugin validate
Livrer	apply, deploy, publish, plugin build, plugin sign, plugin publish, plugin install
Exécuter et observer	run, runs, logs, chat, agent inspect
Lire la plateforme	get, delete, models resolve, context plan, finops, quotas, audit verify
Exploiter l'infrastructure	manager (SDK et CLI du Navin Manager)
Documenter	docs

Prérequis et compatibilité

Élément	Pris en charge
Python	3.10 ou plus (la CLI est livrée dans le paquet enterprise-ai)
Systèmes d'exploitation	Linux, macOS, Windows
Outils optionnels	opa et fga pour test authz, cosign pour publish --sign et plugin sign ; cherchés dans le PATH, puis dans EAI_TOOLCHAIN_DIR (/tmp/toolchains par défaut)
API du Control Plane	v1

Installation

1. Installez la commande. La CLI fait partie du paquet Python : récupérez-le dans Harbor comme décrit dans le guide du SDK Python, puis installez-le avec pipx (environnement propre ; pip dans un environnement virtuel convient aussi).

   oras login registry.navinspire.ai
   oras pull registry.navinspire.ai/sdk/python:1.0.2 -o sdk-python
   pipx install sdk-python/enterprise_ai-1.0.2-py3-none-any.whl
   enterprise-ai --version

   Résultat attendu : la version du paquet (1.0.2). Le registre est registry.navinspire.ai. Les réseaux hors ligne installent la même wheel depuis un dépôt de wheels, comme décrit dans le guide du SDK Python.

Démarrage rapide

Le parcours du développeur, d'un dossier vide à un agent en cours d'exécution :

enterprise-ai login --base-url https://ai.acme.example --api-key eai_...
enterprise-ai doctor                                  # configuration, connectivity, TLS, authentication, versions, clock (PASS, WARN, FAIL)
enterprise-ai create agent ticket-helper --template agent-basic   # also rag-agent; create mcp|connector|policy|skill|prompt
cd ticket-helper && enterprise-ai validate -f agent.yaml
enterprise-ai test authz                              # opa test on policies/ and fga model test on *.fga.yaml (missing binary = error)
enterprise-ai test security --threshold 0             # red team run (POST /v1/redteam/runs), exit 1 above the threshold
enterprise-ai test sdk-conformance                    # contracts/v1 of the SDK against the endpoint
enterprise-ai deploy agent -f agent.yaml --env dev
enterprise-ai run start ticket-helper --task "Summarise this ticket" --follow   # prints the run id and its trace id
enterprise-ai docs --write cli-reference.md

Chaque étape, dans l'ordre : enregistrer les identifiants dans un profil ; vérifier la configuration ; créer un projet ; valider le manifeste contre contracts/v1 ; lancer les tests de politiques et de modèle ; lancer le red team ; vérifier la conformité du SDK ; déployer en dev après la quality gate ; lancer un run et suivre ses événements ; écrire la référence de la CLI installée. Chaque modèle contient AGENTS.md et RULES.md (règles pour les agents de code : aucun secret, aucun appel direct à un LLM hors du gateway, tests obligatoires, anglais et français), des manifestes valides contre contracts/v1, des politiques OPA avec leurs tests, des tests unitaires et un README en anglais et en français.

Le Developer Studio du portail modifie les mêmes objets (prompts, skills, MCP, connecteurs, politiques) avec l'éditeur Monaco, intégré au portail (aucun CDN, prêt pour un réseau isolé) : ses workers sont des fichiers de même origine autorisés par worker-src 'self' blob: et ses styles en ligne par le style-src existant, donc la Content Security Policy ne change pas (vérifié dans portal/tests/security.test.ts).

Configuration

La CLI range les profils dans ~/.config/enterprise-ai/config.yaml (écrit de façon atomique, mode 0600, dossier 0700). Un réglage est pris, du plus prioritaire au moins prioritaire, dans l'option (--base-url, --lang), le profil choisi (--profile, sinon EAI_PROFILE, sinon le profil courant), puis les variables EAI_* lues par le SDK Python.

Réglage	Clé du profil	Variable d'environnement	Défaut
URL du Control Plane	base_url	EAI_BASE_URL	http://127.0.0.1:8000
Clé API	api_key	EAI_API_KEY	aucune
Jeton OIDC	token	EAI_TOKEN	aucun
Tenant, utilisateur et rôles de développement	tenant, dev_user, dev_roles	EAI_TENANT, EAI_DEV_USER, EAI_DEV_ROLES	aucun
Projet, environnement	project, environment	EAI_PROJECT, EAI_ENVIRONMENT	aucun
Langue	locale	EAI_LOCALE	en
Autorités de certification supplémentaires	aucune	EAI_CA_BUNDLE	aucune
Dossier des profils	aucune	EAI_CONFIG_DIR, sinon XDG_CONFIG_HOME/enterprise-ai	~/.config/enterprise-ai
Profil choisi	aucune	EAI_PROFILE	le profil courant

Options globales de chaque commande : --lang en|fr, --output table|json|yaml (-o, table par défaut), --profile <nom>, --base-url <url>.

enterprise-ai config list
enterprise-ai config set project invoices
enterprise-ai config use staging
enterprise-ai config show --output yaml

Authentification

enterprise-ai login enregistre les identifiants dans un profil ; --check appelle GET /v1/me juste après.

Méthode	Commande
Clé API	enterprise-ai login --base-url <url> --api-key <token> --check
Jeton OIDC	EAI_TOKEN=<token> enterprise-ai doctor (lu dans l'environnement), ou la clé token du profil
Mode développement (serveur avec EAI_AUTH_DEV=1)	enterprise-ai login --dev --tenant acme --user alice --roles tenant_admin

<url> est l'adresse du Control Plane et <token> la clé API de votre tenant. config show masque la clé et le jeton.

Erreurs et codes de sortie

Les erreurs de l'API affichent le code, le message dans la langue choisie et l'identifiant de requête sur stderr.

Code de sortie	Signification
0	succès
1	échec de validation, de quality gate, de test ou de contrôle (aussi une validation_error de l'API)
2	erreur d'utilisation (option inconnue, fichier absent)
3	erreur de l'API (réseau, authentification, serveur)

Le groupe manager a ses propres codes, de 0 à 7 (SDK et CLI du Navin Manager).

Reprises, délais et pagination

La CLI utilise le transport du SDK Python : 30 s par tentative, 3 reprises avec délai sur HTTP 429, et sur les 5xx et les erreurs réseau pour les appels sans risque (SDK Python). Les commandes de liste lisent une page : get --limit, runs --limit.

Commandes

Commande	Rôle	API
enterprise-ai login	enregistrer les identifiants dans un profil	/v1/me
enterprise-ai config	lister, afficher, choisir ou modifier des profils	aucune
enterprise-ai init	créer un manifeste et du code de départ	aucune
enterprise-ai create	créer un projet ou une ressource depuis un modèle	aucune
enterprise-ai validate	valider des manifestes et des documents contre les contrats	/v1/contracts/{name}/validate
enterprise-ai apply	appliquer des manifestes	/v1/manifests/apply
enterprise-ai get	lire des ressources ou exporter un manifeste	/v1/manifests/{kind}/{name}
enterprise-ai delete	supprimer une ressource	/v1/agents/{id}, /v1/tools/{name}
enterprise-ai test	suite d'évaluation, red team, tests OPA et OpenFGA, conformité du SDK	/v1/evaluations/runs, /v1/redteam/runs
enterprise-ai publish	publier une skill ou un plugin avec son empreinte	/v1/skills, /v1/plugins
enterprise-ai deploy	appliquer et promouvoir un agent après la quality gate	/v1/manifests/apply, /v1/evaluations/gates/check
enterprise-ai agent inspect	inspecter un agent	/v1/agents/{id}
enterprise-ai run	lancer un run d'un agent déployé et suivre ses événements	/v1/agents/{id}/runs, /v1/runs/{id}/events
enterprise-ai runs	lister, afficher, annuler ou rejouer des runs (--state, alias --status)	/v1/runs, /v1/runs/{id}/cancel
enterprise-ai logs	diffuser les événements d'un run	/v1/runs/{id}/events
enterprise-ai chat	dialoguer par le gateway	/v1/gateway/chat/completions
enterprise-ai models resolve	paramètres natifs ou refus	/v1/models/resolve
enterprise-ai context plan	calculer un budget de contexte (--local sans l'API)	/v1/context/plan
enterprise-ai finops	synthèse et estimation des coûts	/v1/finops/summary, /v1/finops/estimate
enterprise-ai quotas	quotas et consommation	/v1/quotas, /v1/quotas/usage
enterprise-ai audit verify	vérifier la chaîne de hachage de l'audit	/v1/audit/verify
enterprise-ai plugin	packs de la Marketplace : créer, valider, construire, signer, publier, installer	/v1/marketplace/packages
enterprise-ai doctor	configuration, connectivité, TLS, authentification, versions, horloge	/healthz, /v1/me, /v1/meta, /v1/contracts
enterprise-ai docs	afficher ou écrire la référence de la CLI	aucune
enterprise-ai manager	Navin Manager : hôtes, clusters, services, HA, sauvegardes, restaurations, PRA	/api/v1 du Navin Manager

Exemples

enterprise-ai login --base-url <control-plane-url> --lang en
enterprise-ai config set project invoices
enterprise-ai init agent invoice-agent
enterprise-ai validate -f ./manifests/agent.yaml
enterprise-ai apply -f ./manifests/agent.yaml
enterprise-ai get agents --output json
enterprise-ai test --suite invoice-agent-regression --target agent/agt_ap@1.4.0
enterprise-ai deploy agent -f ./manifests/agent.yaml --env prod
enterprise-ai runs list --agent agt_ap --state running --output table
enterprise-ai logs run_42
enterprise-ai chat --model gpt-4o-mini
enterprise-ai models resolve o3-mini --effort high --output yaml
enterprise-ai context plan --window 128000 --output-tokens 4000 --segments ./segments.json
enterprise-ai finops estimate --provider openai --model gpt-4o-mini --input-tokens 12000 --output-tokens 2000
enterprise-ai finops summary --group-by agent
enterprise-ai quotas usage
enterprise-ai audit verify --output json
enterprise-ai delete tool erp.lookup

Utilisation en CI

Un job de pipeline valide les manifestes, lance la suite de régression et promeut l'agent. Les identifiants viennent du coffre de secrets de la CI sous forme de variables d'environnement ; rien n'est écrit dans le dépôt.

quality-gate:
  script:
    - enterprise-ai validate -f ./manifests/agent.yaml --output json
    - enterprise-ai test --suite regression --target agent/$AGENT@$VERSION
    - enterprise-ai deploy agent -f ./manifests/agent.yaml --env staging
  variables:
    EAI_BASE_URL: <control-plane-url>
    EAI_LOCALE: en

EAI_API_KEY est déclarée comme variable masquée de la CI. Un code de sortie non nul arrête le job.

Sécurité

• Le fichier de configuration est écrit de façon atomique avec le mode 0600 (dossier 0700) ; un avertissement s'affiche quand il est lisible par le groupe ou par tous.
• config show masque la clé API et le jeton.
• Les fichiers YAML (manifestes, profils) sont lus avec un chargeur sûr qui refuse les ancres, les alias, les tags Python et les documents de plus de 1 Mio.
• init <kind> <name> : le nom doit respecter ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ ; les fichiers ne sont écrits que dans le dossier cible, jamais à travers un lien symbolique.
• publish --sign appelle cosign sign-blob avec une liste d'arguments (sans shell), -- avant le chemin de l'artefact, une référence de clé validée et une empreinte sha256:<64 hex> validée.
• chat et logs affichent la sortie du modèle en texte brut : les séquences d'échappement ANSI sont retirées et les caractères de contrôle échappés, donc une réponse du modèle ne peut pas piloter le terminal.

Dépannage

Symptôme	Cause	Correction
doctor signale TLS FAIL	autorité de certification privée non reconnue	renseignez EAI_CA_BUNDLE avec le fichier PEM de l'autorité
code de sortie 3 avec unauthenticated	clé ou jeton absent ou expiré	relancez enterprise-ai login --api-key <token> --check
avertissement sur un fichier de configuration lisible	mode plus large que 0600	chmod 600 ~/.config/enterprise-ai/config.yaml
test authz échoue faute de binaire	opa ou fga absent	installez-les dans le PATH ou dans EAI_TOOLCHAIN_DIR

Référence

• Référence de la CLI, générée depuis l'analyseur d'arguments.
• SDK Python, sur lequel repose la CLI.
• SDK et CLI du Navin Manager.