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
- Create a file named
.cursorignorein the root of the repository you open in Cursor. - Write one pattern per line. Lines starting with
#are comments. - 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.
Step 3: Set a global list and hierarchical search
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.
- Open Cursor Settings.
- Go to Indexing, then Ignore Files.
- Add your patterns to the global ignore list.
- Turn on Hierarchical Cursor Ignore in the same section if you want Cursor to search parent directories for
.cursorignorefiles.
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.
Related controls
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
- Cursor ignore file reference, fetched 2026-11-18. Covers the pattern rules, the negation limit, the default list and the global list.
- Claude Code settings, fetched 2026-11-18. Covers the
permissions.denyexample.
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.