CLI (enterprise-ai)

This guide shows how to install the enterprise-ai command line, configure a profile, and use it to scaffold, validate, test, deploy and run agents, from a workstation or a CI pipeline. The CLI is built on the Python SDK (sdks/python/src/enterprise_ai/cli). Every command, option and exit code is in the generated CLI reference (python tools/cli/gen_reference.py, checked in CI with --check).

Version française : cli.fr.md

Overview

Need	Commands
Configure access	login, config, doctor
Create a project or a manifest	create, init, plugin create
Check documents	validate, test, plugin validate
Ship	apply, deploy, publish, plugin build, plugin sign, plugin publish, plugin install
Run and observe	run, runs, logs, chat, agent inspect
Read the platform	get, delete, models resolve, context plan, finops, quotas, audit verify
Operate the infrastructure	manager (Navin Manager SDK and CLI)
Document	docs

Requirements and compatibility

Item	Supported
Python	3.10 or later (the CLI ships in the enterprise-ai package)
Operating systems	Linux, macOS, Windows
Optional tools	opa and fga for test authz, cosign for publish --sign and plugin sign; searched on PATH, then in EAI_TOOLCHAIN_DIR (default /tmp/toolchains)
Control Plane API	v1

Installation

1. Install the command. The CLI is part of the Python package: pull it from Harbor as described in the Python SDK guide, then install it with pipx (own environment; pip in a virtual environment works too).

   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

   Expected result: the version of the package (1.0.2). The registry is registry.navinspire.ai. Offline networks install the same wheel from a wheelhouse, as described in the Python SDK guide.

Quickstart

The developer path from an empty folder to a running agent:

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

Each step, in order: save the credentials in a profile; check the configuration; scaffold a project; validate the manifest against contracts/v1; run the policy and model tests; run the red team; check the SDK conformance; deploy to dev after the quality gate; start a run and follow its events; write the reference of the installed CLI. Each template holds AGENTS.md and RULES.md (rules for coding agents: no secret, no direct LLM call outside the gateway, tests required, English and French), manifests valid against contracts/v1, OPA policies with tests, unit tests and a README in English and French.

The Developer Studio of the portal edits the same objects (prompts, skills, MCP, connectors, policies) with the Monaco editor, bundled in the portal (no CDN, air gap ready): its workers are same-origin files allowed by worker-src 'self' blob: and its inline styles by the existing style-src, so the Content Security Policy is unchanged (asserted in portal/tests/security.test.ts).

Configuration

The CLI stores profiles in ~/.config/enterprise-ai/config.yaml (written atomically, mode 0600, folder 0700). A setting is taken, highest priority first, from the option (--base-url, --lang), the selected profile (--profile, else EAI_PROFILE, else the current profile), then the EAI_* variables read by the Python SDK.

Setting	Profile key	Environment variable	Default
Control Plane URL	base_url	EAI_BASE_URL	http://127.0.0.1:8000
API key	api_key	EAI_API_KEY	none
OIDC token	token	EAI_TOKEN	none
Development tenant, user, roles	tenant, dev_user, dev_roles	EAI_TENANT, EAI_DEV_USER, EAI_DEV_ROLES	none
Project, environment	project, environment	EAI_PROJECT, EAI_ENVIRONMENT	none
Language	locale	EAI_LOCALE	en
Extra trusted CAs	none	EAI_CA_BUNDLE	none
Profile folder	none	EAI_CONFIG_DIR, else XDG_CONFIG_HOME/enterprise-ai	~/.config/enterprise-ai
Selected profile	none	EAI_PROFILE	the current profile

Global options of every command: --lang en|fr, --output table|json|yaml (-o, default table), --profile <name>, --base-url <url>.

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

Authentication

enterprise-ai login saves the credentials in a profile; --check calls GET /v1/me right after.

Method	Command
API key	enterprise-ai login --base-url <url> --api-key <token> --check
OIDC token	EAI_TOKEN=<token> enterprise-ai doctor (read from the environment), or the token key of the profile
Development mode (server with EAI_AUTH_DEV=1)	enterprise-ai login --dev --tenant acme --user alice --roles tenant_admin

<url> is the Control Plane address and <token> the API key of your tenant. config show masks the key and the token.

Errors and exit codes

API errors print the code, the localized message and the request id on stderr.

