Skip to main content

Validate local .env files from 1Password Environments with Cursor Agent

You can use the validate-mounted-env-files.sh Cursor hook to validate that locally mounted .env files from 1Password Environments are properly set up and enabled before Cursor Agent executes shell commands.

If any required .env files are missing or invalid, the hook prevents Cursor from running the command and provides instructions for how to fix the issue.

Requirements​

Windows not supported

Local .env files for 1Password Environments are currently only supported on Mac and Linux. If you're on Windows, the hook will skip the validation checks.

Step 1: Set up your environments​

To use the 1Password hook, you'll first need to:

  1. Create one or more environments in 1Password to store your project secrets.
  2. Configure locally mounted .env files for them.

Step 2: Choose how you want the hook to validate your .env files​

Default mode​

By default, the hook will check the 1Password desktop app to find .env files related to your project based on the file path destinations you configured in 1Password Environments.

Configured mode​

Alternatively, you can create a .1password/environments.toml file at the root of your project that specifies which locally mounted .env files to validate. The hook only validates the specified files.

To do this, the hook parses the TOML file to extract mount paths from the mount_paths array field. Mount paths can be relative to the project root or absolute. For example:

.1password/environments.toml

The mount_paths field must be explicitly defined in the TOML file. If the file exists but doesn't contain a mount_paths field, the hook will log a warning and fall back to default mode.

If no .env files are specified in the TOML file, all commands will be allowed to run.

Step 3: Set up the hook in your project​

note

This guide shows you how to set up the 1Password hook in a specific project. You can also configure the hook at the user or global level. More specific configurations take precedence over more general ones. Learn more about configuration options .

To set up the hook in your project, first clone or download the 1Password Cursor Hooks repository.

If you're using Cursor Hooks for the first time, you can copy the entire .cursor directory from the repository into your project root to get started.

If you already have Cursor Hooks set up in your project:

  1. Copy the 1password subfolder into the .cursor/hooks directory.

  2. Update your existing .cursor/hooks.json file to map the hook beforeShellExecution to the path for the validate-mounted-env-files.sh script. For example:

.cursor/hooks.json

The resulting file structure should look like this:

tip

If you don't see the .cursor subfolder, make sure to run ls -a in the terminal or Command + Shift + . in Finder on Mac to show hidden dotfiles.

After you set up the hook, restart Cursor and tell the Cursor Agent to perform a task that requires running a shell command. If your .env files are properly configured, the command will proceed. Otherwise the Agent will guide you through fixing the issue.

To confirm the hook worked as expected, open Cursor, then navigate to Settings > Hooks > Execution Log.

How it works​

Cursor hooks are custom scripts that run before or after specific stages of the agent loop. Each hook runs as a spawned process that communicates with Cursor over standard input and output using JSON in both directions. Hooks can observe, block, or modify the agent’s behavior as it runs.

The 1Password hook is designed to be used with the beforeShellExecution event , so that the hook is called before any shell command is executed by the agent. The hook returns a permission decision that decides whether or not the command is allowed to run.

When Cursor Agent tries to execute a command, the hook first checks for a .1password/environments.toml file in the current project directory. If a TOML file exists and contains the required mount_paths field, Cursor validates only the specified .env files. If no TOML file exists, Cursor queries the 1Password desktop app for all .env files mounted in the project directory. The hook then confirms that each .env file discovered for the project is enabled, the mount file exists, and the file is a valid FIFO (named pipe).

If all required .env files are enabled and configured correctly, the command is allowed to proceed. If one or more required .env files are missing, disabled, or invalid, the hook denies shell execution and provides an error message with steps to fix the issue.

The hook uses a "fail open" approach in default mode. If it can't access the 1Password database, the hook logs a warning and allows subsequent commands to proceed. This makes sure development can proceed if the 1Password app is not installed or the database is unavailable. Similarly, if a TOML file exists but no .env files are specified, the command is allowed to proceed.

Configuration examples​

Single .env file

.1password/environments.toml

Only .env is validated. Other environment files are ignored.

Multiple .env files

.1password/environments.toml

Only the three declared .env files are validated.

No validation

.1password/environments.toml

No .env files are validated. All commands are allowed.

Default mode

No .1password/environments.toml file exists or the mount_paths field has been improperly defined. The hook discovers and validates all mounts configured in 1Password that are within the project directory.

Troubleshooting​

The hook logs information to /tmp/1password-cursor-hooks.log for troubleshooting. Check this file if you encounter issues.

Log entries include timestamps and detailed information about:

  • Database queries and results
  • Mount validation checks
  • Permission decisions
  • Error conditions

To enable debug mode, set DEBUG=1 to output logs directly to the shell instead of the log file:

Learn more​

Was this page helpful?