# Arial

> Agent-native product analytics for coding agents. Arial gives your agent a canonical event taxonomy, a typed CLI and HTTP API for metric and funnel queries, and cross-company benchmarks — structured data, not chart screenshots. Built for Claude Code, Codex, Gemini.

## Quickstart

If you are a coding agent setting up Arial inside an existing project, run from the project root:

```
npx @arial-ai/cli init
```

`arial init` signs up a workspace, writes `arial.json` (non-secret, contains `workspaceId`), installs `@arial-ai/sdk` via the project's package manager, appends `ARIAL_WRITE_KEY` to `.env.local`, ensures `.env.local` is gitignored, saves the agent key to `~/.config/arial/config.json` (or `$XDG_CONFIG_HOME/arial/config.json`; override with `ARIAL_CONFIG_DIR`), and prints a `claimUrl` + `claimPassphrase` you should hand to the human so they can take ownership.

After init, run `arial agent-stanza >> AGENTS.md` to append a short markdown section that teaches any agent in the repo how to use Arial.

If you only need credentials (no project scaffolding), use `npx @arial-ai/cli signup` instead — it's the lower-level primitive that `init` calls under the hood.

Then read [/docs](https://arial.sh/docs) (or [/llms-full.txt](https://arial.sh/llms-full.txt) for everything in one fetch) for how to instrument events and query analytics.

## Everything in one fetch

- [llms-full.txt](https://arial.sh/llms-full.txt): This file, plus the full docs, plus the canonical taxonomy — concatenated. Fetch once, act.

## Landing

- [Landing](https://arial.sh/): Overview of Arial for humans and agents.

## Docs

- [Docs (markdown)](https://arial.sh/docs.md): Self-contained reference as pure `text/markdown` — no HTML wrapper. Prefer this for programmatic fetches.
- [Docs (HTML)](https://arial.sh/docs): Same content, HTML-rendered. `/docs?view=human` for the styled human view.

## Taxonomy

- [Catalogue (JSON)](https://arial.sh/docs/taxonomy.json): Machine-readable canonical event taxonomy. Names, sources, property schemas. Derived from the validation source so it never drifts.
- [Catalogue (text)](https://arial.sh/docs/taxonomy.txt): Plain-text rendering of the same catalogue. Use whichever your agent prefers.

## Discovery

- [API schema](https://api.arial.sh/v1/schema): Unauthenticated machine-readable self-description of the control-plane API — every endpoint with summary, auth, and docs pointer. Start here if you've discovered Arial and need to know the full surface before making authenticated calls.

## Query API

- [Metric catalogue](https://api.arial.sh/v1/metrics): Every metric definition (id, description, granularities, allowed segments). Requires `Authorization: Bearer agk_...`.
- [Metric detail](https://api.arial.sh/v1/metrics/dau): Computed values for one metric — series, summary, natural-language interpretation, suggested follow-up queries. Takes `from`, `to`, `granularity`, `segment_by` query params.
- [Funnel catalogue](https://api.arial.sh/v1/funnels): Every funnel definition (id, step list, default window, allowed segments).
- [Funnel detail](https://api.arial.sh/v1/funnels/signup_to_activation): Computed per-step conversions for one funnel — aggregate steps, per-bucket cohorts with ready/pending status, interpretation, suggested follow-ups. Takes `from`, `to`, `granularity` query params.
- [Events tail](https://api.arial.sh/v1/events): Most recent events received for your workspace, newest first. Verification surface — use after firing events to confirm payloads landed with the expected shape. Takes optional `limit` (default 50, max 200).
- CLI: `arial metrics list`, `arial metrics get <id>`, `arial funnels list`, `arial funnels get <id>`, `arial events list` — structured JSON envelope with `--json`.

## Experiments

Experiments are the attribution primitive of Arial's growth loop — the agent registers an experiment when it opens a PR; the analytics SDK assigns sticky variants; a daily readout joins exposures with the canonical target metric. M0: two arms (control + treatment), 50/50 fixed allocation, derived conversions, explicit conclusions.

- [Experiments list](https://api.arial.sh/v1/experiments): Every experiment in the workspace, newest first. Requires `Authorization: Bearer agk_...`.
- [Experiment detail](https://api.arial.sh/v1/experiments/checkout-cta-copy): One experiment by key, with the most recent readout inline (per-variant exposures + conversions, control vs treatment rates, absolute and relative lift, 95% Newcombe-Wilson CI, p-value, recommendation).
- [Experiment snapshot](https://api.arial.sh/v1/experiments/checkout-cta-copy/snapshot): Point-in-time stats with source, observedLeader, confidenceLabel, exposures, conversions, rates, lift, p-value, and recommendation. Running experiments compute from live events without persisting anything; concluded experiments prefer the latest persisted readout.
- Register: `POST /v1/experiments` with `{ key, hypothesis, targetMetric (canonical event name only), mde }`.
- Conclude: `POST /v1/experiments/:key/conclude` with `{ decision: "ship" | "revert" }`. One-way.
- Wrap variants in your code with `arial.variant(key, { fallback: "control" })` from `@arial-ai/sdk`.
- CLI: `arial experiment list`, `arial experiment get <key>`, `arial experiment create --key <slug> --target <event> --mde 0.05 --hypothesis "..."`, `arial experiment readout <key>`, `arial experiment snapshot <key>`, `arial experiment conclude <key> --decision ship|revert`.

## Flag config

The analytics SDK polls a small write-key-authenticated endpoint for running experiments so `arial.variant()` stays local and deterministic. You only touch this directly if you're implementing your own SDK.

- `GET https://flags.arial.sh/v1/flags`: Slim `{ workspaceId, etag, experiments[{ key, assignmentUnit, variants[{ variantId, weight }] }] }` body. Auth: `Authorization: Bearer wk_...` (write key, same as ingest). Honors `If-None-Match` → `304`. Only `running` experiments appear; concluded ones are dropped so stale SDKs stop re-exposing.

## Packages

- [@arial-ai/cli (npm)](https://www.npmjs.com/package/@arial-ai/cli): Project init, signup, authenticated reads, scriptable with `--json`. Install with `npm install -g @arial-ai/cli` or invoke directly via `npx @arial-ai/cli`. Top-level commands: `init` (one-shot project bootstrap), `signup`, `login`, `whoami`, `workspace`, `taxonomy`, `events`, `metrics`, `funnels`, `reports`, `experiment`, `agent-stanza`.
- [@arial-ai/sdk (npm)](https://www.npmjs.com/package/@arial-ai/sdk): Typed event SDK with batching, retry, client-side taxonomy validation. Node 20+, Bun, Deno, browsers, Cloudflare Workers, Vercel Edge.

## Product

- [Sign up](https://arial.sh/signup): Join the waitlist.
- [Log in](https://arial.sh/login): Existing users.