🐝 apiario — CLI Harness

An npx-installable CLI tool that wraps pi.dev (v0.74.0), pre-configured to use Apiário's API (api.apiario.dev) as the LLM provider. Launches directly into pi's TUI interactive mode.

Usage

# Run directly (requires Node >= 20.6.0)
npx apiario

# Or with an explicit API key
APIARIO_API_KEY=sk-... npx apiario

On first run, the tool will guide you through setting up your API key.

Quick start

1. Get an API key at platform.apiario.dev/auth
2. Run npx apiario
3. Paste your sk-... key when prompted
4. Start chatting in the TUI

Environment variables

| Variable | Required | Description | | ----------------- | -------- | ------------------------------------------------------------------- | | APIARIO_API_KEY | No | API key. Falls back to ~/.config/apiario/settings.json if not set |

Integração com o Herdr (opt-in)

Quando o apiario roda dentro de um pane do Herdr, ele se reporta como agente (working/idle) e expõe a referência da sessão, fazendo o pane aparecer na seção Agents da sidebar e habilitando o resume.

A integração é opt-in por ambiente e é um no-op absoluto fora do Herdr. Ela só age quando o Herdr injeta as três variáveis no processo:

| Variável | Descrição | | ------------------- | ------------------------------------------------------ | | HERDR_ENV | Precisa ser 1 | | HERDR_SOCKET_PATH | Caminho do socket Unix do Herdr | | HERDR_PANE_ID | Identificador do pane atual |

Essas variáveis são herdadas automaticamente: nenhuma configuração manual é necessária. Fora de um pane do Herdr (ou sem HERDR_ENV=1), a extensão nem registra handlers e o harness se comporta exatamente como antes. Erros de conexão ao socket são engolidos silenciosamente — nunca quebram a TUI.

Detalhes de implementação: src/extensions/herdr.ts (--source custom:apiario, --agent apiario, seq monotônico e fila de coalescência de estado).

Config file location

All configuration is stored under ~/.config/apiario/:

• settings.json — API key
• models.json — Cached model list (24 h TTL)

Development

# Install dependencies
cd harness && npm install

# Build
npm run build

# Watch mode
npm run dev

# Run locally
node dist/cli.js

License

MIT