{"_id":"@aeondave/opencode-dotenv","name":"@aeondave/opencode-dotenv","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aeondave/opencode-dotenv","version":"0.1.0","description":"Load a .env file next to your OpenCode config into the process and substitute {env:VAR} / ${VAR} placeholders across config files. Cross-platform, zero runtime dependencies.","keywords":["opencode","opencode-plugin","dotenv","env","environment-variables","config"],"homepage":"https://github.com/AeonDave/opencode-dot-env#readme","bugs":{"url":"https://github.com/AeonDave/opencode-dot-env/issues"},"repository":{"type":"git","url":"git+https://github.com/AeonDave/opencode-dot-env.git"},"license":"MIT","type":"module","main":"src/plugin/dotenv.ts","exports":{".":"./src/plugin/dotenv.ts"},"scripts":{"typecheck":"tsc --noEmit","test":"bun test"},"peerDependencies":{"@opencode-ai/plugin":"*"},"peerDependenciesMeta":{"@opencode-ai/plugin":{"optional":true}},"devDependencies":{"@opencode-ai/plugin":"latest","@types/bun":"latest","typescript":"latest"},"gitHead":"7a7e880bdd4535c6561f70ceafa1dfe472ae5044","_id":"@aeondave/opencode-dotenv@0.1.0","_nodeVersion":"26.3.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-1WCfFpawSUCCW5xsT7J0mjRWURGDhuisSN6cmHWe6JI+bbOlX1DNw40e6k9B59ZCYWeuMdBplEgyuHryB6UgPA==","shasum":"b46ce0994878fe19e5a801f901f03c84cf7b47db","tarball":"https://registry.npmjs.org/@aeondave/opencode-dotenv/-/opencode-dotenv-0.1.0.tgz","fileCount":6,"unpackedSize":18365,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHr+aFfpsyKfDoCuYa5BFxPTB2UXJmeFIZscl9A8hcxBAiEAgbVV+g1yRTtHx7X7DZvSi5+jk/aQsp6xow7v1S5tjzU="}]},"_npmUser":{"name":"aeondave","email":"nova.davide@gmail.com"},"directories":{},"maintainers":[{"name":"aeondave","email":"nova.davide@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/opencode-dotenv_0.1.0_1781270136888_0.6756098939933495"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T13:15:36.731Z","0.1.0":"2026-06-12T13:15:37.043Z","modified":"2026-06-12T13:15:37.267Z"},"maintainers":[{"name":"aeondave","email":"nova.davide@gmail.com"}],"description":"Load a .env file next to your OpenCode config into the process and substitute {env:VAR} / ${VAR} placeholders across config files. Cross-platform, zero runtime dependencies.","homepage":"https://github.com/AeonDave/opencode-dot-env#readme","keywords":["opencode","opencode-plugin","dotenv","env","environment-variables","config"],"repository":{"type":"git","url":"git+https://github.com/AeonDave/opencode-dot-env.git"},"bugs":{"url":"https://github.com/AeonDave/opencode-dot-env/issues"},"license":"MIT","readme":"# opencode-dot-env\r\n\r\n> Load a `.env` next to your OpenCode config and resolve `{env:VAR}` placeholders — no shell wrapper, no profile alias.\r\n\r\nA plugin for [OpenCode](https://github.com/sst/opencode) that reads a `.env` file from your config directory into the running process, so `{env:VAR}` placeholders in `opencode.json`, MCP definitions, provider options, and other plugins resolve automatically. Cross-platform (Linux, macOS, Windows) with zero runtime dependencies.\r\n\r\nRepository: [AeonDave/opencode-dot-env](https://github.com/AeonDave/opencode-dot-env)\r\n\r\n## Why This Exists\r\n\r\nOpenCode resolves `{env:VAR}` from the **process environment** at startup. Without help, that means exporting every secret beforehand — a shell wrapper script, a profile alias, or system-wide environment variables. That is fragile and easy to forget.\r\n\r\nThis plugin removes the wrapper: drop a `.env` next to `opencode.json` and the variables are loaded for you, on every OS, every launch.\r\n\r\n- **One `.env`, everywhere** — Keep values like `API_KEY`, `ACCESS_TOKEN`, and other secrets in a single gitignored file beside your config.\r\n- **Placeholders just work** — `{env:VAR}` and `${VAR}` in config files resolve from the loaded `.env`.\r\n- **Shells inherit it too** — Loaded variables are injected into the `bash` tool and terminal sessions.\r\n\r\n## How It Works\r\n\r\nThe plugin runs at three points, earliest first:\r\n\r\n1. **Plugin init** — before MCP servers spawn and providers initialize, it parses the `.env` and populates `process.env`. This is what makes OpenCode's own `{env:VAR}` resolution succeed.\r\n2. **`config` hook** — rewrites any `{env:VAR}` / `${VAR}` literals that survived into the merged config object (covers `opencode.json`, `dcp.jsonc`, and other plugins' config).\r\n3. **`shell.env` hook** — injects the loaded variables into shell executions (bash tool + user terminals).\r\n\r\nUnknown variables are left untouched, so a typo never silently blanks a value.\r\n\r\n## .env Resolution\r\n\r\nThe plugin looks for a `.env` in your OpenCode config directory, resolved in this order:\r\n\r\n1. `OPENCODE_DOTENV_DIR` — explicit directory to search.\r\n2. `OPENCODE_CONFIG` — explicit config file; its directory is used.\r\n3. `XDG_CONFIG_HOME/opencode`.\r\n4. `~/.config/opencode` (OpenCode's default on every OS, including Windows).\r\n\r\nAn optional `OPENCODE_DOTENV_PATH` points at a specific `.env` file, which is loaded last and wins.\r\n\r\n### Supported `.env` syntax\r\n\r\n```bash\r\n# comments and blank lines are ignored\r\nexport FOO=bar\r\nAPI_KEY=\"example-key\"\r\nQUOTED='single quoted'\r\nMULTILINE=\"line1\\nline2\"   # \\n \\t \\r \\\\ \\\" unescaped inside double quotes\r\n```\r\n\r\n## Installation\r\n\r\n### From npm (recommended)\r\n\r\nAdd the package to the `plugin` array in your OpenCode config at `~/.config/opencode/opencode.json`:\r\n\r\n```jsonc\r\n{\r\n  \"plugin\": [\"@aeondave/opencode-dotenv@latest\"]\r\n}\r\n```\r\n\r\nOpenCode installs the plugin automatically on the next start. To pin a version, replace `@latest` with a specific version (e.g. `@0.1.0`).\r\n\r\n### From a local clone (shim)\r\n\r\nRun from a local checkout — useful before publishing or while hacking on the plugin:\r\n\r\n1. Clone the repository and install dependencies:\r\n\r\n   ```bash\r\n   git clone https://github.com/AeonDave/opencode-dot-env.git\r\n   cd opencode-dot-env\r\n   npm install\r\n   ```\r\n\r\n2. Create a shim file in your global plugin directory that re-exports the checkout's entry point. The directory is `plugin` (singular):\r\n\r\n   - Path: `~/.config/opencode/plugin/dotenv.ts`\r\n   - Content — a single line pointing at the absolute path of the cloned entry point:\r\n\r\n   ```ts\r\n   export { default } from \"/absolute/path/to/opencode-dot-env/src/plugin/dotenv.ts\"\r\n   ```\r\n\r\n   On Windows, use forward slashes and include the drive letter, for example:\r\n\r\n   ```ts\r\n   export { default } from \"C:/path/to/opencode-dot-env/src/plugin/dotenv.ts\"\r\n   ```\r\n\r\n3. Restart OpenCode. The plugin loads from your working tree, so edits to `src/` take effect on the next restart. Delete the shim file to uninstall.\r\n\r\n> Use one method at a time. If you add the npm entry, remove the local shim (and vice versa) so the plugin is not loaded twice.\r\n\r\n## Usage\r\n\r\n1. Put a `.env` next to your config:\r\n\r\n   ```bash\r\n   # ~/.config/opencode/.env\r\n   API_KEY=your-api-key\r\n   ACCESS_TOKEN=your-access-token\r\n   ```\r\n\r\n2. Reference the variables in your config as usual:\r\n\r\n   ```jsonc\r\n   // Example excerpt\r\n   {\r\n     \"somePlugin\": {\r\n       \"apiKey\": \"{env:API_KEY}\",\r\n       \"accessToken\": \"${ACCESS_TOKEN}\"\r\n     }\r\n   }\r\n   ```\r\n\r\n3. Start OpenCode normally — no wrapper script, no alias.\r\n\r\n> Add `.env` to your `.gitignore`. Never commit real secrets.\r\n\r\n## Configuration\r\n\r\n| Environment variable | Default | Effect |\r\n|----------------------|---------|--------|\r\n| `OPENCODE_DOTENV_DIR` | unset | Directory to search for `.env` (overrides config-dir detection). |\r\n| `OPENCODE_DOTENV_PATH` | unset | Path to an extra `.env` file, loaded last (highest priority). |\r\n| `OPENCODE_DOTENV_OVERRIDE` | `0` | When truthy (`1`/`true`/`yes`/`on`), `.env` values replace existing process variables. By default existing variables are kept. |\r\n| `OPENCODE_DOTENV_SILENT` | `0` | When truthy, suppress info/debug logs (warnings still shown). |\r\n\r\n## Development\r\n\r\n```bash\r\nnpm install      # install dev dependencies\r\nnpm run typecheck\r\n```\r\n\r\n## Disclaimer\r\n\r\nThis project is not built by the OpenCode team and is not affiliated with [OpenCode](https://github.com/sst/opencode).\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md","_rev":"1-f6ccc812bc2d5a66cb6f8f58bc482123"}