Quick start

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.

1. Install and set up

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.

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).
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.

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:

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

See the CLI reference for the full set.

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.

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

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

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

Claude Code plugin

Inside Claude Code, no terminal needed:

/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

·

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. npx lurqrun does the same without the paste, and also installs standing instructions.

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>.

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:

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

If you'd rather not run the wizard, create a key on Dashboard → API 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):

{
  "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.

{
  "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:

[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

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), point setup at it:

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:

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:

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

• 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.
• 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.

Uninstall

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: 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.

Next steps

• Learn what each tool does in the MCP tools reference.
• Hit an error? See Plans, limits & troubleshooting.
• Curious how scores are derived? Read How it works.