---
title: CLI
description: The llmentions command-line tool — every command maps 1:1 to a REST endpoint and an MCP tool.
group: Interfaces
---

# CLI

The `llmentions` CLI is a thin client over the REST API. Every command maps to an endpoint and an MCP tool, and `--json` prints the raw response for scripts and agents.

> Prebuilt binaries ship with the public launch. Until then, build the CLI from source with `cargo install --path crates/cli`.

## Auth

```bash
llmentions login                  # opens your browser to sign in, confirms a one-time code, saves the key
llmentions login --key sk_live_…  # headless: use a key you already have (or pipe it on stdin)
llmentions account                # workspace, mode, balance, engines
llmentions logout
```

`llmentions login` uses a device-code flow: the CLI prints a short code and opens [api.llmentions.com/login](https://api.llmentions.com/login), you sign in with Google, GitHub or email, confirm the code, and the key is saved to `~/.config/llmentions` (mode `0600`). On a server with no browser, open the printed URL on any device.

Key precedence is flags, then the environment (`LLMENTIONS_API_KEY`, `LLMENTIONS_API_URL`), then the config file.

## Output

By default you get readable tables. Add `--json` to any command for the raw API envelope, so the CLI composes with `jq`, scripts and agents. Exit codes: `0` on success, `1` on an error or when a `--fail-on` condition trips, `2` on invalid arguments.

## Commands

| Command | Does | API |
|---|---|---|
| `llmentions ask "<prompt>"… [--brand B --domain D --competitor C] [-n N] [--engines a,b] [--dry-run]` | Ask engines now, print the answers or a mention report | `POST /v1/ai/answers` |
| `llmentions projects` | List projects | `GET /v1/projects` |
| `llmentions projects create <brand> --domain D [--competitor C]… [--prompt P]…` | Create a project | `POST /v1/projects` |
| `llmentions track <project> --add P --remove P` | Change tracked prompts | `POST /v1/projects/{p}/prompts` |
| `llmentions run <project> [-n N] [--engines …] [--queued] [--webhook URL] [--dry-run] [--no-wait]` | Start a panel, wait, print the report | `POST /v1/visibility/runs` |
| `llmentions job <id>` | Job status and report | `GET /v1/jobs/{id}` |
| `llmentions report <project> [--all]` | Latest report vs the previous run | `GET /v1/projects/{p}/visibility` |
| `llmentions answers <project> [--missing] [--engine E] [--brand B] [-q text]` | Read stored answers | `GET /v1/projects/{p}/answers` |
| `llmentions analyze <project> [--all] [--force] [--dry-run]` | Sentiment, recommended vs listed, and claims per brand | `POST /v1/projects/{p}/analyze` |
| `llmentions suggest --category "…" [--project P \| --brand B] [-n N] [--track]` | Research the buyer questions worth tracking | `POST /v1/prompts/suggest` |
| `llmentions audit <site> [--max-pages N] [--render N] [--fail-on error\|warning\|regression] [--pages]` | Can AI answer engines read your site, and what's in the way? Shows what changed since the last audit. `--fail-on` exits 1 for CI | `POST /v1/site/audit` |
| `llmentions audits <id \| site>` | A stored audit and what changed since the previous one | `GET /v1/site/audits/{audit}` |
| `llmentions bots <access.log \| ->` | Which search and AI bots visit, from server logs, with fake bots flagged by IP | `POST /v1/bots/report` |
| `llmentions keys list \| create <name> [--test] \| revoke <id>` | Manage API keys | `/v1/keys` |
| `llmentions prices` | Public price list | `GET /v1/prices` |
| `llmentions engines` | Engines configured locally | (local) |

## In CI (GitHub Actions)

Fail a pull request when the site, or its preview deploy, stops being readable by AI:

```yaml
- uses: williamrogersdev/llmentions@main
  with:
    site: ${{ steps.deploy.outputs.url }}   # or example.com
    api-key: ${{ secrets.LLMENTIONS_API_KEY }}
    fail-on: regression                     # or: error, warning, none
```

The audit is printed to the job summary. Test keys (`sk_test_…`) audit for free.

## Run locally with your own keys

`--local` runs the same panel code on your machine, using provider keys from `.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `PERPLEXITY_API_KEY`, `XAI_API_KEY`, `DEEPSEEK_API_KEY`, `DASHSCOPE_API_KEY`, `MOONSHOT_API_KEY`, `DATAFORSEO_LOGIN`/`DATAFORSEO_PASSWORD`). You pay the providers directly. `--mock` uses demo engines and needs no keys.

```bash
llmentions ask "best crm for startups" --brand Acme --local -n 5
llmentions ask "best crm for startups" --brand Acme --mock
```
