# Cursor CLI & IDE Guide

Cursor is an AI-first code editor (fork of VS Code) with deep agent, inline edit, and multi-file reasoning capabilities. It runs as a desktop IDE with a companion CLI for opening projects from the terminal.

**Official docs:** https://docs.cursor.com
**Download:** https://www.cursor.com/download

---

## Installation

```bash
# macOS (download .dmg from cursor.com, or via Homebrew)
brew install --cask cursor

# The `cursor` CLI is installed automatically with the desktop app
# macOS: add to PATH via Command Palette → "Install 'cursor' command in PATH"
```

**Installed on:** Tabitha (and any machine with Cursor desktop app)

---

## CLI Usage

```bash
# Open current directory in Cursor
cursor .

# Open a specific file or folder
cursor /path/to/project
cursor src/components/Button.tsx

# Open a Gitea-cloned repo
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cursor aarete-doczyai-app/

# Reuse existing window
cursor --reuse-window .

# New window
cursor --new-window .
```

---

## Agent Mode

Cursor's Agent mode (formerly Composer) lets you give multi-step tasks in natural language. It reads and edits across files, runs terminal commands, and can loop until the task is done.

**Open Agent:** `Cmd+I` (or `Ctrl+I` on Windows/Linux)

```
# Example agent prompts:
"Add form validation to the login page and write tests for it"
"Refactor the API calls to use a centralized fetch wrapper"
"Fix all TypeScript errors in the project"
```

---

## Inline Edit

Quick single-location edits without opening Agent:

**Trigger:** `Cmd+K` on selected code

```
# Example inline prompts:
"Add error handling"
"Convert to async/await"
"Add JSDoc comment"
```

---

## Rules (Project Instructions)

Cursor reads `.cursorrules` (legacy) or `cursor/rules/` directory for project-specific AI instructions. These persist across sessions and shape how the AI behaves in your codebase.

**Create `.cursorrules` at project root:**
```
# aarete-doczyai-app Cursor Rules

- TypeScript strict mode is required
- Use React functional components with hooks only
- API calls go through lib/api — never fetch() directly in components
- Run `npm run lint && npm run test:ci` before considering a task done
- This project is on a local Gitea: http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app
```

---

## MCP in Cursor

Cursor supports MCP servers for extending AI capabilities. Configure in `~/.cursor/mcp.json` or via Settings → MCP.

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-pat>" }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://postgres:pass@127.0.0.1:5432/silma"]
    }
  }
}
```

---

## Using Local LLMs in Cursor

Cursor supports custom OpenAI-compatible model endpoints:

1. Open **Settings → Models → Add Model**
2. Set base URL to `http://localhost:8080/v1` (Gemma-4-E4B) or `http://localhost:8081/v1` (Gemma-4-26B)
3. Set API key to `local` (required but ignored by llama.cpp)
4. Name the model `gemma-4-e4b` or `gemma-4-26b`

See `tools/local-llm.llm.md` for full local LLM details and endpoints.

---

## Useful Keyboard Shortcuts

| Action | macOS | Windows/Linux |
|--------|-------|---------------|
| Open Agent | `Cmd+I` | `Ctrl+I` |
| Inline Edit | `Cmd+K` | `Ctrl+K` |
| Chat panel | `Cmd+L` | `Ctrl+L` |
| Command Palette | `Cmd+Shift+P` | `Ctrl+Shift+P` |
| Terminal | `` Ctrl+` `` | `` Ctrl+` `` |
| File search | `Cmd+P` | `Ctrl+P` |
| Symbol search | `Cmd+T` | `Ctrl+T` |

---

## Working with Gitea Repos in Cursor

```bash
# Clone from local Gitea
git clone http://jacob-mathison:<PAT>@100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cursor aarete-doczyai-app/

# Or clone first, configure remote without PAT in URL
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cd aarete-doczyai-app
git config credential.helper store
cursor .
```

Cursor's Source Control panel works with local Gitea repos the same as GitHub — commit, push, pull, branch all work normally.

---

## Tips for This Environment

- The Claude Code extension for Cursor is available: search "Claude Code" in Extensions (`Cmd+Shift+X`)
- For AI-heavy tasks, Agent mode + a good `.cursorrules` file beats ad-hoc prompts every time
- Cursor indexes your codebase on first open — give it a minute on large repos
- Use `@file`, `@folder`, `@symbol` mentions in Agent to scope context precisely
- `@docs` lets you pull in external documentation URLs as context mid-chat