# @azothos/cli

El comando `azoth`: retransmite por la pasarela las llamadas de una herramienta de código con IA, nombra esas llamadas en tus commits, notifica el uso, pide un modelo al enrutador y ejecuta suites de regresión en CI.

```
npm install -g @azothos/cli
azoth --help

# or without installing
npx @azothos/cli --help
```

> El paquete es `@azothos/cli`, para Node.js 18 o posterior. No existe `@azoth/cli`, y `npx azoth` no es Azoth: ese nombre de npm pertenece a otra persona.

## Configuración

Define `AZOTH_API_KEY` — y `AZOTH_BASE_URL` para un despliegue autoalojado — o escríbelos como `apiKey` y `baseUrl` en `~/.azoth/config.json`. El entorno tiene prioridad.

## azoth proxy

- Un relé en tu máquina para cualquier herramienta que acepte una URL base de OpenAI: apúntala a `http://127.0.0.1:8787/v1`, con cualquier clave API.
- Cada llamada va a la pasarela de tu espacio de trabajo con la clave de tu espacio de trabajo, donde se gobierna y se sella; la clave propia de la herramienta nunca se reenvía.
- El relé solo conserva la referencia que lleva cada respuesta — su recibo firmado, o la traza de una respuesta en streaming — en `~/.azoth/receipts.jsonl`, durante 7 días. Solo responde a esta máquina.

```
azoth proxy                                      # relay on http://127.0.0.1:8787/v1
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1   # or the tool's own setting; any API key
```

## azoth hook install

- Añade un hook de git `commit-msg` al repositorio actual: cada commit recibe un trailer `Azoth-Receipt:` por cada llamada que el relé vio desde el último commit, hasta las 5 más recientes.
- Cuando Azoth lee el repositorio, ese commit se muestra como vinculado a la llamada sellada: nombra una llamada que la pasarela selló, nunca una prueba de que el código procede de ella.
- El hook nunca bloquea un commit, no añade nada a un mensaje vacío ni a un merge, y nunca sobrescribe un hook que no escribió — con husky o commitlint, añade `azoth hook run "$1" || true` al tuyo. `azoth hook uninstall` lo elimina.

```
azoth hook install

git commit -m "Fix the retry on 429"
# → Azoth-Receipt: eyJhbGciOiJFZERTQSIs…   (one trailer per relayed call, the latest 5)
```

## Otros comandos

- `azoth ingest [file]` — Notifica eventos de uso desde un archivo, stdin u opciones de línea de comandos
- `azoth route` — Pide un modelo al enrutador (`--mode cost|quality|balanced`)
- `azoth budget` — Muestra cada presupuesto y su consumo; `--exit-on-exceeded` lo convierte en una puerta de CI
- `azoth test run <suite.json>` — Ejecuta una suite de regresión a través de la pasarela; termina con 1 cuando un caso falla

## En CI

```
# .github/workflows/ai-regression.yml
- run: npx --yes @azothos/cli test run suite.json
  env:
    AZOTH_API_KEY: ${{ secrets.AZOTH_API_KEY }}
```
