# The Lune command line app

The Lune command line app installs the Lune MCP server in supported local
agents. It also handles sign-in and teams from a terminal, can create access
keys, and reports on its own setup.

The command line app is optional. Research belongs in your AI agent, where
Lune's MCP tools run; the command line app's own lookups are for quick checks.

## Install it

```sh
npm install -g @retrograde-labs/lune-cli
```

It needs Node.js 22.12 or later. If you don't have Node, install it from
[nodejs.org](https://nodejs.org) or your package manager.

## Sign in

```sh
lune login
```

This opens a browser tab where you sign in with your Lune account. The command
line app keeps the sign-in. You sign in again only after `lune logout`, for a
new `--profile`, or after 90 days without use. To sign in with an access key
instead, run `lune login --api-key lune_your_access_key`.

```sh
lune whoami
```

Shows the team your sign-in bills (your personal team after a browser sign-in),
its plan, today's requests against the daily allowance, your credit balance,
and how you signed in. It needs the `account:read` scope, which a browser
sign-in and a key made with the default scopes both carry.

## Connect Lune to a local AI agent

The command line app writes the MCP config for these agents in one step:

```sh
lune install --client claude-code
lune install --client cursor
lune install --client vscode
lune install --client codex
lune install --client opencode
```

Sign in with `lune login` first. Run `lune install` with no flag to pick from a
list. It asks whether to create a new access key or use one you already have. A
new key goes to the team you choose (the question comes up only if you belong
to more than one) and carries the four default scopes. The key then goes into
the agent's configuration file. If you signed in with an access key, the
install reuses that key.

Some apps connect through their own interface instead, like Claude Desktop,
Perplexity, and Manus. For those, the command prints a link to the matching
recipe on the dashboard:

```sh
lune install --client claude-desktop
```

To remove Lune from an agent later:

```sh
lune uninstall --client cursor
```

For apps set up inside the app itself, `lune uninstall` points you to the
Credentials page to revoke the key or the connected app.

## Use Lune in the connected agent

After installation, open the local agent and ask it to search papers, read full
text, trace citations, compare methods, verify claims, or find research
guidance. The agent picks the Lune tools on its own.

For a quick check without an agent:

```sh
lune papers search "diffusion model guidance"
lune guidance search "how to design an ablation"
```

Each lookup counts against your daily allowance, like the matching tool call.

## Manage your account

```sh
lune teams list                  # all teams you belong to
lune teams use <slug>            # the team lune keys create uses
lune teams current               # show that team

lune keys create --name laptop   # create an access key (shown once)
```

`lune keys create` takes `--scopes` and `--expires` to choose the key's scopes
and expiry date. It needs a browser sign-in: a session signed in with an access
key can't create keys. To list or revoke keys, use the
[Credentials page](https://luneresearch.com/dashboard/settings/credentials).

## Multiple identities

If you use Lune for both personal and team work, the `--profile` flag keeps
them apart.

```sh
lune --profile work login
lune --profile work teams use acme
lune --profile work keys create --name work-laptop
```

Without `--profile`, the command line app uses `default`. Each profile has its
own sign-in and its own team for `lune keys create`. A browser sign-in always
bills your personal team, whichever team the profile has selected. To bill a
shared team from the command line, sign that profile in with an access key
created in the team.

## Diagnostics

```sh
lune doctor
```

Prints the version and profile, whether a sign-in is saved and which kind, the
profile's team, whether Lune's service answers, and each agent it detects,
with the config file `lune install` would write for it. It doesn't check that
the saved sign-in still works, and it doesn't test the MCP connection. To test
the connection, use the check in
[Troubleshooting](https://luneresearch.com/docs/troubleshooting#test-the-connection-by-hand).