# Quick start (https://www.lurq.run/docs/quickstart)



lurq is a **hosted service**: you don't run a database or a sync to use it. One
command installs the CLI and wires up both your terminal and every coding agent
on the machine.

<Callout type="info">
  The package ships on npm as &#x2A;*`lurqrun`** (the bare name `lurq` is taken). The command you invoke
  is still `lurq` once installed.
</Callout>

## 1. Install and set up [#1-install-and-set-up]

```bash
npx lurqrun
```

That runs the setup wizard. It offers to install `lurqrun` globally first, so
`lurq` works in any terminal without npx, then opens lurq in your browser. Sign
in (or create an account) and the browser **hands the key back to the wizard by
itself**: there is nothing to copy. If that can't work, on an SSH session or a
headless box say, the wizard prints the link and falls back to asking you to
paste a key from [Dashboard → API keys](https://www.lurq.run/dashboard/keys).

From there it does everything in one pass:

1. **Validates the key** against the hosted endpoint.
2. **Stores it** in `~/.lurq/config.json`, owner-readable only (mode `0600`).
3. **Detects your assistants**: Claude Code, Cursor, Windsurf, VS Code /
   Copilot, Codex, Gemini CLI, Antigravity, Kiro.
4. **Writes a keyed remote MCP entry** for each one, in the shape that agent
   expects (see [per-agent configuration](#per-agent-configuration)).
5. **Installs standing instructions** where the agent has a place for them, so
   the model reaches for lurq on its own rather than answering about a package
   from memory.

**No database credentials ever touch your machine.** Restart your agent afterward
so it picks up the new MCP server.

This is a per-machine step, not a per-project one. There is nothing to add to a
repo and nothing to re-run when you start a new project.

<Callout type="info">
  `lurq setup` re-runs the same wizard later, after installing a new editor or to swap in a
  different key. `lurq install` and `lurq login` are aliases for it.
</Callout>

## 2. Use it from the terminal [#2-use-it-from-the-terminal]

The stored key is what makes the CLI work anywhere, with no `LURQ_API_KEY` to
export and no database:

```bash
lurq verify jsonwebtoken
lurq evaluate zod
lurq compare date-fns dayjs moment
lurq usage zod --known 3.22.4
```

See the [CLI reference](/cli) for the full set.

## 3. Verify your agent is connected [#3-verify-your-agent-is-connected]

Ask it to add a dependency, for example:

> "Add zod to this project."

Before it installs anything, you should see it call lurq's `verify` tool, and get
back whether the package exists, its risk level and flags, and a `dataAsOf`
timestamp. To see the same answer without an agent, run `lurq verify zod`.

If the agent doesn't call lurq, confirm it was restarted and that `lurq` shows up
in its MCP tool list. More in
[troubleshooting](/plans-and-troubleshooting#my-agent-never-calls-lurq).

## From a coding agent [#from-a-coding-agent]

An AI agent can set lurq up for you. When `npx lurqrun setup` runs in an agent's
shell, where there is no terminal to prompt in, it prints a one-time sign-in link
and exits. Open the link on the same computer and sign in: lurq stores the key
and connects every detected agent in the background. The link works for 15
minutes. Restart the agent afterwards.

The sign-in has to happen on the machine the agent runs on. For a cloud or SSH
agent, use the non-interactive form below.

## Non-interactive setup [#non-interactive-setup]

For scripted setups (CI, dotfiles, provisioning), skip the prompts and the
browser:

```bash
lurq setup --yes --no-open --api-key <key>
```

Use `--agent all` to configure every detected assistant, or `--agent claude-code`
for one. With `--yes`, the key can also come from `LURQ_API_KEY`. The wizard needs
a terminal, so without one and without a key, setup uses the sign-in link above
instead, except in CI, where this form is the one to use.

## One-click install [#one-click-install]

### Claude Code plugin [#claude-code-plugin]

Inside Claude Code, no terminal needed:

```text
/plugin marketplace add jadenryu/lurq
/plugin install lurq@lurq
```

Claude Code asks for your API key once and keeps it in your system keychain.
The plugin connects the hosted MCP server and adds the lurq skill. Run
`/reload-plugins`, or restart, to load it.

### Cursor and VS Code [#cursor-and-vs-code]

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=lurq&config=eyJ1cmwiOiJodHRwczovL2FwaS5sdXJxLnJ1bi9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgPHlvdXItbHVycS1hcGkta2V5PiIsIlgtTHVycS1DbGllbnQiOiJjdXJzb3IifX0%3D">
  Add lurq to Cursor
</a>

·

<a href="vscode:mcp/install?%7B%22name%22%3A%22lurq%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.lurq.run%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%3Cyour-lurq-api-key%3E%22%2C%22X-Lurq-Client%22%3A%22copilot%22%7D%7D">
  Install lurq in VS Code
</a>

Each opens the editor with the lurq server filled in. Replace
`<your-lurq-api-key>` in the new entry with a key from
[Dashboard → API keys](https://www.lurq.run/dashboard/keys). `npx lurqrun` does
the same without the paste, and also installs standing instructions.

## Per-agent configuration [#per-agent-configuration]

Setup writes one `lurq` entry into each agent's own MCP config, merged into what
is already there. The shape differs per agent, and the wrong field name is the
most common reason a hand-written entry silently fails. Every entry points at
`https://api.lurq.run/mcp` and sends `Authorization: Bearer <your-key>`.

| Agent             | `--agent`     | MCP config file                       | Entry                                                     |
| ----------------- | ------------- | ------------------------------------- | --------------------------------------------------------- |
| Claude Code       | `claude-code` | `~/.claude.json`                      | `mcpServers.lurq`: `{ "type": "http", "url", "headers" }` |
| Cursor            | `cursor`      | `~/.cursor/mcp.json`                  | `mcpServers.lurq`: `{ "url", "headers" }`                 |
| Windsurf          | `windsurf`    | `~/.codeium/windsurf/mcp_config.json` | `mcpServers.lurq`: `{ "serverUrl", "headers" }`           |
| VS Code / Copilot | `copilot`     | `<VS Code user dir>/mcp.json`         | `servers.lurq`: `{ "type": "http", "url", "headers" }`    |
| Codex CLI         | `codex`       | `~/.codex/config.toml`                | `[mcp_servers.lurq]` with `url` and `http_headers`        |
| Gemini CLI        | `gemini-cli`  | `~/.gemini/settings.json`             | `mcpServers.lurq`: `{ "httpUrl", "headers" }`             |
| Antigravity       | `antigravity` | `~/.gemini/config/mcp_config.json`    | `mcpServers.lurq`: `{ "serverUrl", "headers" }`           |
| Kiro              | `kiro`        | `~/.kiro/settings/mcp.json`           | `mcpServers.lurq`: `{ "url", "headers" }`                 |

The VS Code user directory is `~/Library/Application Support/Code/User` on macOS,
`%APPDATA%\Code\User` on Windows, and `~/.config/Code/User` on Linux (or
`$XDG_CONFIG_HOME/Code/User`).

Standing instructions, written alongside the MCP entry:

| Agent                     | Instructions                                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| Claude Code               | `~/.claude/skills/lurq/SKILL.md`, the full guide as a skill                                     |
| Kiro                      | `~/.kiro/steering/lurq.md`, the full guide as a steering file                                   |
| Windsurf                  | a marked block in `~/.codeium/windsurf/memories/global_rules.md`                                |
| Codex CLI                 | a marked block in `~/.codex/AGENTS.md`                                                          |
| Gemini CLI, Antigravity   | a marked block in `~/.gemini/GEMINI.md`                                                         |
| Cursor, VS Code / Copilot | none: neither has a machine-wide instructions file, so the tool descriptions carry the guidance |

Every install also copies the full guide to `~/.lurq/skill-instructions.md`, as
a readable reference. Shared files are merged, never overwritten: the block sits
between `<!-- lurq:start -->` and `<!-- lurq:end -->`, and re-running setup
replaces that block and leaves everything you wrote alone.

### Installing by hand [#installing-by-hand]

If you'd rather not run the wizard, create a key on
[Dashboard → API keys](https://www.lurq.run/dashboard/keys) and add the entry to
your agent's config file yourself, merged with any servers already there.

For Claude Code, in `~/.claude.json` (and VS Code, under `servers` in its
`mcp.json`):

```json
{
  "mcpServers": {
    "lurq": {
      "type": "http",
      "url": "https://api.lurq.run/mcp",
      "headers": { "Authorization": "Bearer <your-key>" }
    }
  }
}
```

For Cursor or Kiro, drop `type`. For Windsurf or Antigravity, use `serverUrl`
instead of `url`. For Gemini CLI, use `httpUrl`: a plain `url` there means an SSE
server, and the connection never completes.

```json
{
  "mcpServers": {
    "lurq": {
      "httpUrl": "https://api.lurq.run/mcp",
      "headers": { "Authorization": "Bearer <your-key>" }
    }
  }
}
```

For Codex, append to `~/.codex/config.toml`. The headers must be the inline
`http_headers` table, not a `[mcp_servers.lurq.headers]` section, which Codex
rejects:

```toml
[mcp_servers.lurq]
url = "https://api.lurq.run/mcp"
http_headers = { Authorization = "Bearer <your-key>" }
```

For the CLI, `export LURQ_API_KEY=<your-key>` is enough. Restart the agent once
the entry is in place.

## Pointing at your own server [#pointing-at-your-own-server]

The hosted service at `api.lurq.run` is the default, not the only option. If you
run your own `lurq serve-http` (see [Self-hosting](/self-hosting)), point
setup at it:

```bash
lurq setup --url https://lurq.internal/mcp
```

Setup then issues its instructions for your server instead of ours: it won't open
our dashboard, because a key from there is one your server has never issued.
Issue the key from the operator plane of your own deployment:

```bash
npm run operator -- keys create --label my-laptop
```

The endpoint is stored alongside the key, so a later bare `lurq setup` (to wire
up a newly-installed editor, say) stays on your server. Setup always prints which
endpoint it used, so you can see at a glance where a machine points. To move back:

```bash
lurq setup --url https://api.lurq.run/mcp
```

For a one-off against a different endpoint without changing what's stored, set
`LURQ_ENDPOINT` for that command.

If you'd rather your agent talk to a local `lurq serve` over stdio against your
own Postgres, with no HTTP service at all, use `lurq install-skill --local`
instead. That path needs `DATABASE_URL` and no API key.

## What lurq sends and stores [#what-lurq-sends-and-stores]

* **Package names and versions** you ask about, and for `audit`, the dependency
  names, declared ranges and installed versions from your manifest and lockfile.
  Never source code.
* **The `need` text**, if your agent passes one to `report_outcome`, plus whether
  it went with the package and whether it built.
* **MCP scans.** With a key configured, `lurq mcp-scan` records each server's
  contract (tools, parameters, annotations, prompts, instructions) to your
  account. Credentials from `env` and `headers` are scrubbed first, and resource
  URIs are counted, not kept. `--no-upload` keeps a scan on your machine;
  `--no-contribute` stops published servers' contracts being offered to the
  public index. See [Scanning your MCP servers](/mcp-scan).
* **`check-upgrade --report`** sends that report to your dashboard. Without the
  flag, `check-upgrade` sends nothing to lurq.
* **Usage counts.** Each hosted call is counted against your account, by tool
  name and whether it succeeded, never with its arguments.

Details are in the [privacy policy](https://www.lurq.run/privacy).

## Uninstall [#uninstall]

<Callout type="info">
  `lurq uninstall` ships with the next `lurqrun` release. On an older version, use the manual steps
  below.
</Callout>

```bash
lurq uninstall                      # asks, then removes lurq from this machine
lurq uninstall --agent cursor       # just one assistant
lurq uninstall --yes                # no prompt
```

It removes the `lurq` MCP entry from each agent's config, the marked instruction
blocks and skill files setup wrote, and `~/.lurq/config.json`. Everything else in
those files stays. Then `npm uninstall -g lurqrun` removes the command itself.

`lurq logout` is not an uninstall: it only removes the key stored in
`~/.lurq/config.json`. Your agents' MCP entries still hold the key and keep
working until you remove them.

To do it by hand:

1. Delete the `lurq` entry from each agent's MCP config in
   [the table above](#per-agent-configuration): `mcpServers.lurq`,
   `servers.lurq` for VS Code, or the `[mcp_servers.lurq]` table in
   `~/.codex/config.toml`.
2. Delete `~/.claude/skills/lurq/` and `~/.kiro/steering/lurq.md`.
3. Delete the `<!-- lurq:start -->` … `<!-- lurq:end -->` block from
   `~/.gemini/GEMINI.md`, `~/.codex/AGENTS.md` and
   `~/.codeium/windsurf/memories/global_rules.md`.
4. Delete `~/.lurq/`.
5. Revoke the key on [Dashboard → API keys](https://www.lurq.run/dashboard/keys).

## Next steps [#next-steps]

* Learn what each tool does in the [MCP tools reference](/mcp-tools).
* Hit an error? See [Plans, limits & troubleshooting](/plans-and-troubleshooting).
* Curious how scores are derived? Read [How it works](/how-it-works).