> ## Documentation Index
> Fetch the complete documentation index at: https://rapidreview.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Nisa from a coding agent

> The contract between the nisa CLI and a coding agent: output, concurrency, structured answers, headless mode, and your local files.

Nisa integrates as a subprocess CLI plus a skill file (`nisa-cli`). There is no MCP server. This page is the working contract once the skill is installed; the per-agent setup is on the [Install page](/docs/nisa/start/install#give-your-coding-agent-the-skill).

<Steps>
  <Step title="Install the CLI and the skill">
    One download into your agent's skills folder — the per-agent paths for Claude Code, Codex, Cursor, Copilot CLI, Gemini CLI, Qwen Code, OpenCode, Kilo Code, Hermes Agent, OpenHands, and Replit Agent are on the [Install page](/docs/nisa/start/install#give-your-coding-agent-the-skill). For Claude Code:

    ```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    curl -sSL https://api.rapidreview.io/cli/install | bash
    mkdir -p ~/.claude/skills/nisa-cli
    curl -sSL https://api.rapidreview.io/cli/skill -o ~/.claude/skills/nisa-cli/SKILL.md
    ```

    The skill is public and edge-cached (\~5 min) — safe to refetch on every start; it also carries the local-tool write contract (read before edit, error codes) and the recipes. Downloads: [SKILL.md](https://api.rapidreview.io/cli/skill?dl=1) · [install.sh](https://api.rapidreview.io/cli/install?dl=1). A self-healing guard the skill itself uses:

    ```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    command -v nisa >/dev/null 2>&1 || { curl -sSL https://api.rapidreview.io/cli/install | bash; export PATH="$HOME/.local/bin:$PATH"; }
    ```
  </Step>

  <Step title="Give it a key">
    On the machine where you signed in through the chat's browser flow, nothing to do: that flow stored a long-lived key in `~/.nisa/credentials.json` and agents pick it up. Anywhere else, mint a named key and export it:

    ```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    nisa login                          # once, as a human; OAuth must be the credential in use
    nisa keys create "claude-code"      # prints rr_sk_… exactly once
    export RAPIDREVIEW_KEY="rr_sk_..."
    ```

    Or create it in the web app under **Settings → API Keys** — the path that always works (a key can't manage keys: `403 API key management requires browser login`). Keys are the only supported agent-mode auth: no refresh, no rotation, parallel-safe. Don't share your OAuth credentials file with parallel agents — refresh tokens are one-shot. (The Python SDK reads `RAPIDREVIEW_API_KEY`, a different variable.)
  </Step>

  <Step title="Run headless">
    ```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
    nisa --headless --envelope search --query "state space models" --query "Mamba" --max-results 20
    nisa --headless ask --timeout 120 "Find recent work on retrieval reranking."
    ```

    <Check>`--headless` disables every prompt; `--envelope` wraps direct-command JSON as `{meta, data}`.</Check>
  </Step>
</Steps>

## Contract for the agent

| Rule                | Detail                                                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Output              | stdout = payload; stderr = session id, usage, errors. Parse stdout only                                                                           |
| Chat-backed JSON    | Always `ok`, `session_id`, `answer`, `arxiv_ids`, `tokens.cost_usd`, `duration_ms` — on failure too. Check the exit code, then `ok`               |
| Order of preference | Direct first (`search`, `paper`, `related`, `excerpts`, `cite`); `ask` for judgment. Multi-query `search` beats one clever query                  |
| Concurrency         | Direct: fan out freely. Chat-backed: 10/min · 100/hr per machine, and the backend can't yet serve many concurrent turns — `ask-batch`, not a loop |
| Structured answers  | `ask --schema '{"relevant":"boolean","reason":"string"}'`                                                                                         |
| Not for             | General web search, non-arXiv sources, editing the user's own paper                                                                               |
| Diagnose            | `nisa doctor --json`                                                                                                                              |

| Code  | Meaning                                                                      |
| ----- | ---------------------------------------------------------------------------- |
| `0`   | success                                                                      |
| `1`   | error — bad input, rate-limit trip, or no credential in headless mode        |
| `124` | `--timeout` reached; a partial answer is still returned and the session kept |
| `130` | interrupted with Ctrl-C                                                      |
| `141` | broken pipe (e.g. `\| head`); exits silently                                 |

## Give it your files

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
nisa exec --workspace ./papers "Summarize the three PDFs here against arXiv:2401.12345"
nisa exec --workspace ./papers --allow-writes "Write notes.md with the comparison"
```

Read tools by default; `--allow-writes` adds file edits; `--allow-exec` adds `shell.exec` (60 s default, credential-shaped env scrubbed, cwd clamped — not a sandbox). For a browser-driven session use the bridge: [Local folder access](/docs/nisa/guides/connect-a-folder). Registering what you find in Merv: [Using Nisa with Merv](/docs/nisa/guides/with-merv).