Vijil SDK & CLI

Measure and improve AI agent trustworthiness from your terminal or Python code.

Vijil provides a unified trust layer for the entire agent lifecycle — from discovery through deployment. Evaluate your agent against known standards, test it under adversarial pressure, adapt it to fix weaknesses, and protect it with runtime Guardrails.

Install

pip install vijil-sdk

Requires Python 3.12+. Installs both the vijil CLI and the vijil Python SDK.

Using Vijil from Claude Desktop, Cursor, or other MCP-aware agent frameworks? See vijil-mcp — a separate package that exposes the Vijil platform as MCP tools. The SDK and the MCP server are independent: vijil-sdk runs in your Python process; vijil-mcp runs as a stdio server attached to your agent framework.

Migrating from the legacy vijil PyPI package (pre-2026)? See docs/migration-from-legacy-vijil.md for the install change, auth flow change, and command-by-command map.

Authenticate

Create an API key in your Vijil Console deployment > Settings > API Keys — a client ID (vk_…) plus a one-time secret. Export the pair; the SDK exchanges it for a short-lived access token automatically:

export VIJIL_CLIENT_ID="vk_..."
export VIJIL_CLIENT_SECRET="..."   # shown once at creation

Already have a bearer access token? Use it directly instead — vijil auth login saves one, or set it in the environment:

vijil auth login                   # paste an access token; saved to ~/.vijil/credentials.json
export VIJIL_API_KEY="<access-token>"

Quick start: CLI

# Evaluate against standard trust Harnesses
vijil evaluate <agent-id> --baseline

# Test under adversarial pressure (Swarm)
vijil test <agent-id> --adaptive

# View trust scores
vijil scores show <agent-id>

# Configure runtime Guardrails
vijil protect <agent-id> --guards prompt_injection,pii --mode enforce

# Improve the agent through corrective evolution
vijil adapt <agent-id> --mode config

Quick start: SDK

from vijil import Vijil

client = Vijil()

# Evaluate and wait for results
evaluation = client.evaluate("my-agent", baseline=True)
print(f"Trust score: {evaluation.trust_score}")
print(f"Reliability: {evaluation.dimensions.reliability}")
print(f"Security:    {evaluation.dimensions.security}")
print(f"Safety:      {evaluation.dimensions.safety}")

# Test under adversarial pressure
job = client.test("my-agent", mode="adaptive")
print(f"Test status: {job.status}")

# Configure Guardrails
dome = client.protect("my-agent", guards=["prompt_injection", "pii"])

# Improve the agent
job = client.adapt("my-agent", mode="config")

How it works

The CLI and SDK are organized into two tiers, inspired by Git:

Porcelain commands (lifecycle verbs)

High-level commands that map to stages of the agent trust lifecycle:

Plumbing commands (resource nouns)

Low-level CRUD operations on platform resources:

Setup commands

Key concepts

Evaluate vs Test: evaluate measures against known standards (like a certification exam). test explores for unknown weaknesses through adversarial pressure (like a penetration test). Both produce trust scores.

Adapt vs Evolve: adapt improves an existing agent through corrective evolution, fixing weaknesses found by evaluation or testing. evolve creates an entirely new agent from a spec or natural-language description.

Trust dimensions: Every evaluation produces scores across three dimensions — reliability (does it work correctly?), security (can it resist exploitation?), and safety (does it behave responsibly?).

Global options

--output, -o    Output format: table, json, yaml, quiet (default: auto)
--gateway       Gateway URL override
--api-key       API key override (or set VIJIL_API_KEY)
--quiet, -q     Quiet mode — IDs only
--verbose, -v   Debug logging

Shell composability

The CLI supports shell scripting:

# JSON output for machine consumption
vijil evaluate my-agent --baseline -o json | jq '.trust_score'

# Quiet mode returns just the ID
EVAL_ID=$(vijil evaluate my-agent --baseline -q)
vijil reports download "$EVAL_ID"

# Pipe agent list to evaluation
vijil agents list -q | xargs -I{} vijil evaluate {} --baseline --no-wait

Exit codes follow Unix convention:

Agent aliases

Set short names for agent IDs you use often:

vijil config set aliases.travel-agent d0087de1-a032-49f7-9d28-3abf4a34404d

# Now use the alias anywhere
vijil evaluate travel-agent --baseline
vijil scores show travel-agent

Framework integrations

Coming soon — Guides for integrating Vijil into agent development frameworks:

• Google ADK — Evaluate and protect ADK agents
• LangGraph — Add trust checks to LangGraph workflows
• CrewAI — Monitor and adapt CrewAI agents

See docs/integrations/ for the roadmap.

Documentation

Requirements

• Python 3.12+
• A Vijil account (access to your Vijil Console deployment)

License

Proprietary. Copyright 2024-2026 Vijil AI, Inc.