> ## Documentation Index
> Fetch the complete documentation index at: https://vijil-vijil-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install Vijil, register an Agent, run a trust Evaluation, and retrieve results, through the CLI, MCP, or REST API.

Vijil exposes four programmatic interfaces. This quickstart takes you from a fresh setup to a completed trust Evaluation. The workflow is the same for all four, so pick the tab for the interface you prefer at each step.

| Interface    | Best For                                       | Requires                   |
| ------------ | ---------------------------------------------- | -------------------------- |
| **CLI**      | Scripting, CI/CD gates, headless automation    | `vijil-console`            |
| **MCP**      | Interactive development, natural language      | Claude Code + `vijil-mcp`  |
| **REST API** | Custom integrations, non-Python environments   | HTTP client + API key      |
| **SDK**      | Python apps, notebooks, programmatic pipelines | `vijil-sdk` (Python 3.12+) |

## Prerequisites

* A [Vijil Console](/developer-guide/deploy-vijil/deploy-vijil-console) deployment and its API gateway URL
* An API key for the AI model you want to evaluate
* A Vijil API key from the Console (**Settings** > **API Keys**) — a client ID and secret — for the SDK
* [Python 3.8](https://www.python.org/) or later (CLI and MCP only; the SDK requires Python 3.12 or later)
* [Claude Code](https://claude.ai/code) installed (MCP only)

## Steps

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="CLI">
        Install `vijil-console` via pip or pipx:

        <CodeGroup>
          ```bash pip theme={null}
          pip install vijil-console
          ```

          ```bash pipx theme={null}
          pipx install vijil-console
          ```
        </CodeGroup>

        Verify the installation:

        ```bash theme={null}
        vijil --help
        ```
      </Tab>

      <Tab title="MCP">
        Install `vijil-mcp`. It pulls in `vijil-console` as a dependency, so you get both the MCP server and the CLI in a single install:

        <CodeGroup>
          ```bash pip theme={null}
          pip install vijil-mcp
          ```

          ```bash pipx theme={null}
          pipx install vijil-mcp
          ```
        </CodeGroup>

        Verify both components are available:

        ```bash theme={null}
        vijil --help
        vijil-mcp --help
        ```
      </Tab>

      <Tab title="REST API">
        No installation is required. You only need an HTTP client such as `curl`. Set your API gateway URL as a shell variable for convenience:

        ```bash theme={null}
        export VIJIL_URL="https://console-api.example.com"
        ```
      </Tab>

      <Tab title="SDK">
        Install `vijil-sdk`, which provides the `vijil` Python SDK:

        <CodeGroup>
          ```bash pip theme={null}
          pip install vijil-sdk
          ```

          ```bash poetry theme={null}
          poetry add vijil-sdk
          ```
        </CodeGroup>

        The SDK requires Python 3.12 or later. Verify the import:

        ```bash theme={null}
        python -c "from vijil import Vijil; print('ok')"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure and Authenticate">
    <Tabs>
      <Tab title="CLI">
        Point the CLI at your Console API gateway, then log in:

        ```bash theme={null}
        vijil auth init --url https://console-api.example.com
        vijil auth login
        ```

        You will be prompted for your email and password. The CLI stores your token in `~/.vijil/config.yaml`.

        If you belong to multiple teams, select the one you want to work with:

        ```bash theme={null}
        vijil team list
        vijil team use <team_id>
        ```

        <Tip>
          Every subsequent command uses the active team automatically, so you do not need to pass a team ID manually.
        </Tip>
      </Tab>

      <Tab title="MCP">
        `vijil-mcp` reads the same credentials as the CLI. Configure and log in once:

        ```bash theme={null}
        vijil auth init --url https://console-api.example.com
        vijil auth login
        vijil team use <team_id>   # if you belong to multiple teams
        ```

        Then create a `.mcp.json` file in your project root so Claude Code launches the server:

        ```json theme={null}
        {
          "mcpServers": {
            "vijil": {
              "type": "stdio",
              "command": "vijil-mcp"
            }
          }
        }
        ```

        Start Claude Code in the directory containing `.mcp.json` and confirm the connection:

        <Prompt description="Check my Vijil setup">
          Check my Vijil setup
        </Prompt>

        Claude calls the `vijil_status` tool, which confirms the CLI is configured, authenticated, and has a team selected.

        <Tip>
          For access across all projects, add the same block to `~/.claude.json` instead of a per-project `.mcp.json`.
        </Tip>
      </Tab>

      <Tab title="REST API">
        Exchange your credentials for a JWT access token:

        ```bash theme={null}
        curl -s -X POST "$VIJIL_URL/auth/jwt/login" \
          -H "Content-Type: application/json" \
          -d '{"email": "user@example.com", "password": "your-password"}'
        ```

        Save the returned token and include it on every subsequent request:

        ```bash theme={null}
        export TOKEN="eyJhbG..."
        ```

        Most operations are scoped to a team. List your memberships and save the `team_id`:

        ```bash theme={null}
        curl -s "$VIJIL_URL/users/me/teams" \
          -H "Authorization: Bearer $TOKEN"

        export TEAM_ID="c58aea71-..."
        ```
      </Tab>

      <Tab title="SDK">
        Create an API key in the Console under **Settings** > **API Keys** — a client ID (`vk_…`) plus a one-time secret shown only at creation. Export the pair; the SDK exchanges it for a short-lived access token automatically:

        ```bash theme={null}
        export VIJIL_CLIENT_ID="vk_..."
        export VIJIL_CLIENT_SECRET="..."   # shown once at creation
        ```

        Construct the client, pointing it at your Console gateway:

        ```python theme={null}
        from vijil import Vijil

        client = Vijil(gateway="https://console-api.example.com")
        ```

        `Vijil()` reads the credentials from the environment automatically. If you already have a bearer access token, use it directly instead with `VIJIL_API_KEY` or `Vijil(api_key="<access-token>")` — but note that a bearer token is a JWT that expires 24 hours after it is issued. The client ID and secret do not expire, and the SDK refreshes the token from them automatically, so prefer the pair for long-lived automation.

        <Tip>
          In CI/CD, set `VIJIL_CLIENT_ID` and `VIJIL_CLIENT_SECRET` as secrets rather than committing them.
        </Tip>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Register an Agent">
    <Tabs>
      <Tab title="CLI">
        Create an [Agent](/owner-guide/register-agents/what-is-an-agent) configuration for the model you want to evaluate. Export your provider API key first to keep it out of your shell history:

        ```bash theme={null}
        export OPENAI_API_KEY="sk-..."

        vijil agent create \
          --agent-name "My Chat Agent" \
          --model-name "gpt-4o" \
          --agent-url "https://api.openai.com/v1/chat/completions" \
          --api-key "$OPENAI_API_KEY"
        ```

        The output includes the new Agent's `id`. Save it, then confirm the Agent was registered:

        ```bash theme={null}
        export AGENT_ID="a1b2c3d4-..."
        vijil agent list
        ```
      </Tab>

      <Tab title="MCP">
        Tell Claude about the model you want to evaluate:

        <Prompt description="Create a new agent called 'My Chat Agent' using gpt-4o at https://api.openai.com/v1/chat/completions with my OpenAI API key sk-…">
          Create a new agent called 'My Chat Agent' using gpt-4o at [https://api.openai.com/v1/chat/completions](https://api.openai.com/v1/chat/completions) with my OpenAI API key sk-…
        </Prompt>

        Claude calls `agent_create` and shows you the new [Agent](/owner-guide/register-agents/what-is-an-agent) including its ID. Note that ID, you will use it in the next steps. To see all registered Agents at any time:

        <Prompt description="List my agents">
          List my agents
        </Prompt>
      </Tab>

      <Tab title="REST API">
        Create an Agent configuration pointing at the AI model you want to evaluate. The team is derived from your JWT token, so no `team_id` parameter is needed:

        ```bash theme={null}
        curl -s -X POST "$VIJIL_URL/agent-configurations/" \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json" \
          -d '{
            "agent_name": "My Chat Agent",
            "model_name": "gpt-4o",
            "agent_url": "https://api.openai.com/v1/chat/completions",
            "api_key": "sk-..."
          }'
        ```

        The response (HTTP 201) includes the new Agent's `id`. Save it:

        ```bash theme={null}
        export AGENT_ID="a1b2c3d4-..."
        ```
      </Tab>

      <Tab title="SDK">
        Create an [Agent](/owner-guide/register-agents/what-is-an-agent) configuration for the model you want to evaluate:

        ```python theme={null}
        agent = client.agents.create(
            name="My Chat Agent",
            url="https://api.openai.com/v1/chat/completions",
        )
        print(agent.id)
        ```

        Keep the returned `agent` object, you will pass `agent.id` to the Evaluation. To see all registered Agents at any time:

        ```python theme={null}
        for a in client.agents.list().items:
            print(a.id, a.name)
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Choose a Harness">
    [Harnesses](/concepts/evaluation-components/harness) are test suites that cover a specific [trust dimension](/concepts/trust-score/introduction). The standard Harnesses include `safety`, `security`, `reliability`, `privacy`, `toxicity`, and `ethics`. For this quickstart you will run `safety` and `security`.

    <Tabs>
      <Tab title="CLI">
        List the available standard Harnesses:

        ```bash theme={null}
        vijil harness list
        ```
      </Tab>

      <Tab title="MCP">
        Ask Claude which Harnesses are available:

        <Prompt description="What Harnesses are available?">
          What Harnesses are available?
        </Prompt>
      </Tab>

      <Tab title="REST API">
        List the standard Harnesses:

        ```bash theme={null}
        curl -s "$VIJIL_URL/harnesses/?team_id=$TEAM_ID" \
          -H "Authorization: Bearer $TOKEN"
        ```
      </Tab>

      <Tab title="SDK">
        List the available Harnesses:

        ```python theme={null}
        for harness in client.harnesses.list().items:
            print(harness.name)
        ```

        For this quickstart you will use the standard trust Harnesses, which `client.evaluate(..., baseline=True)` runs in the next step. To run a specific custom Harness instead, pass its `harness_id`.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Run an Evaluation">
    <Tabs>
      <Tab title="CLI">
        Start an Evaluation and wait for it to complete:

        ```bash theme={null}
        vijil eval run \
          --agent-id "$AGENT_ID" \
          --harness-names '["safety", "security"]' \
          --sample-size 50 \
          --wait
        ```

        `--sample-size 50` runs 50 [Probes](/concepts/evaluation-components/probe) per Harness, enough for a meaningful score in a few minutes. Omit it to run the full Harness (\~1,250 Probes for `security`). The CLI polls every 5 seconds and prints the evaluation ID when complete. Save it:

        ```bash theme={null}
        export EVAL_ID="e5f6a7b8-..."
        ```
      </Tab>

      <Tab title="MCP">
        Start a trust Evaluation and wait for it to finish:

        <Prompt description="Run a safety and security evaluation on agent a1b2c3d4-… with a sample size of 50, and wait for it to complete">
          Run a safety and security evaluation on agent a1b2c3d4-… with a sample size of 50, and wait for it to complete
        </Prompt>

        Claude calls `eval_run` with `wait=True`, polls every 5 seconds, and reports back when the Evaluation finishes, including the per-Harness scores.

        <Tip>
          Ask for a sample size of 10 for fast iteration during development. Run the full Harness before releasing to production.
        </Tip>
      </Tab>

      <Tab title="REST API">
        Start a trust Evaluation. Evaluations run asynchronously, so the API returns immediately with a `202 Accepted` status and an `evaluation_id`:

        ```bash theme={null}
        curl -s -X POST "$VIJIL_URL/evaluations/" \
          -H "Authorization: Bearer $TOKEN" \
          -H "Content-Type: application/json" \
          -d "{
            \"agent_id\": \"$AGENT_ID\",
            \"team_id\": \"$TEAM_ID\",
            \"harness_names\": [\"safety\", \"security\"],
            \"sample_size\": 50
          }"
        ```

        Save the evaluation ID, then poll for status until it reaches `completed`:

        ```bash theme={null}
        export EVAL_ID="e5f6a7b8-..."

        curl -s "$VIJIL_URL/evaluations/$EVAL_ID" \
          -H "Authorization: Bearer $TOKEN"
        ```

        The `status` field progresses through `starting` → `pending` → `running` → `completed` → `saving` → `saved`.
      </Tab>

      <Tab title="SDK">
        Start a trust Evaluation against the standard Harnesses. `evaluate` polls until the Evaluation completes, then returns the result:

        ```python theme={null}
        evaluation = client.evaluate(agent.id, baseline=True)
        print(evaluation.status)   # "completed"
        ```

        Polling runs every 5 seconds by default. Adjust it with the `_poll_interval` argument. `baseline=True` covers the reliability, security, and safety dimensions in a single run.
      </Tab>
    </Tabs>
  </Step>

  <Step title="View the Results">
    <Tabs>
      <Tab title="CLI">
        Retrieve your [Trust Score](/concepts/trust-score/introduction) and per-Harness breakdown:

        ```bash theme={null}
        vijil eval results-detail "$EVAL_ID"
        ```

        This returns scores per Harness (0 to 1), individual Probe results, and identified failure patterns. To filter with `jq`:

        ```bash theme={null}
        vijil eval results-detail "$EVAL_ID" --json | jq '.scores'
        ```
      </Tab>

      <Tab title="MCP">
        Once the Evaluation completes, retrieve the full results:

        <Prompt description="Show me the detailed results for evaluation e5f6a7b8-…">
          Show me the detailed results for evaluation e5f6a7b8-…
        </Prompt>

        Claude calls `eval_results_detail` and presents your [Trust Score](/concepts/trust-score/introduction), per-Harness breakdowns, and individual Probe results with identified failure patterns.
      </Tab>

      <Tab title="REST API">
        Retrieve the full results once the Evaluation has completed:

        ```bash theme={null}
        curl -s "$VIJIL_URL/evaluation-results/$EVAL_ID/results?team_id=$TEAM_ID" \
          -H "Authorization: Bearer $TOKEN"
        ```

        This returns the detailed results JSON including per-Harness breakdowns, individual Probe results, and analysis.
      </Tab>

      <Tab title="SDK">
        Read the [Trust Score](/concepts/trust-score/introduction) and per-dimension breakdown straight off the returned Evaluation:

        ```python theme={null}
        print(evaluation.trust_score)               # 0.82
        print(evaluation.dimensions.reliability)
        print(evaluation.dimensions.security)
        print(evaluation.dimensions.safety)
        ```

        To fetch the latest score for an Agent later, without holding the Evaluation object:

        ```python theme={null}
        score = client.scores.show(agent.id)
        print(score.trust_score)
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Generate a Report">
    <Tabs>
      <Tab title="CLI">
        Trigger a [Trust Report](/developer-guide/evaluate/understanding-results) for the completed Evaluation:

        ```bash theme={null}
        vijil eval report "$EVAL_ID"
        ```

        The report summarizes what was tested, how the Agent scored, and where it failed. Download it as HTML or PDF from the Console.
      </Tab>

      <Tab title="MCP">
        Trigger a [Trust Report](/developer-guide/evaluate/understanding-results) for the completed Evaluation:

        <Prompt description="Generate a report for evaluation e5f6a7b8-…">
          Generate a report for evaluation e5f6a7b8-…
        </Prompt>

        Claude calls `eval_report`. Download the report as HTML or PDF from the Console.
      </Tab>

      <Tab title="REST API">
        Download the [Trust Report](/developer-guide/evaluate/understanding-results) for the completed Evaluation as HTML or PDF:

        ```bash theme={null}
        curl -s "$VIJIL_URL/evaluations/$EVAL_ID/html?team_id=$TEAM_ID" \
          -H "Authorization: Bearer $TOKEN" \
          -o report.html

        curl -s "$VIJIL_URL/evaluations/$EVAL_ID/pdf?team_id=$TEAM_ID" \
          -H "Authorization: Bearer $TOKEN" \
          -o report.pdf
        ```
      </Tab>

      <Tab title="SDK">
        Download the [Trust Report](/developer-guide/evaluate/understanding-results) for the completed Evaluation as a PDF:

        ```python theme={null}
        pdf_bytes = client.reports.download(evaluation.id)
        with open("report.pdf", "wb") as f:
            f.write(pdf_bytes)
        ```

        The report summarizes what was tested, how the Agent scored, and where it failed.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/developer-guide/cli/setup">
    Full command reference for auth, Agents, Evaluations, and protection
  </Card>

  <Card title="MCP Tools Reference" icon="wrench" href="/developer-guide/agentic/tools">
    Complete list of MCP tools with parameters and example prompts
  </Card>

  <Card title="SDK Reference" icon="code" href="/developer-guide/sdk/setup">
    Python client, lifecycle methods, resources, models, and errors
  </Card>

  <Card title="Understand Results" icon="chart-line" href="/developer-guide/evaluate/understanding-results">
    Interpret Trust Scores and prioritize what to fix
  </Card>

  <Card title="Custom Harnesses" icon="flask-conical" href="/developer-guide/evaluate/custom-harnesses">
    Generate test suites tailored to your Agent
  </Card>
</CardGroup>

## Troubleshooting

| Symptom                               | Fix                                                                                                |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `vijil` not found in `PATH`           | Re-install with `pipx`, which handles `PATH` setup automatically                                   |
| CLI not configured                    | Run `vijil auth init --url <your-url>`                                                             |
| Session expired                       | Run `vijil auth login`                                                                             |
| No team selected                      | Run `vijil team list` then `vijil team use <team_id>`                                              |
| Tools do not appear in Claude Code    | Verify `.mcp.json` is in the project root, then restart Claude Code                                |
| Claude uses Bash instead of MCP tools | Confirm `vijil-mcp` is in your `PATH`: run `which vijil-mcp`                                       |
| `401 Unauthorized` from the REST API  | Your token expired, request a new one from `POST /auth/jwt/login`                                  |
| `VijilAuthError` from the SDK         | Set `VIJIL_CLIENT_ID` and `VIJIL_CLIENT_SECRET` (or `VIJIL_API_KEY`) before constructing `Vijil()` |
| SDK import fails                      | Ensure you are on Python 3.12 or later, then reinstall with `pip install vijil-sdk`                |