{"id":44669171,"url":"https://github.com/matteocervelli/op-env-manager","last_synced_at":"2026-02-15T01:35:20.202Z","repository":{"id":323819706,"uuid":"1094324043","full_name":"matteocervelli/op-env-manager","owner":"matteocervelli","description":"Bidirectional environment variable sync with 1Password - Securely manage .env files using 1Password as the source of truth","archived":false,"fork":false,"pushed_at":"2025-11-12T08:53:08.000Z","size":148,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-12T10:17:58.787Z","etag":null,"topics":["1password","bash","cli-tool","devops","dotenv","environment-variables","secrets-management","security"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matteocervelli.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T15:02:19.000Z","updated_at":"2025-11-12T08:30:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/matteocervelli/op-env-manager","commit_stats":null,"previous_names":["matteocervelli/op-env-manager"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/matteocervelli/op-env-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matteocervelli%2Fop-env-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matteocervelli%2Fop-env-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matteocervelli%2Fop-env-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matteocervelli%2Fop-env-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matteocervelli","download_url":"https://codeload.github.com/matteocervelli/op-env-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matteocervelli%2Fop-env-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29464369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T01:01:38.065Z","status":"ssl_error","status_checked_at":"2026-02-15T01:01:23.809Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["1password","bash","cli-tool","devops","dotenv","environment-variables","secrets-management","security"],"created_at":"2026-02-15T01:35:19.475Z","updated_at":"2026-02-15T01:35:20.190Z","avatar_url":"https://github.com/matteocervelli.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# op-env-manager\n\n**Bidirectional environment variable sync with 1Password** - Securely manage your `.env` files using 1Password as the source of truth.\n\nby [Matteo Cervelli](https://github.com/matteocervelli)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Test Suite](https://github.com/matteocervelli/tool-op-env-manager/actions/workflows/test.yml/badge.svg)](https://github.com/matteocervelli/tool-op-env-manager/actions/workflows/test.yml)\n[![1Password CLI](https://img.shields.io/badge/1Password-CLI-blue.svg)](https://developer.1password.com/docs/cli/)\n[![Buy Me A Coffee](https://img.shields.io/badge/☕-Buy%20me%20a%20coffee-orange.svg)](https://adli.men/coffee)\n\n---\n\n## What is this?\n\n`op-env-manager` is a command-line tool that bridges your local `.env` files and 1Password vaults, enabling:\n\n- **Init**: Interactive setup wizard for guided onboarding (~2 minutes) (v0.3.0+)\n- **Push**: Upload your `.env` variables to 1Password for secure storage\n- **Inject**: Download secrets from 1Password into local `.env` files\n- **Run**: Execute commands with secrets injected from 1Password (no plaintext files!)\n- **Diff**: Compare local `.env` with 1Password to identify differences (planned v0.4.0)\n- **Sync**: Bidirectional synchronization with intelligent conflict resolution (planned v0.4.0)\n- **Convert**: Migrate legacy `.env` files with `op://` references to op-env-manager format\n- **Template**: Generate `.env.op` files with `op://` references for version control\n\nStop committing secrets to git. Stop sharing `.env` files over Slack. Use 1Password.\n\n## Architecture\n\n```mermaid\ngraph LR\n    A[.env Files] --\u003e|push| B[op-env-manager]\n    B --\u003e|Secure Storage| C[1Password Vaults]\n    C --\u003e|inject| B\n    B --\u003e|.env Files| A\n    B --\u003e|run| D[App with Secrets]\n    C -.-\u003e|runtime injection| D\n    E[.env.op Templates] -.-\u003e|safe for git| F[Version Control]\n\n    style C fill:#0094F5,color:#fff\n    style B fill:#333,color:#fff\n    style F fill:#2ea44f,color:#fff\n```\n\n**How it works**:\n1. **Push**: Parse local `.env` → Create/update 1Password Secure Note with fields\n2. **Inject**: Fetch 1Password fields → Write to local `.env` (chmod 600)\n3. **Run**: Generate `op://` references → Execute with `op run` (no plaintext on disk)\n4. **Template**: Create `.env.op` with references → Safe for git commits\n\n## Why?\n\n**The Problem**:\n- `.env` files contain sensitive secrets\n- Sharing them is insecure (email, Slack, git)\n- Keeping them in sync across team members is painful\n- Rotating secrets requires manual updates everywhere\n\n**The Solution**:\n- Store secrets in 1Password (encrypted, shared, versioned)\n- Push/pull on demand\n- Run applications with secrets injected at runtime\n- No plaintext secrets on disk\n\n## Features\n\n✅ **Bidirectional Sync** - Push `.env` → 1Password, Inject 1Password → `.env`\n✅ **Multiline Values** - Support for private keys, certificates, JSON configs (v0.2.0+)\n✅ **Progress Indicators** - ASCII progress bars for operations with 100+ variables (v0.3.0+)\n✅ **Quiet Mode** - `--quiet` flag for CI/CD pipelines and scripts (v0.3.0+)\n✅ **Retry Logic** - Automatic retry with exponential backoff for network failures (v0.2.0+)\n✅ **Interactive Setup** - Guided `init` wizard for new users (v0.3.0+)\n✅ **Multiple Vaults** - Separate dev, staging, production secrets\n✅ **Dry Run Mode** - Preview changes before applying\n✅ **Runtime Injection** - Run commands with secrets (no disk storage)\n✅ **Template Generation** - Create safe `.env.op` files for version control\n✅ **Team Friendly** - Share vaults, control access\n✅ **Git Safe** - Never commit secrets again\n✅ **Auto-tagging** - All items tagged for easy filtering\n🔜 **Intelligent Sync** - Smart conflict resolution with diff/sync commands (planned v0.4.0)\n🔜 **Performance Optimized** - Parallel operations, caching, bulk resolution (planned v0.5.0)\n\n## Performance\n\nop-env-manager is designed for speed and efficiency:\n\n- **Batch Operations**: Single API call for all variables (not N calls)\n- **Retry Logic**: Automatic retry with exponential backoff for network failures\n- **Progress Indicators**: Visual feedback for large operations (100+ variables)\n- **Network-bound**: Performance limited by 1Password API latency, not CPU\n\n**Typical Performance** (v0.3.0):\n\n| Variables | push  | inject |\n|-----------|-------|--------|\n| 10        | ~2s   | ~2s    |\n| 50        | ~3s   | ~3s    |\n| 100       | ~4s   | ~4s    |\n| 500       | ~8s   | ~8s    |\n\n**Future Optimizations** (planned v0.5.0):\n- Parallel read operations for sync/diff commands\n- Intelligent caching to reduce API calls\n- Bulk resolution for op:// references\n\nSee [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for detailed information and optimization strategies.\n\n## Comparison with Alternatives\n\n| Feature | op-env-manager | dotenv | envkey | AWS Secrets | HashiCorp Vault |\n|---------|---------------|--------|--------|-------------|-----------------|\n| **Cost** | Free (uses 1Password) | Free | Paid plans | AWS pricing | Self-hosted/paid |\n| **Setup Complexity** | Low (1Password CLI) | Very low | Medium | High | Very high |\n| **Team Sharing** | ✅ (1Password vaults) | ❌ (manual files) | ✅ | ✅ | ✅ |\n| **Access Control** | ✅ (1Password policies) | ❌ | ✅ | ✅ | ✅ |\n| **Audit Trail** | ✅ (1Password logs) | ❌ | ✅ | ✅ | ✅ |\n| **Runtime Injection** | ✅ (`run` command) | ❌ | ✅ | ❌ | ✅ |\n| **Multi-Environment** | ✅ (sections/vaults) | Manual files | ✅ | ✅ | ✅ |\n| **Git Safe** | ✅ (templates) | ⚠️ (gitignore) | ✅ | ✅ | ✅ |\n| **CI/CD Integration** | ✅ (Service Accounts) | ✅ | ✅ | ✅ | ✅ |\n| **Learning Curve** | Low | Very low | Medium | Medium | High |\n| **Infrastructure** | None (SaaS) | None | SaaS | AWS account | Self-hosted |\n\n**When to use op-env-manager**:\n- ✅ You already use 1Password for your team\n- ✅ You want simple, secure secret management without new infrastructure\n- ✅ You need team collaboration with access control\n- ✅ You want audit trails and versioning\n- ✅ You prefer CLI tools over web dashboards\n\n**When to use alternatives**:\n- **dotenv**: Solo projects, no team collaboration needed, very simple setup\n- **envkey**: Need dedicated secret management platform, willing to pay\n- **AWS Secrets Manager**: Already on AWS, want tight AWS integration\n- **HashiCorp Vault**: Enterprise needs, complex access patterns, dynamic secrets\n\n## Installation\n\n### Quick Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/matteocervelli/op-env-manager.git\ncd op-env-manager\n\n# Run installer\n./install.sh\n```\n\nThe installer will:\n1. Install to `~/.local/bin/op-env-manager/`\n2. Create symlink in `~/.local/bin/`\n3. Add to PATH (if needed)\n4. Verify prerequisites (jq, 1Password CLI)\n\n### Manual Installation\n\n```bash\n# Clone and setup\ngit clone https://github.com/matteocervelli/op-env-manager.git\nmkdir -p ~/.local/bin\nln -s \"$(pwd)/op-env-manager/bin/op-env-manager\" ~/.local/bin/op-env-manager\n\n# Add to PATH (if not already)\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc  # or ~/.bashrc\nsource ~/.zshrc\n```\n\n### Prerequisites\n\n- **Bash** (4.0+)\n- **jq** - JSON processor\n  ```bash\n  # macOS\n  brew install jq\n\n  # Linux\n  sudo apt install jq    # Debian/Ubuntu\n  sudo dnf install jq    # Fedora/RHEL\n  ```\n- **1Password CLI** - See [docs/1PASSWORD_SETUP.md](docs/1PASSWORD_SETUP.md)\n\n## Quick Start\n\n### 1. Install 1Password CLI\n\nSee [docs/1PASSWORD_SETUP.md](docs/1PASSWORD_SETUP.md) for detailed instructions.\n\n```bash\n# macOS\nbrew install --cask 1password-cli\n\n# Linux (Debian/Ubuntu)\n# See docs/1PASSWORD_SETUP.md for full instructions\n\n# Sign in\nop signin\n```\n\n### 2. Run the Setup Wizard (Recommended)\n\n**New in v0.3.0**: The `init` command provides a guided setup experience:\n\n```bash\n# Interactive wizard - get started in ~2 minutes\nop-env-manager init\n```\n\nThe wizard will guide you through:\n- ✅ Vault selection or creation\n- ✅ Item naming\n- ✅ .env file detection\n- ✅ Multi-environment setup (dev/staging/prod)\n- ✅ Initial push to 1Password\n- ✅ Optional template generation\n\nOr continue with manual setup below...\n\n### 3. Push your .env to 1Password (Manual)\n\n```bash\n# Push .env to your Personal vault\nop-env-manager push --vault \"Personal\" --env .env\n\n# Push production secrets to separate vault\nop-env-manager push --vault \"Production\" --env .env.production --item \"myapp\"\n```\n\n### 4. Inject secrets from 1Password\n\n```bash\n# Inject to .env.local\nop-env-manager inject --vault \"Personal\" --output .env.local\n\n# Inject production secrets\nop-env-manager inject --vault \"Production\" --item \"myapp\" --output .env.production\n```\n\n### 5. Run commands with secrets\n\n```bash\n# Run docker compose with secrets (no .env file created!)\nop-env-manager run --vault \"Production\" --item \"myapp\" -- docker compose up\n\n# Run any command\nop-env-manager run --vault \"Personal\" -- npm run dev\n```\n\n## Usage\n\n### Commands\n\n```bash\nop-env-manager [global options] \u003ccommand\u003e [options]\n```\n\n### Global Options\n\nAvailable across all commands:\n\n- `-q, --quiet` - Suppress all non-error output (useful for CI/CD pipelines)\n- `-h, --help` - Show help message\n- `-v, --version` - Show version information\n\n**Progress Indicators** (v0.3.0+):\n- Operations with 100+ variables automatically show ASCII progress bars: `[=====\u003e     ] 45/150 (30%)`\n- Progress bars auto-detect terminal type (no output in pipes/redirects)\n- Auto-suppressed in CI/CD environments (detects `CI`, `GITHUB_ACTIONS`, etc.)\n- Can be controlled via environment variables:\n  - `OP_SHOW_PROGRESS=true|false` - Force enable/disable progress bars\n  - `OP_PROGRESS_THRESHOLD=100` - Customize threshold (default: 100 variables)\n\n**Examples:**\n```bash\n# Quiet mode for scripts/CI\nop-env-manager --quiet push --vault \"Production\" --env .env.prod\n\n# Force progress display (override CI detection)\nOP_SHOW_PROGRESS=true op-env-manager push --vault \"Personal\" --env large.env\n\n# Custom threshold (show progress for 50+ variables)\nOP_PROGRESS_THRESHOLD=50 op-env-manager inject --vault \"Dev\"\n```\n\n#### `init` - Interactive Setup Wizard\n\n**New in v0.3.0**: Guided onboarding experience to set up op-env-manager with your 1Password vault.\n\n```bash\nop-env-manager init [options]\n\nOptions:\n  --dry-run              Preview setup flow without making changes\n\nInteractive Flow:\n  1. Vault Selection:    Choose existing vault or create new one\n  2. Item Naming:        Set item name (default: env-secrets)\n  3. .env Detection:     Auto-detect .env files in current directory\n  4. Multi-Environment:  Optional setup for dev/staging/prod\n     - Separate Items:   myapp-dev, myapp-staging, myapp-prod\n     - Sections:         Single item with environment sections\n  5. Initial Push:       Upload selected .env file(s) to 1Password\n  6. Template:           Optionally generate .env.op template file\n  7. Success Summary:    Show next steps and example commands\n\nFeatures:\n  ✅ Vault creation support (if you have permissions)\n  ✅ Smart .env file detection (excludes .example, .bak, .op)\n  ✅ Multi-environment strategies (your choice)\n  ✅ Dry-run mode for preview\n  ✅ Guided best practices\n  ✅ \u003c 2 minute setup time\n\nExamples:\n  # Run interactive wizard\n  op-env-manager init\n\n  # Preview setup flow without changes\n  op-env-manager init --dry-run\n\nUse Cases:\n  - First-time setup\n  - Onboarding new team members\n  - Setting up new projects\n  - Learning op-env-manager workflow\n```\n\n#### `push` - Upload .env to 1Password\n\n```bash\nop-env-manager push --vault VAULT [options]\n\nOptions:\n  --env FILE             .env file to push (default: .env)\n  --vault VAULT          1Password vault name (required)\n  --item NAME            Item name prefix (default: env-secrets)\n  --template             Also generate .env.op template file\n  --template-output FILE Output path for template (default: .env.op)\n  --dry-run              Preview without pushing\n\nExamples:\n  op-env-manager push --vault \"Personal\"\n  op-env-manager push --vault \"Production\" --env .env.prod --item \"api\"\n  op-env-manager push --vault \"Dev\" --dry-run\n  op-env-manager push --vault \"Personal\" --template  # Also generate .env.op\n```\n\n#### `inject` - Download secrets from 1Password\n\n```bash\nop-env-manager inject --vault VAULT [options]\n\nOptions:\n  --vault VAULT       1Password vault name (required)\n  --item NAME         Item name prefix (default: env-secrets)\n  --output FILE       Output file (default: .env)\n  --overwrite         Skip overwrite confirmation\n  --dry-run           Preview without writing\n\nExamples:\n  op-env-manager inject --vault \"Personal\" --output .env.local\n  op-env-manager inject --vault \"Production\" --item \"api\" --overwrite\n  op-env-manager inject --vault \"Staging\" --dry-run\n```\n\n#### `run` - Execute command with secrets\n\n```bash\nop-env-manager run --vault VAULT [options] -- \u003ccommand\u003e\n\nOptions:\n  --vault VAULT          1Password vault name (required)\n  --item NAME            Item name prefix (default: env-secrets)\n  --env-file FILE        Additional .env file to merge\n  --template             Also save .env.op template file\n  --template-output FILE Output path for template (default: .env.op)\n  --no-masking           Show unmasked secrets in command output\n\nExamples:\n  op-env-manager run --vault \"Production\" -- docker compose up\n  op-env-manager run --vault \"Dev\" --item \"api\" -- npm start\n  op-env-manager run --vault \"Staging\" -- python manage.py migrate\n  op-env-manager run --vault \"Personal\" --template -- npm start  # Also save .env.op\n  op-env-manager run --vault \"Personal\" --no-masking -- env      # Show full secret values\n```\n\n#### `diff` - Compare local .env with 1Password\n\nCompare your local `.env` file with the corresponding 1Password vault item to identify differences.\n\n```bash\nop-env-manager diff --vault VAULT [options]\n\nOptions:\n  --vault VAULT       1Password vault name (required)\n  --env-file FILE     .env file to compare (default: .env)\n  --item NAME         Item name prefix (default: env-secrets)\n  --section SECTION   Environment section (e.g., dev, prod)\n  --dry-run           Preview without checking 1Password\n\nExit Codes:\n  0   Files are identical (no differences)\n  1   Differences found\n  2   Error occurred\n\nOutput Format:\n  +  Variable added in 1Password (not in local)\n  -  Variable removed (only in local, not in 1Password)\n  ±  Variable modified (different values)\n\nExamples:\n  # Compare local .env with 1Password\n  op-env-manager diff --vault \"Personal\"\n\n  # Compare specific environment\n  op-env-manager diff --vault \"Projects\" --item \"myapp\" --section \"prod\" --env-file .env.prod\n\n  # Preview what would be compared\n  op-env-manager diff --vault \"Personal\" --dry-run\n\nUse cases:\n  - Check what changed before syncing\n  - Verify push/inject operations\n  - Audit differences between local and remote\n  - CI/CD validation (exit code 0 = in sync)\n```\n\n#### `sync` - Bidirectional synchronization\n\nIntelligently synchronize your local `.env` file with 1Password, handling additions, deletions, and conflicts automatically.\n\n```bash\nop-env-manager sync --vault VAULT [options]\n\nOptions:\n  --vault VAULT       1Password vault name (required)\n  --env-file FILE     .env file to sync (default: .env)\n  --item NAME         Item name prefix (default: env-secrets)\n  --section SECTION   Environment section (e.g., dev, prod)\n  --strategy STRATEGY Conflict resolution strategy (default: interactive)\n                      - interactive: Prompt for each conflict\n                      - ours:        Always prefer local values\n                      - theirs:      Always prefer 1Password values\n                      - newest:      Use most recently modified values\n  --no-backup         Skip automatic backup before sync\n  --dry-run           Preview what would be synced\n\nSync Behavior:\n  + Added:      Variables only in 1Password are pulled to local\n  - Removed:    Variables only in local are removed from 1Password\n  ± Modified:   Variables with different values trigger conflict resolution\n  = Unchanged:  Variables with same values are skipped\n\nState Tracking:\n  Sync creates a .op-env-manager.state file to track the last sync state.\n  This enables accurate three-way merge and prevents false conflicts.\n\nExamples:\n  # Interactive sync (default - prompts for conflicts)\n  op-env-manager sync --vault \"Personal\"\n\n  # Automatic sync strategies\n  op-env-manager sync --vault \"Projects\" --item \"myapp\" --strategy ours     # Prefer local\n  op-env-manager sync --vault \"Projects\" --item \"myapp\" --strategy theirs   # Prefer remote\n  op-env-manager sync --vault \"Projects\" --item \"myapp\" --strategy newest   # Use timestamps\n\n  # Sync with environment sections\n  op-env-manager sync --vault \"Projects\" --item \"myapp\" --section \"dev\" --env-file .env.dev\n\n  # Preview changes before syncing\n  op-env-manager sync --vault \"Personal\" --dry-run\n\n  # Sync without backup (use cautiously)\n  op-env-manager sync --vault \"Personal\" --no-backup\n\nUse cases:\n  - Team collaboration (multiple people updating secrets)\n  - Multi-machine development (keep laptop and desktop in sync)\n  - Gradual migration (sync instead of full push/inject)\n  - Configuration drift prevention\n```\n\n#### `convert` - Migrate from op:// reference format\n\n```bash\nop-env-manager convert --vault VAULT --env FILE [options]\n\nOptions:\n  --env FILE             .env file with op:// references (required)\n  --vault VAULT          Target 1Password vault name (required)\n  --item NAME            Target item name prefix (default: env-secrets)\n  --section SECTION      Environment section (e.g., dev, prod)\n  --template             Also generate .env.op template file\n  --template-output FILE Output path for template (default: .env.op)\n  --dry-run              Preview without converting\n\nExamples:\n  # Convert legacy .env.template with op:// references\n  op-env-manager convert --vault \"Personal\" --env .env.template --item \"myapp\"\n\n  # Convert with environment section\n  op-env-manager convert --vault \"Personal\" --env .env.prod.template --item \"myapp\" --section \"prod\"\n\n  # Preview conversion\n  op-env-manager convert --vault \"Personal\" --env .env.template --dry-run\n\n  # Convert and generate template\n  op-env-manager convert --vault \"Personal\" --env .env.legacy --template\n\nWhat it does:\n  1. Parses .env file with op://vault/item/field references\n  2. Resolves each reference using 'op read'\n  3. Creates Secure Note with resolved values\n  4. No temporary plaintext files created\n\nSee: docs/1password-formats.md for detailed format comparison\n```\n\n#### `template` - Generate op:// reference files\n\n**Enhanced in v0.3.1**: Now supports two modes - generate from 1Password (original) or merge with existing `.env.example` files (preserves comments/structure).\n\nGenerate `.env.op` template files with `op://` secret references that can be safely committed to version control.\n\n```bash\nop-env-manager template --vault VAULT [options]\n\nOptions:\n  --vault VAULT          1Password vault name (required)\n  --item NAME            Item name (default: env-secrets)\n  --section SECTION      Environment section (e.g., dev, prod)\n  --env-file FILE        Template file to merge with (e.g., .env.example) [NEW]\n  --output FILE          Output file (default: .env.op)\n  --dry-run              Preview without generating\n\nMode 1: Generate from 1Password (default):\n  # Generate template from existing 1Password item\n  op-env-manager template --vault \"Personal\" --item \"myapp\"\n\n  # Generate with section (uses $APP_ENV variable)\n  op-env-manager template --vault \"Projects\" --item \"myapp\" --section \"dev\"\n\nMode 2: Merge with existing file (NEW - preserves structure):\n  # Merge .env.example with 1Password references\n  op-env-manager template --vault \"Personal\" --item \"myapp\" --env-file \".env.example\"\n\n  # With section for multi-environment\n  op-env-manager template --vault \"Projects\" --item \"myapp\" --section \"dev\" --env-file \".env.example\"\n\n  # Custom output filename\n  op-env-manager template --vault \"Personal\" --env-file \".env.example\" --output \".env.production.op\"\n\nMerge Mode Behavior (--env-file):\n  - Preserves all comments and structure from source file\n  - Variables in 1Password → replaced with op:// references\n  - Variables NOT in 1Password → kept as-is with WARNING comment\n  - Extra 1Password variables → appended at end with section comment\n\nGenerated Format:\n  # Without section:\n  API_KEY=op://Personal/myapp/API_KEY\n  DATABASE_URL=op://Personal/myapp/DATABASE_URL\n\n  # With section (dynamic):\n  API_KEY=op://Personal/myapp/$APP_ENV/API_KEY\n  DATABASE_URL=op://Personal/myapp/$APP_ENV/DATABASE_URL\n\n  # Merge mode example output:\n  # Application Settings\n  APP_NAME=op://Projects/myapp/$APP_ENV/APP_NAME\n  # WARNING: 'APP_VERSION' not found in 1Password - push this variable first\n  APP_VERSION=1.0.0\n\n  # Additional variables from 1Password (not in original template)\n  JWT_SECRET=op://Projects/myapp/$APP_ENV/JWT_SECRET\n\nUsage with op run:\n  # Set APP_ENV to select section dynamically\n  export APP_ENV=\"dev\"\n  op run --env-file=.env.op -- docker compose up\n\nUsing --template flag:\n  All commands support --template flag to automatically generate .env.op:\n\n  # Push and generate template\n  op-env-manager push --vault \"Personal\" --template\n\n  # Convert and generate template\n  op-env-manager convert --vault \"Personal\" --env .env.legacy --template\n\n  # Run and save template\n  op-env-manager run --vault \"Personal\" --template -- docker compose up\n```\n\n### Multiline Values (v0.2.0+)\n\nThe tool supports multiline values for private keys, certificates, and JSON configurations.\n\n**Supported format:**\n```bash\n# Single-line values (as before)\nAPI_KEY=simple_value\nDATABASE_URL=\"postgresql://localhost/db\"\n\n# Multiline values (wrap in double quotes)\nPRIVATE_KEY=\"-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA1234567890...\naBcDeFgHiJkLmNoPqRsTuVwXyZ...\n-----END RSA PRIVATE KEY-----\"\n\nSSL_CERT=\"-----BEGIN CERTIFICATE-----\nMIIDXTCCAkWgAwIBAgIJAKZ...\n-----END CERTIFICATE-----\"\n\nJSON_CONFIG=\"{\n  \\\"database\\\": {\n    \\\"host\\\": \\\"localhost\\\",\n    \\\"port\\\": 5432\n  },\n  \\\"cache\\\": {\n    \\\"ttl\\\": 3600\n  }\n}\"\n```\n\n**How it works:**\n- Multiline values must be enclosed in double quotes\n- When pushed to 1Password, newlines are converted to `\\n` escape sequences\n- When injected back, escape sequences are converted to actual newlines\n- The injected `.env` file preserves the multiline format with quotes\n\n**Example usage:**\n```bash\n# Push .env with multiline values\nop-env-manager push --vault \"Personal\" --env .env.production\n\n# Inject back - multiline values are restored\nop-env-manager inject --vault \"Personal\" --output .env.local\n\n# Use with runtime injection (no temp files)\nop-env-manager run --vault \"Personal\" -- docker compose up\n```\n\n## Workflows\n\n### Development Team Workflow\n\n**Setup (once per team member)**:\n```bash\n# Team lead: Create shared vault and push secrets\nop-env-manager push --vault \"MyApp-Dev\" --env .env.development\n\n# Team members: Pull secrets\nop-env-manager inject --vault \"MyApp-Dev\" --output .env.local\n```\n\n**Daily development**:\n```bash\n# Run with fresh secrets from 1Password\nop-env-manager run --vault \"MyApp-Dev\" -- docker compose up\n```\n\n**Update secrets**:\n```bash\n# Update in 1Password UI or CLI\n# Team members automatically get updated secrets on next inject/run\n```\n\n### Multi-Environment Deployment\n\n```bash\n# Different vaults for different environments\nop-env-manager push --vault \"MyApp-Dev\" --env .env.dev\nop-env-manager push --vault \"MyApp-Staging\" --env .env.staging\nop-env-manager push --vault \"MyApp-Prod\" --env .env.prod\n\n# Deploy to production\nop-env-manager run --vault \"MyApp-Prod\" -- docker compose -f docker-compose.prod.yml up -d\n```\n\n### CI/CD Integration\n\nUse 1Password Service Accounts for automated pipelines:\n\n```bash\n# Set service account token (in CI environment variables)\nexport OP_SERVICE_ACCOUNT_TOKEN=\"ops_...\"\n\n# Inject secrets in CI pipeline\nop-env-manager inject --vault \"CI-Secrets\" --output .env.ci\n\n# Or run tests with secrets\nop-env-manager run --vault \"CI-Secrets\" -- npm test\n```\n\nSee [1Password Service Accounts docs](https://developer.1password.com/docs/service-accounts/).\n\n### Migrating from op:// References\n\nIf you have existing `.env` files with 1Password secret references (`op://vault/item/field`), use the convert command:\n\n```bash\n# You have: .env.template with op:// references\n# Example: API_KEY=op://Production/api-keys/stripe_key\n\n# Convert to op-env-manager format\nop-env-manager convert \\\n  --env .env.template \\\n  --vault \"Production\" \\\n  --item \"myapp\"\n\n# Now use op-env-manager commands\nop-env-manager run --vault \"Production\" --item \"myapp\" -- docker compose up\n\n# Old workflow still works (both formats can coexist)\nop run --env-file=.env.template -- docker compose up\n```\n\n**Why convert?**\n- Automated item management (no manual creation)\n- Bidirectional sync (push updates back)\n- Organized in single Secure Note per environment\n- Team-friendly structure\n\nSee [docs/1password-formats.md](docs/1password-formats.md) for detailed comparison of the two formats.\n\n## Best Practices\n\n### Security\n\n- ✅ **Never commit `.env` files** - Add to `.gitignore`\n- ✅ **Use separate vaults** for dev/staging/production\n- ✅ **Rotate secrets regularly** - Update in 1Password, team auto-syncs\n- ✅ **Use Service Accounts in CI/CD** - Principle of least privilege\n- ✅ **Prefer `run` over `inject`** - No plaintext files on disk\n\n### Organization\n\n```bash\n# Vault structure\nPersonal/           # Your personal projects\nMyApp-Dev/         # Shared development secrets\nMyApp-Staging/     # Staging environment\nMyApp-Production/  # Production (restricted access)\nCI-CD/             # Service account secrets\n```\n\n### .gitignore\n\nAlways add to your `.gitignore`:\n\n```gitignore\n# Environment files\n.env\n.env.*\n.env.local\n.env.*.local\n!.env.example\n\n# op-env-manager shouldn't be committed\n# (each dev installs separately)\n```\n\n## Troubleshooting\n\n### \"1Password CLI not installed\"\n\nSee [docs/1PASSWORD_SETUP.md](docs/1PASSWORD_SETUP.md) for installation instructions.\n\n### \"Not signed in to 1Password CLI\"\n\n```bash\nop signin\n```\n\n### \"Vault not found\"\n\n```bash\n# List available vaults\nop vault list\n\n# Use exact vault name (case-sensitive)\nop-env-manager push --vault \"Personal\"  # ✅ Correct\nop-env-manager push --vault \"personal\"  # ❌ Wrong case\n```\n\n### \"No items found\"\n\nYou need to push first:\n\n```bash\n# Push .env to create items\nop-env-manager push --vault \"Personal\" --env .env\n\n# Then inject\nop-env-manager inject --vault \"Personal\"\n```\n\n### Permission Issues\n\nCheck vault permissions in 1Password UI - you need read/write access.\n\n## Development\n\n### Project Structure\n\n```\nop-env-manager/\n├── bin/\n│   └── op-env-manager          # Main executable\n├── lib/\n│   ├── logger.sh               # Logging utilities\n│   ├── push.sh                 # Push command\n│   ├── inject.sh               # Inject command\n│   └── convert.sh              # Convert command\n├── docs/\n│   ├── 1PASSWORD_SETUP.md      # 1Password CLI setup guide\n│   ├── 1password-formats.md    # Format comparison guide\n│   ├── CONVERT_TESTING.md      # Convert command testing guide\n│   └── QUICKSTART.md           # Quick reference\n├── examples/\n│   └── .env.example            # Example .env file\n├── install.sh                  # Installation script\n├── README.md                   # This file\n└── LICENSE                     # MIT license\n```\n\n### Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## Roadmap\n\n### Completed (v0.3.0)\n- ✅ `init` command - Interactive vault setup wizard\n- ✅ Progress indicators for large files\n- ✅ Global `--quiet` flag for CI/CD\n- ✅ Retry logic with exponential backoff\n- ✅ Multiline value support\n\n### Upcoming\n\n**v0.4.0** - Synchronization\n- [ ] `diff` command - Compare local .env with 1Password\n- [ ] `sync` command - Bidirectional sync with conflict resolution\n\n**v0.5.0** - Performance\n- [ ] Performance optimizations (parallel operations, caching)\n- [ ] Batch field operations optimization\n\n**v1.0.0** - Distribution\n- [ ] `rotate` command - Generate new secrets and update\n- [ ] Shell script installer (curl | bash)\n- [ ] Homebrew tap\n- [ ] Support for `.env.schema` validation\n- [ ] Docker image for CI/CD\n- [ ] GitHub Action\n\nSee [ROADMAP.md](ROADMAP.md) for detailed information.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Matteo Cervelli**\nTransformation \u0026 Business Scalability Engineer\n\n- GitHub: [@matteocervelli](https://github.com/matteocervelli)\n- Company: [Ad Limen S.r.l.](https://adlimen.it)\n\n## Acknowledgments\n\n- Built on [1Password CLI](https://developer.1password.com/docs/cli/)\n- Inspired by the need for secure, team-friendly secret management\n- Part of my open-source tooling for developer productivity\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/matteocervelli/op-env-manager/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/matteocervelli/op-env-manager/discussions)\n- **1Password CLI**: [1Password Support](https://support.1password.com/)\n\n### Support This Project\n\nIf `op-env-manager` saves you time and improves your team's security, consider supporting its development:\n\n[![Buy Me A Coffee](https://img.shields.io/badge/☕-Buy%20me%20a%20coffee-orange.svg?style=for-the-badge)](https://adli.men/coffee)\n\nYour support helps me:\n- Maintain and improve this tool\n- Create more open-source developer tools\n- Write documentation and tutorials\n- Provide community support\n\n---\n\n**Made with ❤️ for developers who care about security**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatteocervelli%2Fop-env-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatteocervelli%2Fop-env-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatteocervelli%2Fop-env-manager/lists"}