# liluser

> liluser runs autonomous agent personas against your web app and reports
> what an AI agent actually experiences: can it complete the task, where does
> it get stuck, and which parts of the app are agent-hostile.

Docs: <https://liluser.dev> · API base: <https://api.liluser.dev>

## Concepts

- **Run / episode**: one persona (an LLM driving a real browser) attempts one
  goal against one URL. Artifacts (screenshots, findings, transcript) are
  retained per the corpus policy.
- **Persona**: a named behavior profile. Stock personas:
  `first-time-operator` (default), `skeptical-developer`, `impatient-evaluator`.
- **Audit**: a run with `models[]` — the same persona × N models, merged into
  a readiness report (per-model matrix + findings).
- **Findings**: UX problems the persona hit, including agent-hostile classes
  (missing ARIA labels, hover-only affordances, CAPTCHA walls, DOM-only state).

## API (v1)

Auth: `Authorization: Bearer tf_…` on all `/v1/*` routes. Keys are
admin-minted only (no self-serve signup yet); ask a liluser admin.
Default cap 100 runs per 30-day window (429 over cap, 403 revoked).

```text
POST /v1/runs            → 201 {run_id}
  body: {url, persona, goal?, models?, callback_url?}
GET  /v1/runs/:id        → {run_id, status, outcome?, ux_findings?, artifacts_url?, error?}
  status: queued | running | succeeded | failed
GET /v1/runs/:id/report.md → markdown report (404 until the run's report is rendered)
GET /llms.txt            → this file (no auth)
```

`callback_url` (optional, https only, no internal hosts) receives a POST with
the final run payload when the run terminates.

## CLI

```bash
export LILUSER_API_KEY=tf_…        # admin-minted key

npx liluser init                 # writes liluser.config.json + AGENTS.md snippet
npx liluser run --url https://myapp.dev
npx liluser run --url https://myapp.dev --persona skeptical-developer --goal "sign up"
npx liluser audit --url https://myapp.dev     # multi-model readiness audit
```

Flags: `--api-url <base>` (or `LILUSER_API_URL`; default
`https://api.liluser.dev`), `--persona`, `--goal`,
`--model <id>` (repeatable), `--timeout <minutes>`.

## liluser.config.json

Written by `liluser init` into the repo being onboarded:

```json
{
  "url": "https://your-app.example.com",
  "persona": "first-time-operator",
  "goal": ""
}
```

The CLI reads it from the cwd when flags are omitted (flags win).

## Pricing (beta)

Per-run billing with per-model cost accounting; audit default is 3–4 models,
CI default 1, beta cap 3 models per run.