For your agent: Download .md lightweightanalytics.com/docs/api.md

The lwa CLI

lwa is the Lightweight Analytics command line: register sites, pull stats and manage goals from your terminal, a script, or an AI agent. It is a single small binary for macOS, Linux and Windows that wraps the agent API, so anything the dashboard can do, lwa can do too.

Working with an agent? This whole page is also plain markdown at https://lightweightanalytics.com/docs/cli.md, and lwa docs prints it in the terminal. Point your agent at either.

Install

macOS and Linux:

curl -fsSL https://lightweightanalytics.com/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://lightweightanalytics.com/install.ps1 | iex"

The installer detects your platform, downloads the right binary and puts it on your PATH. No package manager, no runtime, no dependencies. Builds ship for macOS (Apple Silicon and Intel), Linux (x64 and arm64, so it also works inside the containers most coding agents run in) and Windows x64.

Prefer to do it by hand? Download a binary from https://lightweightanalytics.com/cli/download/<platform> where <platform> is one of osx-arm64, osx-x64, linux-x64, linux-arm64, win-x64, make it executable, and put it anywhere on your PATH. Checksums are in /cli/latest.json.

Log in once

lwa login

Paste an API key from Settings, API keys. The key is validated against the server and stored in ~/.config/lwa/config.json (%APPDATA%\lwa on Windows), readable only by your user.

For CI jobs and agents you can skip login entirely: set the LA_API_KEY environment variable, or pass --key la_... on any single command.

LA_API_KEY=la_... lwa whoami

lwa logout removes the stored key from the machine.

A quick tour

# Register a site and get its tracking snippet
lwa sites add example.com --name "My blog"

# Just the snippet (pipe it anywhere)
lwa snippet example.com

# How is it doing?
lwa stats example.com --range 7d
lwa stats breakdown example.com --by referrers --limit 20
lwa stats live example.com

# Track a conversion goal
lwa goals add example.com --name "Signup" --type url --pattern /welcome --value 4.99
lwa goals stats example.com --range thisMonth

Everywhere a command wants a <site>, a domain (example.com) or a site id (GUID) both work.

Command reference

Account

Command	What it does
`lwa login [--key la_...]`	Validate and store an API key. Without `--key` it prompts, or reads one line from stdin.
`lwa logout`	Remove the stored key from this machine.
`lwa whoami`	Account email, plan, site count, API calls today and your rate limit.

Sites

Command	What it does
`lwa sites list [--stats]`	All your sites. `--stats` adds all-time pageviews and visitors.
`lwa sites add <domain> [--name <label>] [--no-cookie] [--live-pings]`	Register a site and print its tracking snippet. High accuracy mode (cookie) is on by default; `--no-cookie` turns it off.
`lwa sites get <site>`	One site's settings, all-time numbers and snippet.
`lwa sites update <site> [--name <label>] [--cookie on\\|off] [--live-pings on\\|off]`	Change settings. Changing them changes the snippet, which the command prints.
`lwa sites remove <site> --confirm <domain>`	Unregister a site and delete all of its analytics data. The domain must be repeated via `--confirm` (interactive runs prompt for it). There is no undo.
`lwa snippet <site>`	Print only the tracking snippet.

Stats

Command	What it does
`lwa stats <site>`	Traffic summary: pageviews, visitors, sessions, bounce rate, session length, new vs returning, live count. Alias for `lwa stats summary`.
`lwa stats timeseries <site> [--bucket auto\\|hour\\|day]`	Pageviews and visitors per day (or per hour), zero-filled.
`lwa stats breakdown <site> --by <dimension> [--limit 1..100]`	Top items for a dimension: `pages`, `referrers`, `countries`, `browsers`, `devices`, `os`, `languages`, `resolutions`, `hosts`, `campaigns`. Campaign data always covers the last 30 days.
`lwa stats live <site>`	Visitors on the site right now.

Summary, timeseries and breakdown accept a time range:

--range with today, yesterday, 7d, 30d (the default), 90d, 365d, thisMonth, lastMonth, thisYear, all
or explicit dates: --from 2026-07-01 --to 2026-07-31
--dev switches to non-production traffic (localhost and staging hosts)

Goals

Command	What it does
`lwa goals list <site>`	Goal definitions with their ids.
`lwa goals add <site> --name <name> [--type manual\\|click\\|url] [--match contains\\|starts\\|regex] [--pattern <p>] [--value <amount>]`	Create a goal. `url` goals need `--pattern`. `--value` is the default value per conversion, like `--value 4.99`.
`lwa goals update <goal-id> [...]`	Change any of the same fields.
`lwa goals remove <goal-id> [--keep-events] [--yes]`	Delete a goal. Recorded conversions are purged too unless `--keep-events`. Non-interactive runs must pass `--yes`.
`lwa goals stats <site> [range options]`	Conversions, revenue and average value per goal.

Utility

Command	What it does
`lwa docs [--api]`	Print this reference as markdown. `--api` prints the full HTTP API reference instead.
`lwa update [--check]`	Self-update to the latest version (checksum verified). `--check` only reports.
`lwa version`	Version and platform.
`lwa <command> --help`	Detailed help with examples for any command group.

Options that work everywhere

Option	What it does
`--json`	Print the raw API response instead of tables. The shapes match the API reference exactly.
`--key <la_...>`	Use a key for this one call, overriding login and environment.
`--server <url>`	Talk to a different server (self-hosted or staging).

Environment variables: LA_API_KEY (key, overrides the stored login) and LA_SERVER (server URL).

Notes for agents

Add --json to any command to get the exact API response, ready to parse.
Exit codes are stable: 0 success, 1 API or network error, 2 usage error. Errors go to stderr as error (code): message using the same error codes as the HTTP API.
Destructive commands never rely on prompts when input is piped: sites remove requires --confirm <domain>, goals remove requires --yes. Without them the command fails safely and tells you what to pass.
Rate limits are generous (600 requests/minute per key). If you do hit a 429 the CLI waits and retries once on its own.
lwa docs and lwa docs --api give you the full references offline, no HTML to scrape.

Updating and uninstalling

lwa update replaces the binary in place after verifying its checksum against /cli/latest.json. Nothing runs in the background and the CLI never phones home on its own; update checks happen only when you run lwa update.

To uninstall, delete the binary (which lwa shows where it is) and, if you want, the config folder ~/.config/lwa (Windows: %APPDATA%\lwa).

Troubleshooting

lwa: command not found right after installing: the install directory is not on your PATH. The installer prints the exact line to add to your shell profile. On Windows, open a new terminal so the updated PATH is picked up.
invalid_api_key: the key was revoked or mistyped. Check Settings, API keys and run lwa login again.
subscription_required: the account behind the key has no active subscription. Visit the pricing page to re-activate.
lwa update says no permission: the binary lives in a system directory. Re-run as sudo lwa update, or re-install to a user directory with LWA_INSTALL_DIR.