168 lines
4.6 KiB
Markdown
168 lines
4.6 KiB
Markdown
# 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
|