Add support for global .env.schema file for commonly used environment variables

[sanathusk]

Summary

Add the ability to define a global .env.schema file in folder say in ~/.varlock that contains commonly used global environment variables (like API keys, tokens, etc.) that can be used across all projects when running varlock run.

Motivation

When using varlock run to execute commands in an agentic context (e.g., running varlock run pi), the command may be launched from any folder and requires certain environment variables like OPENAI_API_KEY to be set.

Currently, users must define these variables in each project's .env.schema file, which is:

1. Repetitive - Same variables need to be defined in every project
2. Error-prone - Easy to forget to add them to a new project
3. Inconvenient - Can't use global tools like varlock run pi without project-specific setup

Proposed Solution

Introduce a global .env.schema file (e.g., at ~/.varlock/global.env.schema or similar) that:

• Contains commonly used environment variables accessible across all projects
• Is automatically loaded when running varlock run or varlock load
• Contains sensitive variables like API keys, tokens, etc.

Precedence/Override Behavior

When both global and local .env.schema files define the same variable:

• Local project .env.schema takes precedence for the variable definition
• This allows projects to customize or override global defaults as needed

Example:

# Global (~/.varlock/global.env.schema)
OPENAI_API_KEY=@required @sensitive
ANTHROPIC_API_KEY=@required @sensitive

# Project (.env.schema)
OPENAI_API_KEY=@required @sensitive @example("sk-proj-...")

In this case, the project's local definition would override the global one.

Use Cases

1. Agentic tools: Running tools like pi that need OPENAI_API_KEY set from any directory
2. Common credentials: API keys, tokens, secrets used across multiple projects
3. Developer convenience: Avoiding duplicate configuration across projects

Additional Considerations

• The global schema file location should be configurable
• Users should be able to disable global schema loading if needed
• Security: ensure the global file is properly secured (permissions, etc.)

[theoephraim]

I'm hesitant to do anything that will would make default behaviour on one machine different than on another. Your use case is loading env vars into commands, but for many users they are wiring varlock into a git repo. In that case, we woudlnt want global env vars to be automatically loaded, as we only want project specific vars there. You can of course import additional vars from other locations outside the repo too.

For a similar use case, currently I create env files in my home folder, and then use aliases to wrap the command in varlock run. For example:

alias vclaude="bunx varlock run -p ~/.env.claude --no-redact-stdout -- claude"

You coudl also imagine having a tool specific env file in a project, and creating a package.json script that calls it injecting the right vars. Imports make this all flexible as well and composable.

Maybe we could add some kind of shortcut/flag which loads a global file in a known location so at least it's easier to type (varlock run -g?), but I think you'd still want to opt into those global vars rather than applying them within all your projects. Note that this is also important for type generation, as you woundlt want your global vars making it into the project specific env var types.

[theoephraim]

@sanathusk - what do you think about just adding a -g flag that would be a shorthand for --path ~/.env.global?

[sanathusk]

@sanathusk - what do you think about just adding a -g flag that would be a shorthand for --path ~/.env.global?

Sounds great, that should work. Thanks🙏