Exit code	Meaning
0	success
1	validation, gate, test or check failure (also an API validation_error)
2	usage error (unknown option, missing file)
3	API error (network, authentication, server)

The manager group has its own codes, from 0 to 7 (Navin Manager SDK and CLI).

Retries, timeouts and pagination

The CLI uses the Python SDK transport: 30 s per attempt, 3 retries with backoff on HTTP 429, and on 5xx and network errors for safe calls (Python SDK). List commands read one page: get --limit, runs --limit.

Commands

Command	Purpose	API
enterprise-ai login	save credentials in a profile	/v1/me
enterprise-ai config	list, show, select or edit profiles	none
enterprise-ai init	scaffold a manifest and starter code	none
enterprise-ai create	create a project or a resource from a template	none
enterprise-ai validate	validate manifests and documents against the contracts	/v1/contracts/{name}/validate
enterprise-ai apply	apply manifests	/v1/manifests/apply
enterprise-ai get	read resources or export a manifest	/v1/manifests/{kind}/{name}
enterprise-ai delete	delete a resource	/v1/agents/{id}, /v1/tools/{name}
enterprise-ai test	evaluation suite, red team, OPA and OpenFGA tests, SDK conformance	/v1/evaluations/runs, /v1/redteam/runs
enterprise-ai publish	publish a skill or plugin with its digest	/v1/skills, /v1/plugins
enterprise-ai deploy	apply and promote an agent after the quality gate	/v1/manifests/apply, /v1/evaluations/gates/check
enterprise-ai agent inspect	inspect an agent	/v1/agents/{id}
enterprise-ai run	start a run of a deployed agent and follow its events	/v1/agents/{id}/runs, /v1/runs/{id}/events
enterprise-ai runs	list, show, cancel or replay runs (--state, alias --status)	/v1/runs, /v1/runs/{id}/cancel
enterprise-ai logs	stream the events of a run	/v1/runs/{id}/events
enterprise-ai chat	chat through the gateway	/v1/gateway/chat/completions
enterprise-ai models resolve	native parameters or rejection	/v1/models/resolve
enterprise-ai context plan	compute a context budget (--local without the API)	/v1/context/plan
enterprise-ai finops	cost summary and estimate	/v1/finops/summary, /v1/finops/estimate
enterprise-ai quotas	quotas and usage	/v1/quotas, /v1/quotas/usage
enterprise-ai audit verify	verify the audit hash chain	/v1/audit/verify
enterprise-ai plugin	Marketplace packs: create, validate, build, sign, publish, install	/v1/marketplace/packages
enterprise-ai doctor	configuration, connectivity, TLS, authentication, versions, clock	/healthz, /v1/me, /v1/meta, /v1/contracts
enterprise-ai docs	print or write the CLI reference	none
enterprise-ai manager	Navin Manager: hosts, clusters, services, HA, backups, restores, DR	Navin Manager /api/v1

Examples

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

CI usage

A pipeline job validates the manifests, runs the regression suite and promotes the agent. The credentials come from the secret store of the CI as environment variables; nothing is written in the repository.

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 is set as a masked CI variable. A non zero exit code stops the job.

Security

• The configuration file is written atomically with mode 0600 (folder 0700); a warning is printed when it is group or world readable.
• config show masks the API key and the token.
• YAML files (manifests, profiles) are read with a safe loader that refuses anchors, aliases, Python tags and documents larger than 1 MiB.
• init <kind> <name>: the name must match ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$; files are written only inside the target folder, never through a symbolic link.
• publish --sign calls cosign sign-blob with an argument list (no shell), -- before the artifact path, a validated key reference and a validated sha256:<64 hex> digest.
• chat and logs print model output as plain text: ANSI escape sequences are removed and control characters are escaped, so a model answer cannot drive the terminal.

Troubleshooting

Symptom	Cause	Fix
doctor reports TLS FAIL	private CA not trusted	set EAI_CA_BUNDLE to the PEM file of the CA
exit code 3 with unauthenticated	missing or expired key or token	run enterprise-ai login --api-key <token> --check again
warning about a readable configuration file	mode wider than 0600	chmod 600 ~/.config/enterprise-ai/config.yaml
test authz fails with a missing binary	opa or fga not installed	install them on PATH or in EAI_TOOLCHAIN_DIR

Reference

• CLI reference, generated from the parser.
• Python SDK, on which the CLI is built.
• Navin Manager SDK and CLI.