Skip to content

All posts

AI

How to use .cursorignore to keep secrets out of Cursor

Ritesh Patel

AI: How to use .cursorignore to keep secrets out of Cursor

A .cursorignore file in your project root tells Cursor which files it should not access, using .gitignore syntax. The Cursor docs say the file blocks Agent and Tab from reading matched code, and blocks @ mention references to it. The same docs say complete protection is not guaranteed, so treat the file as one layer, not the only control.

Checked against the Cursor ignore file reference as fetched on 2026-11-18. The page does not state a Cursor app version, so confirm the behaviour in the build your team uses.

What the file blocks, and what it cannot

The Cursor docs list two surfaces the file covers and two it cannot. The wording matters, so the table quotes the page directly.

Surface Covered by .cursorignore? Wording in the Cursor docs
Code accessed by Agent and Tab Yes “Cursor blocks access to files listed in .cursorignore from” these
Code accessed through @ mention references Yes Listed with the two surfaces above
Terminal tools used by Agent No “cannot block access to code governed by .cursorignore”
MCP server tools used by Agent No Same sentence, which names the terminal and MCP server tools together

Under the Security heading the page is blunter: “While Cursor blocks ignored files, complete protection isn’t guaranteed due to LLM unpredictability.” Plan for a file that reduces exposure, and keep real credentials out of places an agent can reach.

Step 1: Create the file in the project root

  1. Create a file named .cursorignore in the root of the repository you open in Cursor.
  2. Write one pattern per line. Lines starting with # are comments.
  3. Trailing spaces are ignored unless you escape them with \.

The docs define these pattern characters:

Pattern Meaning
* Any characters except /
** Any characters, including /
? A single character
! Negates a pattern and un-ignores a path

Start with the common patterns the docs suggest for secrets:

# Environment files
**/.env
**/.env.*

# Credentials
**/credentials.json
**/secrets.json

# Keys
**/*.key
**/*.pem
**/id_rsa

Step 2: Check what Cursor already ignores

Cursor ignores files in .gitignore and a default list, without any work from you. The default list includes .env* and .git/, along with lock files, archives and many binary types. You can see the full list on the reference page.

The default list does not include the key and credential names from the example above. So a repository with a credentials.json or a server.pem is exposed unless you add those patterns yourself. Check your repository for those names before you rely on the defaults.

Patterns in the global list apply to every project you open, so they suit credentials that never belong in a repository. The docs say the list is empty by default.

  1. Open Cursor Settings.
  2. Go to Indexing, then Ignore Files.
  3. Add your patterns to the global ignore list.
  4. Turn on Hierarchical Cursor Ignore in the same section if you want Cursor to search parent directories for .cursorignore files.

The docs do not say how the global list and a project .cursorignore combine when they disagree. Test both before you depend on either one.

Step 4: Avoid the negation trap

A ! pattern cannot bring back a file whose parent directory is excluded with *. The docs give this example, where the last line has no effect:

public/*
!public/index.html
!public/assets/style.css

The workaround is to re-include the nested directory first, so traversal can reach it. Then exclude its children and negate the file:

public/*
!public/index.html
!public/assets/
public/assets/*
!public/assets/style.css

Excluded directories are not traversed for performance, so a pattern for a file inside them has no effect. Write the rule at the level of the directory you want to hide.

Step 5: Test the patterns

Do not test a .cursorignore pattern with git check-ignore. Git reads only .gitignore, so the command reports a file as visible even when .cursorignore lists it. Test in Cursor instead: put a dummy file that the pattern should block in the repository, ask Agent to open that file directly, and check which tool it used in the transcript. A terminal command or an MCP tool can read files that .cursorignore lists, so a read through either one is a separate exposure, not a pattern failure. Test it on its own, and do not treat it as a pattern test. Note the Cursor version you tested. If the contents appear, fix the pattern and test again before you assume the file is protected.

Keep the test to a scratch repository with a dummy secret file. Do not use a real credential to check whether Agent can read it.

How this compares with Claude Code deny rules

Claude Code takes a different form. Its settings file has a permissions.deny list that names tools and paths. The Claude Code settings page gives this example, which denies reads of .env files:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}
Question Cursor .cursorignore Claude Code permissions.deny
Where it lives Project root, plus a global list in Cursor Settings settings.json, at the scope you choose
Pattern form .gitignore patterns Tool rules, such as Read(./.env)
Documented limit Terminal and MCP tools cannot be blocked, and protection is not complete Not described on the settings page

If your team uses both tools, write the rules in each tool’s own format and test them in each. One file does not translate to the other.

The .cursorignore file is set by the developer, in each repository, and the Cursor docs describe it as a filter on what Cursor reads. This post makes no claim that AIControls reads, changes or enforces .cursorignore files. To see what the product covers, start at the AIControls download page. For the wider set of controls for coding agents, see governance for AI coding agents. Two related posts cover the adjacent steps: how to stop Claude Code from reading secrets and .env files and how to stop AI coding agents from committing secrets to git.

Sources

Frequently asked questions

Does .cursorignore stop Cursor from reading a secret file?

It blocks the file from Agent and Tab and from @ mention references, according to the Cursor docs. The same page says complete protection is not guaranteed because of LLM unpredictability, and that the terminal and MCP server tools used by Agent cannot block access to ignored code. Use the file to reduce exposure, and keep real credentials out of the project folder where you can.

Are .env files ignored by Cursor by default?

Yes. The default ignore list in the Cursor docs includes .env*, along with .git/ and anything matched by .gitignore. The same list does not include *.key, *.pem, credentials.json or secrets.json, so add those patterns to your .cursorignore. A ! pattern can override a default entry if you need the file back.

Why does my negated pattern not bring a file back?

The docs say you cannot re-include a file when a parent directory is excluded with *. A rule such as !public/assets/style.css has no effect after public/*. Re-include the nested directory with !public/assets/, exclude its children with public/assets/*, then negate the file. Excluded directories are not traversed, so patterns inside them have no effect.

Does a global ignore list apply to every project?

The docs say patterns in the global ignore list apply to all projects, and that the list is empty by default. Hierarchical Cursor Ignore, under Indexing, then Ignore Files, makes Cursor search parent directories for .cursorignore files. The docs suggest a git check-ignore test, but git reads only .gitignore, so that command does not test a .cursorignore pattern.

Ritesh Patel, Founder & VP Product, Nirmata

Ritesh Patel is a founder of Nirmata and leads its products. He writes about governing AI coding agents, MCP security and Kubernetes policy as code.

LinkedIn

Govern AI agents with AIControlsControl what AI agents do, and prove it.
Share

Stay up-to-date with the latest in AI, governance, and infrastructure

Subscribe to our free monthly newsletter to get industry news, DevOps tips, and articles right to your inbox on Kyverno, containerization, Kubernetes deployment & management and more.