{
  "id": "cursor-cli",
  "name": "Cursor CLI",
  "vendor": "Cursor",
  "tagline": "Cursor's AI coding agent, run directly from your terminal.",
  "subtitle": "terminal reference",
  "docsHome": "https://cursor.com/docs/cli/overview",
  "lastVerified": "2026-07-11",
  "stale": false,
  "accent": "#a78bfa",
  "headerNote": "The binary is `agent`, not `cursor`. The source of truth is [cursor.com/docs/cli](https://cursor.com/docs/cli/overview), and inside a session `/help` and `/about` show what *your* build has.",
  "footerNote": "Availability varies by plan and version; run `agent --version` and `agent about` to see what your build has.",
  "sections": [
    {
      "id": "launch",
      "title": "Launch & sessions",
      "lede": "Everything you can type before you're in a session. Fresh installs auto-update by default.",
      "sources": [
        "https://cursor.com/docs/cli/overview.md",
        "https://cursor.com/docs/cli/installation.md",
        "https://cursor.com/docs/cli/using.md",
        "https://cursor.com/docs/cli/reference/parameters.md",
        "https://cursor.com/docs/cli/reference/authentication.md"
      ],
      "groups": [
        {
          "title": "Install & run",
          "rows": [
            {
              "cmd": "curl https://cursor.com/install -fsS | bash",
              "desc": "Install on macOS, Linux, WSL. Windows PowerShell: `irm 'https://cursor.com/install?win32=true' | iex`. Add `~/.local/bin` to PATH."
            },
            {
              "cmd": "agent",
              "desc": "Start an interactive session in the current directory. Agent mode is the default."
            },
            {
              "cmd": "agent \"prompt\"",
              "desc": "Start interactive with an initial prompt."
            },
            {
              "cmd": "agent -p \"prompt\"",
              "desc": "Non-interactive print mode — the scripting entry point. See the headless section."
            },
            {
              "cmd": "agent update",
              "desc": "Update to the latest version manually (the CLI also auto-updates). In-session: `/update`."
            },
            {
              "cmd": "agent --version | agent about",
              "desc": "Installed version / version, system, and account info. `about --format json` for scripting."
            },
            {
              "cmd": "agent models | agent --list-models",
              "desc": "List the models available to this account."
            },
            {
              "cmd": "agent generate-rule",
              "desc": "Generate a new Cursor rule with interactive prompts. Alias `agent rule`."
            },
            {
              "cmd": "agent install-shell-integration",
              "desc": "Install shell integration into `~/.zshrc` (`uninstall-shell-integration` removes it)."
            }
          ]
        },
        {
          "title": "Sessions",
          "rows": [
            {
              "cmd": "agent ls",
              "desc": "Open previous chats and resume one — all workspaces by default, ←/→ narrows to this one."
            },
            {
              "cmd": "agent resume | agent --continue",
              "desc": "Resume the latest conversation (`--continue` is an alias for `--resume=-1`)."
            },
            {
              "cmd": "agent --resume=\"<chat-id>\"",
              "desc": "Resume a specific conversation by id."
            },
            {
              "cmd": "agent create-chat",
              "desc": "Create a new empty chat and print its ID — pairs with `--resume` in scripts."
            },
            {
              "cmd": "agent -w, --worktree [name]",
              "desc": "Run in a fresh git worktree under `~/.cursor/worktrees/<repo>/<name>`. `--worktree-base <ref>` picks the base; `--skip-worktree-setup` skips `.cursor/worktrees.json` scripts."
            },
            {
              "cmd": "agent worker start",
              "desc": "Start a private cloud worker that runs agents in your environment. `agent worker debug` runs preflight diagnostics."
            }
          ]
        },
        {
          "title": "Auth",
          "rows": [
            {
              "cmd": "agent login | logout",
              "desc": "Browser OAuth flow / sign out. `NO_OPEN_BROWSER=1` prints the URL instead; press <kbd>q</kbd> for a QR code over SSH."
            },
            {
              "cmd": "agent status | whoami",
              "desc": "Authentication status, account, endpoint. `--format json` for scripting."
            },
            {
              "cmd": "CURSOR_API_KEY=… | --api-key <key>",
              "desc": "API-key auth for CI and scripts. Generate keys in the Cursor dashboard under API Keys."
            }
          ]
        }
      ]
    },
    {
      "id": "flags",
      "title": "CLI flags",
      "navLabel": "Flags",
      "sources": [
        "https://cursor.com/docs/cli/reference/parameters.md",
        "https://cursor.com/docs/cli/using.md",
        "https://cursor.com/docs/cli/changelog.md"
      ],
      "groups": [
        {
          "rows": [
            {
              "cmd": "-p, --print",
              "desc": "Print responses to console for scripts and non-interactive use. Also inferred on non-TTY stdout or piped stdin."
            },
            {
              "cmd": "--output-format text|json|stream-json",
              "desc": "Print-mode output shape (default `text`)."
            },
            {
              "cmd": "--stream-partial-output",
              "desc": "Stream text deltas as they generate. Needs `--print --output-format stream-json`."
            },
            {
              "cmd": "--model <model>",
              "desc": "Model for the session. `--list-models` shows what your account can use."
            },
            {
              "cmd": "--mode plan|ask  |  --plan",
              "desc": "Start in Plan or Ask mode. Agent mode is the default when no mode is given."
            },
            {
              "cmd": "-f, --force",
              "desc": "Force-allow commands unless explicitly denied. Required for file edits in print mode.",
              "danger": true
            },
            {
              "cmd": "--yolo",
              "desc": "Alias for `--force`.",
              "danger": true
            },
            {
              "cmd": "--sandbox enabled|disabled",
              "desc": "Set sandbox mode for command execution. Settings persist across sessions."
            },
            {
              "cmd": "--approve-mcps",
              "desc": "Automatically approve all MCP servers.",
              "danger": true
            },
            {
              "cmd": "--trust",
              "desc": "Trust the workspace without prompting (headless mode only).",
              "danger": true
            },
            {
              "cmd": "--workspace <path>",
              "desc": "Explicit repository root; otherwise the current working directory."
            },
            {
              "cmd": "--add-dir <path>",
              "desc": "Add extra directories at launch for a multi-root session. Repeatable; in-session `/add-dir`."
            },
            {
              "cmd": "--plugin-dir <path>",
              "desc": "Load a local plugin directory for this session. Repeatable."
            },
            {
              "cmd": "-H, --header \"Name: Value\"",
              "desc": "Add a custom header to agent requests. Repeatable."
            },
            {
              "cmd": "--api-key <key>  |  -v  |  -h",
              "desc": "API key / version / help. Every command and subcommand accepts `-h`."
            }
          ]
        }
      ]
    },
    {
      "id": "slash",
      "title": "Slash commands",
      "navLabel": "Slash commands",
      "lede": "Typed inside a session. `/help <command>` shows details for any of them.",
      "sources": [
        "https://cursor.com/docs/cli/reference/slash-commands.md",
        "https://cursor.com/docs/cli/changelog.md"
      ],
      "groups": [
        {
          "title": "Modes & models",
          "rows": [
            {
              "cmd": "/model [filter]",
              "desc": "Select a model; <kbd>Tab</kbd> to edit. Family shortcuts like `/opus` and `/composer` jump straight to a model; `/fast` toggles Fast where supported."
            },
            {
              "cmd": "/plan [prompt]",
              "desc": "Switch to Plan mode, show the current plan, or submit a prompt in Plan mode."
            },
            {
              "cmd": "/ask",
              "desc": "Toggle Ask mode — read-only questions, no file edits."
            },
            {
              "cmd": "/debug [prompt]",
              "desc": "Toggle Debug mode or submit a prompt in it."
            },
            {
              "cmd": "/max-mode",
              "desc": "Toggle Max Mode on models that support it."
            },
            {
              "cmd": "/run-everything [on|off|status]",
              "desc": "Toggle Run Everything or show its status. Alias `/auto-run`.",
              "danger": true
            }
          ]
        },
        {
          "title": "Session",
          "rows": [
            {
              "cmd": "/clear",
              "desc": "Start a new chat session. Aliases `/new`, `/new-chat`, `/newchat`."
            },
            {
              "cmd": "/resume",
              "desc": "Open recent chats and resume one."
            },
            {
              "cmd": "/fork",
              "desc": "Fork the current chat into a new session."
            },
            {
              "cmd": "/rename <name>",
              "desc": "Rename the current chat session."
            },
            {
              "cmd": "/summarize",
              "desc": "Summarize the conversation to reduce context. Alias `/compress`."
            },
            {
              "cmd": "/rewind",
              "desc": "Jump back to a previous message."
            },
            {
              "cmd": "/copy",
              "desc": "Copy a previous user message to the clipboard."
            },
            {
              "cmd": "/copy-request-id | /copy-conversation-id",
              "desc": "Copy the last request ID / current conversation ID."
            },
            {
              "cmd": "/quit | /exit",
              "desc": "Exit."
            }
          ]
        },
        {
          "title": "System & interface",
          "rows": [
            {
              "cmd": "/shell [command]",
              "desc": "Enter Shell Mode (see below). Aliases `/sh`, `/run`."
            },
            {
              "cmd": "/sandbox",
              "desc": "Configure sandbox mode and network access interactively."
            },
            {
              "cmd": "/mcp [list|list-tools] [id]",
              "desc": "Manage MCP servers and list a server's tools. Type to filter the server list."
            },
            {
              "cmd": "/plugin [subcommand]",
              "desc": "Manage plugins and marketplaces."
            },
            {
              "cmd": "/config",
              "desc": "Configure CLI settings interactively."
            },
            {
              "cmd": "/vim | /line-numbers | /show-thinking | /status-indicators",
              "desc": "Toggle Vim keys, code-block line numbers, thinking blocks, terminal-title status."
            },
            {
              "cmd": "/setup-terminal",
              "desc": "Configure terminal newline keybindings (see Keyboard)."
            },
            {
              "cmd": "/about | /logs",
              "desc": "Version, system, account info / debug log path. Both copy to the clipboard."
            },
            {
              "cmd": "/open",
              "desc": "Open the repository's git root in Cursor. Alias `/cursor`."
            },
            {
              "cmd": "/update | /logout | /help [command] | /feedback <msg>",
              "desc": "Update the CLI, sign out, get help, send feedback to the team."
            },
            {
              "cmd": "/bedrock [subcommand]",
              "desc": "Configure Bedrock when the Bedrock feature is enabled."
            }
          ]
        }
      ]
    },
    {
      "id": "keys",
      "title": "Keyboard & input",
      "navLabel": "Keyboard",
      "sources": [
        "https://cursor.com/docs/cli/using.md",
        "https://cursor.com/docs/cli/reference/terminal-setup.md",
        "https://cursor.com/docs/cli/overview.md",
        "https://cursor.com/docs/cli/shell-mode.md"
      ],
      "groups": [
        {
          "rows": [
            {
              "cmd": "@",
              "desc": "Select files and folders to include in context."
            },
            {
              "cmd": "& <message>",
              "desc": "Prepend to any message to hand the task to a Cloud Agent — it keeps running while you're away; pick it up at cursor.com/agents."
            },
            {
              "cmd": "Shift+Tab",
              "desc": "Rotate between Agent, Plan, and Ask modes."
            },
            {
              "cmd": "Shift+Enter",
              "desc": "Newline. Native in iTerm2, Ghostty, Kitty, Warp, Zed; other terminals run `/setup-terminal`."
            },
            {
              "cmd": "Ctrl+J / \\ + Enter",
              "desc": "Universal newline alternatives — work in every terminal, including tmux and screen."
            },
            {
              "cmd": "ArrowUp",
              "desc": "Cycle through previous messages."
            },
            {
              "cmd": "Ctrl+R",
              "desc": "Review changes. <kbd>i</kbd> adds follow-up instructions; ↑/↓ scroll, ←/→ switch files."
            },
            {
              "cmd": "Ctrl+O",
              "desc": "Expand truncated command output."
            },
            {
              "cmd": "Ctrl+C",
              "desc": "Cancel a hanging command; in Shell Mode, clears and exits."
            },
            {
              "cmd": "Ctrl+D",
              "desc": "Exit the CLI. Standard shell behaviour — press twice."
            },
            {
              "cmd": "y / n",
              "desc": "Approve or reject a proposed terminal command before it runs."
            }
          ]
        }
      ]
    },
    {
      "id": "shell",
      "title": "Shell mode",
      "lede": "Run shell commands without leaving the conversation — quick, non-interactive, permission-checked.",
      "sources": ["https://cursor.com/docs/cli/shell-mode.md"],
      "groups": [
        {
          "rows": [
            {
              "cmd": "/shell [command]",
              "desc": "Enter Shell Mode; commands run in your login shell (`$SHELL`) with the CLI's cwd and environment."
            },
            {
              "cmd": "cd <dir> && …",
              "desc": "`cd` does not persist between commands — chain it each time you need another directory."
            },
            {
              "cmd": "30s timeout",
              "desc": "Commands time out after 30 seconds (not configurable). No servers, no interactive prompts."
            },
            {
              "cmd": "Tab",
              "desc": "On the permission banner: add the command to your allowlist. Commands with redirection can't be allowlisted inline."
            },
            {
              "cmd": "Esc / Backspace on empty input",
              "desc": "Exit Shell Mode."
            }
          ]
        }
      ]
    },
    {
      "id": "headless",
      "title": "Headless & output",
      "navLabel": "Headless",
      "lede": "Print mode for scripts, CI, and automation. Auth via `CURSOR_API_KEY` in CI.",
      "sources": [
        "https://cursor.com/docs/cli/headless.md",
        "https://cursor.com/docs/cli/reference/output-format.md",
        "https://cursor.com/docs/cli/github-actions.md",
        "https://cursor.com/docs/cli/reference/authentication.md"
      ],
      "groups": [
        {
          "rows": [
            {
              "cmd": "agent -p \"prompt\"",
              "desc": "Text answer, no file changes applied — proposals only."
            },
            {
              "cmd": "agent -p --force \"prompt\"",
              "desc": "Apply file changes directly, no confirmation. The headless write switch.",
              "danger": true
            },
            {
              "cmd": "--output-format json",
              "desc": "One JSON object on success: `result`, `session_id`, `duration_ms`. Failures exit non-zero with stderr, no JSON."
            },
            {
              "cmd": "--output-format stream-json",
              "desc": "NDJSON events: `system` init, one `assistant` line per message, `tool_call` started/completed, terminal `result`."
            },
            {
              "cmd": "--stream-partial-output",
              "desc": "Character-level deltas. Keep events with `timestamp_ms` and no `model_call_id`; the other two kinds are duplicate flushes."
            },
            {
              "cmd": "agent -p \"describe ./screenshot.png\"",
              "desc": "Reference file paths in the prompt — the agent reads them (images included) via tool calls."
            },
            {
              "cmd": "echo \"$HOME/.cursor/bin\" >> $GITHUB_PATH",
              "desc": "GitHub Actions: install with the curl one-liner, add to PATH, auth via a `CURSOR_API_KEY` secret."
            }
          ]
        }
      ]
    },
    {
      "id": "permissions",
      "title": "Permissions & sandbox",
      "navLabel": "Permissions",
      "lede": "Permission tokens live in `permissions.allow` / `permissions.deny`; deny rules win.",
      "sources": [
        "https://cursor.com/docs/cli/reference/permissions.md",
        "https://cursor.com/docs/cli/reference/configuration.md",
        "https://cursor.com/docs/cli/reference/parameters.md",
        "https://cursor.com/docs/cli/overview.md"
      ],
      "groups": [
        {
          "title": "Permission tokens",
          "rows": [
            {
              "cmd": "Shell(git)  ·  Shell(curl:*)",
              "desc": "Shell access by command base; `command:args` globs match arguments too."
            },
            {
              "cmd": "Read(src/**/*.ts)  ·  Write(package.json)",
              "desc": "File read/write access by path or glob. Relative paths scope to the workspace."
            },
            {
              "cmd": "WebFetch(*.example.com)",
              "desc": "Domains the web-fetch tool may hit without prompting. `*` = any domain — use with caution."
            },
            {
              "cmd": "Mcp(server:tool)",
              "desc": "MCP tools by server and tool name, `*` wildcards on either side."
            }
          ]
        },
        {
          "title": "Modes & sandbox",
          "rows": [
            {
              "cmd": "approvalMode allowlist|auto-review|unrestricted",
              "desc": "Config-file setting for how tool calls get approved. Auto-review availability is admin-controlled."
            },
            {
              "cmd": "agent sandbox enable | disable | reset",
              "desc": "Sandbox mode for command execution vs allowlist mode. In-session: `/sandbox` (network access too)."
            },
            {
              "cmd": "agent sandbox run <cmd>",
              "desc": "Run one command sandboxed with workspace read/write. `--allow-paths`, `--readonly-paths`, `--blocked-patterns`, `--network`, `--sb-debug`."
            },
            {
              "cmd": "sudo prompting",
              "desc": "Elevated commands get a masked password prompt over secure IPC — the model never sees the password."
            }
          ]
        }
      ]
    },
    {
      "id": "config",
      "title": "Config & files",
      "navLabel": "Config",
      "sources": [
        "https://cursor.com/docs/cli/reference/configuration.md",
        "https://cursor.com/docs/cli/using.md",
        "https://cursor.com/docs/mcp.md",
        "https://cursor.com/docs/cli/reference/permissions.md"
      ],
      "groups": [
        {
          "rows": [
            {
              "cmd": "~/.cursor/cli-config.json",
              "desc": "Global CLI config: model, `editor.vimMode`, permissions, `approvalMode`, display toggles, `attribution.*`. Pure JSON, self-repairing."
            },
            {
              "cmd": ".cursor/cli.json",
              "desc": "Project-level config — **permissions only**; everything else must be global."
            },
            {
              "cmd": "CURSOR_CONFIG_DIR | XDG_CONFIG_HOME",
              "desc": "Relocate the config directory."
            },
            {
              "cmd": ".cursor/rules/",
              "desc": "Same rules system as the editor, auto-loaded. `AGENTS.md` and `CLAUDE.md` at the project root are applied as rules too."
            },
            {
              "cmd": ".cursor/mcp.json  ·  ~/.cursor/mcp.json",
              "desc": "Project / global MCP servers — the CLI reuses the editor's configuration. Variables like `${workspaceFolder}` resolve."
            },
            {
              "cmd": "notifications · hints · rewind · suggestNextPrompt",
              "desc": "Optional config booleans: terminal notification on finish, working hints, `/rewind` support, next-prompt suggestions."
            },
            {
              "cmd": "attribution.attributeCommitsToAgent",
              "desc": "\"Made with Cursor\" trailer on agent commits (default `true`); `attributePRsToAgent` for PR footers."
            },
            {
              "cmd": "HTTP_PROXY · HTTPS_PROXY · NODE_USE_ENV_PROXY=1",
              "desc": "Proxy support; `NODE_EXTRA_CA_CERTS` for SSL inspection, `network.useHttp1ForAgent` for proxies without HTTP/2."
            }
          ]
        }
      ]
    },
    {
      "id": "mcp",
      "title": "MCP & integrations",
      "navLabel": "MCP",
      "sources": [
        "https://cursor.com/docs/cli/reference/parameters.md",
        "https://cursor.com/docs/mcp.md",
        "https://cursor.com/docs/cli/using.md",
        "https://cursor.com/docs/cli/acp.md"
      ],
      "groups": [
        {
          "rows": [
            {
              "cmd": "agent mcp list | list-tools <id>",
              "desc": "Configured servers and their status / a server's tools and argument names."
            },
            {
              "cmd": "agent mcp login <id>",
              "desc": "Authenticate with an OAuth MCP server from `.cursor/mcp.json` or `~/.cursor/mcp.json`."
            },
            {
              "cmd": "agent mcp enable | disable <id>",
              "desc": "Add a server to the local approved list / stop it loading or prompting."
            },
            {
              "cmd": "agent acp",
              "desc": "Run the CLI as an ACP (Agent Client Protocol) server over stdio JSON-RPC — for custom client integrations. Hidden from help."
            },
            {
              "cmd": "agent worker --pool --pool-name <name>",
              "desc": "Register the private worker for pool assignment; one cloud agent claims it at a time. `--worker-dir`, `--label`, `--management-addr` shape it."
            }
          ]
        }
      ]
    }
  ]
}