Help

Using ARIL

ARIL is a native macOS chat client for OpenRouter. It grades prompts, routes models, shows cost before you send, and can run local MCP tools — all from your Mac.

Install

Download ARIL-latest.dmg from this site (or GitHub Releases).
Open the disk image and drag ARIL into Applications.
Launch ARIL. Solo mode starts the bundled local gateway automatically.
Open ARIL → Preferences → Subscription and sign in with OpenRouter or paste an API key.

Requirements: Apple Silicon Mac · macOS 14 (Sonoma) or newer · an OpenRouter key with a small credit balance.

Builds are Developer ID signed and notarized. If an older unsigned build is blocked, right-click the app → Open, or allow it in System Settings → Privacy & Security.

First chat

Type a prompt in the entry field at the bottom of the window.
Wait for the Intelligence panel — it grades the prompt, estimates tokens/cost, and recommends a model.
Press Return to send (or click the send button).

The status tray under the window shows gateway, database, OpenRouter credits, session-cache size, the model in use, and the app version.

Auto · Manual · Judge

Auto — Classifies the prompt and picks the mapped model. Prefer wins from Learning/Judge can promote a model for similar prompts.
Manual — Locks the model you choose (via the status-tray model menu or Preferences → Models). Analysis still runs; the model is not swapped.
Judge — Runs the same prompt on three capability-matched models, scores them, and lets you Prefer a winner for next time.

Prompt bar

Return — send the prompt (or run a slash command).
Shift+Return — insert a new line.
↑ / ↓ — recall recent prompts (slash commands are not stored in this history).
Paperclip — attach images or files.
Web — enable OpenRouter live web search for the next send (extra cost).
Model picker lives in the status tray (not inside the prompt field).

Slash commands

Type / in an empty prompt to open the command palette. Anything starting with / is treated as a command — unknown commands are not sent to a model.

Command	What it does
`/status`	Gateway, OpenRouter, guardrails, cache, MCP, and latest release check
`/version`	Current app version and build
`/update`	Check for a newer notarized release (or use the sidebar Update button)
`/web`	Toggle web search (`on` / `off` / `status`)
`/cache`	Session-cache size; `compact` or `clear`
`/new`	Start a new chat session
`/clear`	Clear the current transcript
`/export`	Export the session as Markdown
`/nmap`	Example prompts for the local Nmap MCP scanner
`/codescan`	Example prompts for the Semgrep code scanner
`/help`	List commands in chat
`/reset`	Delete all sessions and Learning data (asks to confirm)
`/exit`	Quit ARIL

Preferences

Subscription — OpenRouter sign-in or API key; local guardrails (sensitive-info redact, prompt-injection block).
Models — Default and per-category mappings for Auto; browse the OpenRouter catalog.
MCP — Enable managed local scanners (Nmap, Semgrep) or remote HTTP MCP servers.
General — Solo gateway, budget caps, session cache, system prompt, menu-bar icon.
Appearance — Themes including System (follows macOS).

Toolbar shortcuts open Spend analysis, Learning, Model popularity, and Log analysis.

MCP tools

Turn on Use MCP servers in Preferences → MCP, enable a server, run Check, then ask in Auto or Manual chat. Tool status can appear in the reply as Using … · …. Judge mode does not use MCP.

Nmap Scanner (local) — requires brew install nmap; only scan targets you own or are authorized to test.
Code Scanner / Semgrep (local) — requires brew install semgrep.

Managed servers store rotating bearer tokens in Application Support .env (same place as your OpenRouter key).

Sessions & projects

Create sessions from the sidebar or with /new (⌘N).
Group sessions into Projects; project search is scoped, main search is global.
Export as Markdown from the sidebar, context menu, or /export.
Local data lives under ~/Library/Application Support/ARIL/.

Updates

When a newer release is available, use the sidebar Update button or run /update. You can always download the latest DMG from aril.host or GitHub Releases.

Troubleshooting

Symptom	What to try
Gateway offline / starting…	Wait a few seconds; check Preferences → General (Solo); relaunch ARIL
API key required	Preferences → Subscription — connect OpenRouter or paste a key
Port 8741 in use	Quit other ARIL/gateway processes; relaunch
Empty chat after reinstall	History is in Application Support — restore that folder if you backed it up
Nmap / Semgrep not found	`brew install nmap` or `brew install semgrep`, then re-enable the MCP preset

More detail: INSTALL.md · FEATURES.md · GitHub Issues