@tolgamorf/env2op-cli 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,8 @@
 # env2op
 
-Convert `.env` files to 1Password Secure Notes and generate template files for `op inject` and `op run`.
+Push `.env` files to 1Password and pull them back with two simple commands.
+
+![env2op demo](demo/env2op-demo.gif)
 
 ## Installation
 
@@ -20,7 +22,18 @@ bunx @tolgamorf/env2op-cli .env Personal "MyApp"
 - [1Password CLI](https://1password.com/downloads/command-line/) installed and signed in
 - [Bun](https://bun.sh) runtime (for best performance)
 
-## Usage
+## Commands
+
+This package provides two commands:
+
+| Command | Description |
+|---------|-------------|
+| `env2op` | Push `.env` to 1Password, generate `.env.tpl` template |
+| `op2env` | Pull secrets from 1Password using `.env.tpl` template |
+
+## env2op (Push)
+
+Push environment variables to 1Password and generate a template file.
 
 ```bash
 env2op <env_file> <vault> <item_name> [options]
@@ -32,6 +45,9 @@ env2op <env_file> <vault> <item_name> [options]
 # Basic usage - creates a Secure Note and generates .env.tpl
 env2op .env.production Personal "MyApp - Production"
 
+# Custom output path for template
+env2op .env Personal "MyApp" -o secrets.tpl
+
 # Preview what would happen without making changes
 env2op .env.production Personal "MyApp" --dry-run
 
@@ -39,38 +55,62 @@ env2op .env.production Personal "MyApp" --dry-run
 env2op .env.production Personal "MyApp" --secret
 
 # Skip confirmation prompts (useful for scripts/CI)
-env2op .env.production Personal "MyApp" -y
+env2op .env.production Personal "MyApp" -f
 ```
 
 ### Options
 
 | Flag | Description |
 |------|-------------|
+| `-o, --output` | Output template path (default: `<env_file>.tpl`) |
+| `-f, --force` | Skip confirmation prompts |
 | `--dry-run` | Preview actions without executing |
 | `--secret` | Store all fields as 'password' type (default: 'text') |
-| `-y, --yes` | Skip confirmation prompts (auto-accept) |
 | `-h, --help` | Show help |
 | `-v, --version` | Show version |
 
-### Overwriting Existing Items
+## op2env (Pull)
 
-If an item with the same name already exists in the vault, env2op will prompt for confirmation before overwriting. Use `-y` or `--yes` to skip the prompt and auto-accept.
+Pull secrets from 1Password to generate a `.env` file.
 
-## How It Works
+```bash
+op2env <template_file> [options]
+```
 
-1. **Parses** your `.env` file to extract environment variables
-2. **Creates** a 1Password Secure Note with all variables as fields
-3. **Generates** a `.tpl` template file with `op://` references
+### Examples
 
-## Using the Generated Template
+```bash
+# Basic usage - generates .env from .env.tpl
+op2env .env.tpl
 
-After running env2op, you'll have a `.env.tpl` file with 1Password references:
+# Custom output path
+op2env .env.tpl -o .env.local
 
-```bash
-# Inject secrets into a new .env file
-op inject -i .env.tpl -o .env
+# Preview without making changes
+op2env .env.tpl --dry-run
+
+# Overwrite existing .env without prompting
+op2env .env.tpl -f
+```
 
-# Run a command with secrets injected
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-o, --output` | Output .env path (default: template without `.tpl`) |
+| `-f, --force` | Overwrite without prompting |
+| `--dry-run` | Preview actions without executing |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+## How It Works
+
+1. **env2op** parses your `.env` file, creates a 1Password Secure Note, and generates a `.tpl` template
+2. **op2env** reads the template and pulls current values from 1Password to create a `.env` file
+
+You can also use the `op run` command to run processes with secrets injected:
+
+```bash
 op run --env-file .env.tpl -- npm start
 ```
 
@@ -99,12 +139,12 @@ Creates a 1Password Secure Note with fields:
 - `API_KEY` (text)
 - `DEBUG` (text)
 
-And generates `.env.tpl`:
+And generates `.env.tpl` with UUID-based references (avoids naming conflicts):
 
 ```env
-DATABASE_URL=op://Personal/MyApp Secrets/DATABASE_URL
-API_KEY=op://Personal/MyApp Secrets/API_KEY
-DEBUG=op://Personal/MyApp Secrets/DEBUG
+DATABASE_URL=op://abc123vaultid/xyz789itemid/def456fieldid
+API_KEY=op://abc123vaultid/xyz789itemid/ghi012fieldid
+DEBUG=op://abc123vaultid/xyz789itemid/jkl345fieldid
 ```
 
 ## Programmatic Usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tolgamorf/env2op-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Convert .env files to 1Password Secure Notes and generate templates for op inject/run",
   "type": "module",
   "main": "src/index.ts",
@@ -13,7 +13,8 @@
     }
   },
   "bin": {
-    "env2op": "src/cli.ts"
+    "env2op": "src/cli.ts",
+    "op2env": "src/op2env-cli.ts"
   },
   "files": [
     "src",
@@ -23,6 +24,8 @@
   "scripts": {
     "dev": "bun run src/cli.ts",
     "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
     "typecheck": "tsc --noEmit",
     "lint": "bunx biome check .",
     "lint:fix": "bunx biome check . --write",

package/src/cli.ts

@@ -9,9 +9,17 @@ const args = process.argv.slice(2);
 // Parse arguments
 const flags = new Set<string>();
 const positional: string[] = [];
-
-for (const arg of args) {
-    if (arg.startsWith("--")) {
+const options: Record<string, string> = {};
+
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-o" || arg === "--output") {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+            options.output = next;
+            i++; // skip next arg
+        }
+    } else if (arg.startsWith("--")) {
         flags.add(arg.slice(2));
     } else if (arg.startsWith("-")) {
         // Handle short flags
@@ -48,9 +56,10 @@ await runConvert({
     envFile,
     vault,
     itemName,
+    output: options.output,
     dryRun: flags.has("dry-run"),
     secret: flags.has("secret"),
-    yes: flags.has("y") || flags.has("yes"),
+    force: flags.has("f") || flags.has("force"),
 });
 
 function showHelp(): void {
@@ -70,9 +79,10 @@ ${pc.bold("ARGUMENTS")}
   ${pc.yellow("item_name")}    Name for the Secure Note in 1Password
 
 ${pc.bold("OPTIONS")}
+  ${pc.cyan("-o, --output")}   Output template path (default: <env_file>.tpl)
+  ${pc.cyan("-f, --force")}    Skip confirmation prompts
   ${pc.cyan("--dry-run")}      Preview actions without executing
   ${pc.cyan("--secret")}       Store all fields as password type (hidden)
-  ${pc.cyan("-y, --yes")}      Skip confirmation prompts (auto-accept)
   ${pc.cyan("-h, --help")}     Show this help message
   ${pc.cyan("-v, --version")}  Show version
 
@@ -80,6 +90,9 @@ ${pc.bold("EXAMPLES")}
   ${pc.dim("# Basic usage")}
   ${pc.cyan("$")} env2op .env.production Personal "MyApp - Production"
 
+  ${pc.dim("# Custom output path")}
+  ${pc.cyan("$")} env2op .env Personal "MyApp" -o secrets.tpl
+
   ${pc.dim("# Preview without making changes")}
   ${pc.cyan("$")} env2op .env Personal "MyApp" --dry-run
 
@@ -87,10 +100,10 @@ ${pc.bold("EXAMPLES")}
   ${pc.cyan("$")} env2op .env Personal "MyApp" --secret
 
   ${pc.dim("# Skip confirmation prompts (for CI/scripts)")}
-  ${pc.cyan("$")} env2op .env Personal "MyApp" -y
+  ${pc.cyan("$")} env2op .env Personal "MyApp" -f
 
 ${pc.bold("DOCUMENTATION")}
-  ${pc.dim("https://github.com/tolgamorf/env2op")}
+  ${pc.dim("https://github.com/tolgamorf/env2op-cli")}
 `);
 }
 

package/src/commands/convert.ts

@@ -11,7 +11,7 @@ import {
     vaultExists,
 } from "../core/onepassword";
 import { generateTemplateContent, generateUsageInstructions, writeTemplate } from "../core/template-generator";
-import type { ConvertOptions } from "../core/types";
+import type { ConvertOptions, CreateItemResult } from "../core/types";
 import { Env2OpError } from "../utils/errors";
 import { logger } from "../utils/logger";
 
@@ -19,7 +19,7 @@ import { logger } from "../utils/logger";
  * Execute the convert operation
  */
 export async function runConvert(options: ConvertOptions): Promise<void> {
-    const { envFile, vault, itemName, dryRun, secret, yes } = options;
+    const { envFile, vault, itemName, output, dryRun, secret, force } = options;
 
     // Display intro
     const pkg = await import("../../package.json");
@@ -41,6 +41,8 @@ export async function runConvert(options: ConvertOptions): Promise<void> {
         }
 
         // Step 2: Create 1Password Secure Note
+        let itemResult: CreateItemResult | null = null;
+
         if (dryRun) {
             logger.warn("Would create Secure Note");
             logger.keyValue("Vault", vault);
@@ -70,8 +72,10 @@ export async function runConvert(options: ConvertOptions): Promise<void> {
             // Check if vault exists
             const vaultFound = await vaultExists(vault);
 
-            if (!vaultFound) {
-                if (yes) {
+            if (vaultFound) {
+                logger.success(`Vault "${vault}" found`);
+            } else {
+                if (force) {
                     // Auto-create vault
                     logger.warn(`Vault "${vault}" not found, creating...`);
                     await createVault(vault);
@@ -99,7 +103,7 @@ export async function runConvert(options: ConvertOptions): Promise<void> {
             const exists = await itemExists(vault, itemName);
 
             if (exists) {
-                if (yes) {
+                if (force) {
                     // Auto-accept: delete and recreate
                     logger.warn(`Item "${itemName}" already exists, overwriting...`);
                     await deleteItem(vault, itemName);
@@ -122,14 +126,14 @@ export async function runConvert(options: ConvertOptions): Promise<void> {
             spinner.start("Creating 1Password Secure Note...");
 
             try {
-                const result = await createSecureNote({
+                itemResult = await createSecureNote({
                     vault,
                     title: itemName,
                     fields: variables,
                     secret,
                 });
 
-                spinner.stop(`Created "${result.title}" in vault "${result.vault}"`);
+                spinner.stop(`Created "${itemResult.title}" in vault "${itemResult.vault}"`);
             } catch (error) {
                 spinner.stop("Failed to create Secure Note");
                 throw error;
@@ -137,21 +141,22 @@ export async function runConvert(options: ConvertOptions): Promise<void> {
         }
 
         // Step 3: Generate template file
-        const templateFileName = `${basename(envFile)}.tpl`;
-        const templatePath = join(dirname(envFile), templateFileName);
-        const templateContent = generateTemplateContent(
-            {
-                vault,
-                itemTitle: itemName,
-                variables,
-                lines,
-            },
-            templateFileName,
-        );
+        const templatePath = output ?? join(dirname(envFile), `${basename(envFile)}.tpl`);
+        const templateFileName = basename(templatePath);
 
         if (dryRun) {
             logger.warn(`Would generate template: ${templatePath}`);
-        } else {
+        } else if (itemResult) {
+            const templateContent = generateTemplateContent(
+                {
+                    vaultId: itemResult.vaultId,
+                    itemId: itemResult.id,
+                    variables,
+                    lines,
+                    fieldIds: itemResult.fieldIds,
+                },
+                templateFileName,
+            );
             writeTemplate(templateContent, templatePath);
             logger.success(`Generated template: ${templatePath}`);
         }

package/src/commands/inject.ts

@@ -0,0 +1,130 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import * as p from "@clack/prompts";
+import { $ } from "bun";
+import { stripHeaders } from "../core/env-parser";
+import { checkOpCli, checkSignedIn } from "../core/onepassword";
+import { generateEnvHeader } from "../core/template-generator";
+import type { InjectOptions } from "../core/types";
+import { Env2OpError } from "../utils/errors";
+import { logger } from "../utils/logger";
+
+/**
+ * Derive output path from template path
+ * .env.tpl -> .env
+ * .env.local.tpl -> .env.local
+ * secrets.tpl -> secrets
+ */
+function deriveOutputPath(templatePath: string): string {
+    if (templatePath.endsWith(".tpl")) {
+        return templatePath.slice(0, -4);
+    }
+    return `${templatePath}.env`;
+}
+
+/**
+ * Execute the inject operation (op2env)
+ */
+export async function runInject(options: InjectOptions): Promise<void> {
+    const { templateFile, output, dryRun, force } = options;
+    const outputPath = output ?? deriveOutputPath(templateFile);
+
+    // Display intro
+    const pkg = await import("../../package.json");
+    logger.intro("op2env", pkg.version, dryRun);
+
+    try {
+        // Step 1: Check template file exists
+        if (!existsSync(templateFile)) {
+            throw new Env2OpError(
+                `Template file not found: ${templateFile}`,
+                "TEMPLATE_NOT_FOUND",
+                "Ensure the file exists and the path is correct",
+            );
+        }
+
+        logger.success(`Found template: ${basename(templateFile)}`);
+
+        // Step 2: Check 1Password CLI
+        if (!dryRun) {
+            const opInstalled = await checkOpCli();
+            if (!opInstalled) {
+                throw new Env2OpError(
+                    "1Password CLI (op) is not installed",
+                    "OP_CLI_NOT_INSTALLED",
+                    "Install from https://1password.com/downloads/command-line/",
+                );
+            }
+
+            const signedIn = await checkSignedIn();
+            if (!signedIn) {
+                throw new Env2OpError(
+                    "Not signed in to 1Password CLI",
+                    "OP_NOT_SIGNED_IN",
+                    'Run "op signin" to authenticate',
+                );
+            }
+        }
+
+        // Step 3: Check if output file exists
+        const outputExists = existsSync(outputPath);
+
+        if (dryRun) {
+            if (outputExists) {
+                logger.warn(`Would overwrite: ${outputPath}`);
+            } else {
+                logger.warn(`Would create: ${outputPath}`);
+            }
+            logger.outro("Dry run complete. No changes made.");
+            return;
+        }
+
+        if (outputExists && !force) {
+            const shouldOverwrite = await p.confirm({
+                message: `File "${outputPath}" already exists. Overwrite?`,
+            });
+
+            if (p.isCancel(shouldOverwrite) || !shouldOverwrite) {
+                logger.cancel("Operation cancelled");
+                process.exit(0);
+            }
+        }
+
+        // Step 4: Run op inject
+        const spinner = logger.spinner();
+        spinner.start("Injecting secrets from 1Password...");
+
+        try {
+            const result = await $`op inject -i ${templateFile} -o ${outputPath} -f`.quiet();
+
+            if (result.exitCode !== 0) {
+                throw new Error(result.stderr.toString());
+            }
+
+            // Strip any existing headers and prepend fresh .env header
+            const rawContent = readFileSync(outputPath, "utf-8");
+            const envContent = stripHeaders(rawContent);
+            const header = generateEnvHeader(basename(outputPath)).join("\n");
+            writeFileSync(outputPath, header + envContent, "utf-8");
+
+            spinner.stop(`Generated: ${outputPath}`);
+        } catch (error) {
+            spinner.stop("Failed to inject secrets");
+            // Extract stderr from Bun shell error
+            const stderr = (error as { stderr?: Buffer })?.stderr?.toString?.();
+            const message = stderr || (error instanceof Error ? error.message : String(error));
+            throw new Env2OpError("Failed to inject secrets from 1Password", "INJECT_FAILED", message);
+        }
+
+        logger.outro("Done! Your .env file is ready");
+    } catch (error) {
+        if (error instanceof Env2OpError) {
+            logger.error(error.message);
+            if (error.suggestion) {
+                logger.info(`Suggestion: ${error.suggestion}`);
+            }
+            process.exit(1);
+        }
+        throw error;
+    }
+}

package/src/core/env-parser.ts

@@ -2,6 +2,44 @@ import { existsSync, readFileSync } from "node:fs";
 import { errors } from "../utils/errors";
 import type { EnvLine, EnvVariable, ParseResult } from "./types";
 
+const HEADER_SEPARATOR = "# ===========================================================================";
+
+/**
+ * Strip env2op/op2env header blocks from content
+ * Headers are delimited by separator lines
+ */
+export function stripHeaders(content: string): string {
+    const lines = content.split("\n");
+    const result: string[] = [];
+    let inHeader = false;
+
+    for (const line of lines) {
+        const trimmed = line.trim();
+
+        if (trimmed === HEADER_SEPARATOR) {
+            if (!inHeader) {
+                // Starting a header block
+                inHeader = true;
+            } else {
+                // Ending a header block
+                inHeader = false;
+            }
+            continue;
+        }
+
+        if (!inHeader) {
+            result.push(line);
+        }
+    }
+
+    // Remove leading empty lines left after stripping header
+    while (result.length > 0 && result[0]?.trim() === "") {
+        result.shift();
+    }
+
+    return result.join("\n");
+}
+
 /**
  * Parse a value from an environment variable line
  * Handles quoted strings and inline comments
@@ -43,7 +81,8 @@ export function parseEnvFile(filePath: string): ParseResult {
         throw errors.envFileNotFound(filePath);
     }
 
-    const content = readFileSync(filePath, "utf-8");
+    const rawContent = readFileSync(filePath, "utf-8");
+    const content = stripHeaders(rawContent);
     const rawLines = content.split("\n");
     const variables: EnvVariable[] = [];
     const lines: EnvLine[] = [];

package/src/core/onepassword.ts

@@ -76,10 +76,22 @@ export async function createSecureNote(options: CreateItemOptions): Promise<Crea
         // Execute op command
         const result = await $`op ${args}`.json();
 
+        // Extract field IDs mapped by label
+        const fieldIds: Record<string, string> = {};
+        if (Array.isArray(result.fields)) {
+            for (const field of result.fields) {
+                if (field.label && field.id) {
+                    fieldIds[field.label] = field.id;
+                }
+            }
+        }
+
         return {
             id: result.id,
             title: result.title,
             vault: result.vault?.name ?? vault,
+            vaultId: result.vault?.id ?? "",
+            fieldIds,
         };
     } catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/src/core/template-generator.ts

@@ -2,27 +2,89 @@ import { writeFileSync } from "node:fs";
 import pkg from "../../package.json";
 import type { TemplateOptions } from "./types";
 
+const SEPARATOR = "# ===========================================================================";
+
+/**
+ * Derive .env filename from template filename
+ * .env.tpl -> .env
+ * .env.local.tpl -> .env.local
+ */
+function deriveEnvFileName(templateFileName: string): string {
+    if (templateFileName.endsWith(".tpl")) {
+        return templateFileName.slice(0, -4);
+    }
+    return templateFileName;
+}
+
+/**
+ * Derive template filename from .env filename
+ * .env -> .env.tpl
+ * .env.local -> .env.local.tpl
+ */
+function deriveTemplateFileName(envFileName: string): string {
+    return `${envFileName}.tpl`;
+}
+
+/**
+ * Generate header for .env.tpl template files
+ */
+export function generateTemplateHeader(templateFileName: string): string[] {
+    const envFileName = deriveEnvFileName(templateFileName);
+    return [
+        SEPARATOR,
+        `#  ${templateFileName} — 1Password Secret References`,
+        "#",
+        "#  This template contains references to secrets stored in 1Password.",
+        "#  The actual values are not stored here — only secret references.",
+        "#",
+        `#  To generate ${envFileName} with real values:`,
+        `#    op2env ${templateFileName}`,
+        "#",
+        "#  To run a command with secrets injected:",
+        `#    op run --env-file ${templateFileName} -- npm start`,
+        "#",
+        `#  Generated by env2op v${pkg.version}`,
+        "#  https://github.com/tolgamorf/env2op-cli",
+        SEPARATOR,
+        "",
+    ];
+}
+
+/**
+ * Generate header for .env files (after pulling from 1Password)
+ */
+export function generateEnvHeader(envFileName: string): string[] {
+    const templateFileName = deriveTemplateFileName(envFileName);
+    return [
+        SEPARATOR,
+        `#  ${envFileName} — Environment Variables`,
+        "#",
+        "#  WARNING: This file contains sensitive values. Do not commit to git!",
+        "#",
+        `#  To push updates to 1Password and generate ${templateFileName}:`,
+        `#    env2op ${envFileName} <vault> "<item_name>"`,
+        "#",
+        `#  Pulled from 1Password by op2env v${pkg.version}`,
+        "#  https://github.com/tolgamorf/env2op-cli",
+        SEPARATOR,
+        "",
+        "",
+    ];
+}
+
 /**
  * Generate op:// reference template content
  *
  * Format: KEY=op://vault/item/field
  *
  * This template can be used with:
- * - `op inject -i template.tpl -o .env`
+ * - `op2env template.tpl` to generate .env
  * - `op run --env-file template.tpl -- command`
  */
 export function generateTemplateContent(options: TemplateOptions, templateFileName: string): string {
-    const { vault, itemTitle, lines: envLines } = options;
+    const { vaultId, itemId, lines: envLines, fieldIds } = options;
 
-    const outputLines: string[] = [
-        `# Generated by env2op v${pkg.version}`,
-        "# https://github.com/tolgamorf/env2op-cli#README",
-        "#",
-        "# Usage:",
-        `#   op inject -i ${templateFileName} -o .env`,
-        `#   op run --env-file ${templateFileName} -- npm start`,
-        "",
-    ];
+    const outputLines: string[] = generateTemplateHeader(templateFileName);
 
     for (const line of envLines) {
         switch (line.type) {
@@ -32,9 +94,11 @@ export function generateTemplateContent(options: TemplateOptions, templateFileNa
             case "comment":
                 outputLines.push(line.content);
                 break;
-            case "variable":
-                outputLines.push(`${line.key}=op://${vault}/${itemTitle}/${line.key}`);
+            case "variable": {
+                const fieldId = fieldIds[line.key] ?? line.key;
+                outputLines.push(`${line.key}=op://${vaultId}/${itemId}/${fieldId}`);
                 break;
+            }
         }
     }
 
@@ -52,10 +116,5 @@ export function writeTemplate(content: string, outputPath: string): void {
  * Generate usage instructions for display
  */
 export function generateUsageInstructions(templatePath: string): string {
-    return [
-        "",
-        "Usage:",
-        `  op inject -i ${templatePath} -o .env`,
-        `  op run --env-file ${templatePath} -- npm start`,
-    ].join("\n");
+    return ["", "Usage:", `  op2env ${templatePath}`, `  op run --env-file ${templatePath} -- npm start`].join("\n");
 }

package/src/core/types.ts

@@ -56,10 +56,14 @@ export interface CreateItemResult {
     title: string;
     /** Vault name */
     vault: string;
+    /** Vault ID */
+    vaultId: string;
+    /** Field IDs mapped by field label */
+    fieldIds: Record<string, string>;
 }
 
 /**
- * Options for the convert command
+ * Options for the convert command (env2op)
  */
 export interface ConvertOptions {
     /** Path to .env file */
@@ -68,24 +72,42 @@ export interface ConvertOptions {
     vault: string;
     /** Secure Note title */
     itemName: string;
+    /** Custom output path for template file */
+    output?: string;
     /** Preview mode - don't make changes */
     dryRun: boolean;
     /** Store all fields as password type */
     secret: boolean;
-    /** Skip confirmation prompts (auto-accept) */
-    yes: boolean;
+    /** Skip confirmation prompts */
+    force: boolean;
+}
+
+/**
+ * Options for the inject command (op2env)
+ */
+export interface InjectOptions {
+    /** Path to template file */
+    templateFile: string;
+    /** Custom output path for .env file */
+    output?: string;
+    /** Preview mode - don't make changes */
+    dryRun: boolean;
+    /** Skip confirmation prompts */
+    force: boolean;
 }
 
 /**
  * Options for template generation
  */
 export interface TemplateOptions {
-    /** Vault name */
-    vault: string;
-    /** Item title in 1Password */
-    itemTitle: string;
+    /** Vault ID */
+    vaultId: string;
+    /** Item ID in 1Password */
+    itemId: string;
     /** Variables to include */
     variables: EnvVariable[];
     /** All lines preserving structure */
     lines: EnvLine[];
+    /** Field IDs mapped by field label */
+    fieldIds: Record<string, string>;
 }

package/src/op2env-cli.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+
+import pc from "picocolors";
+import { runInject } from "./commands/inject";
+
+const pkg = await import("../package.json");
+const args = process.argv.slice(2);
+
+// Parse arguments
+const flags = new Set<string>();
+const positional: string[] = [];
+const options: Record<string, string> = {};
+
+for (let i = 0; i < args.length; i++) {
+    const arg = args[i] as string;
+    if (arg === "-o" || arg === "--output") {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+            options.output = next;
+            i++; // skip next arg
+        }
+    } else if (arg.startsWith("--")) {
+        flags.add(arg.slice(2));
+    } else if (arg.startsWith("-")) {
+        // Handle short flags
+        for (const char of arg.slice(1)) {
+            flags.add(char);
+        }
+    } else {
+        positional.push(arg);
+    }
+}
+
+// Check for help/version flags first
+const hasHelp = flags.has("h") || flags.has("help");
+const hasVersion = flags.has("v") || flags.has("version");
+
+if (hasVersion) {
+    console.log(pkg.version);
+    process.exit(0);
+}
+
+if (hasHelp || positional.length === 0) {
+    showHelp();
+    process.exit(0);
+}
+
+// Run the inject command
+const [templateFile] = positional as [string];
+await runInject({
+    templateFile,
+    output: options.output,
+    dryRun: flags.has("dry-run"),
+    force: flags.has("f") || flags.has("force"),
+});
+
+function showHelp(): void {
+    const name = pc.bold(pc.cyan("op2env"));
+    const version = pc.dim(`v${pkg.version}`);
+
+    console.log(`
+${name} ${version}
+Pull secrets from 1Password to generate .env files
+
+${pc.bold("USAGE")}
+  ${pc.cyan("$")} op2env ${pc.yellow("<template_file>")} ${pc.dim("[options]")}
+
+${pc.bold("ARGUMENTS")}
+  ${pc.yellow("template_file")}  Path to .env.tpl template file
+
+${pc.bold("OPTIONS")}
+  ${pc.cyan("-o, --output")}   Output .env path (default: template without .tpl)
+  ${pc.cyan("-f, --force")}    Overwrite without prompting
+  ${pc.cyan("--dry-run")}      Preview actions without executing
+  ${pc.cyan("-h, --help")}     Show this help message
+  ${pc.cyan("-v, --version")}  Show version
+
+${pc.bold("EXAMPLES")}
+  ${pc.dim("# Basic usage - generates .env from .env.tpl")}
+  ${pc.cyan("$")} op2env .env.tpl
+
+  ${pc.dim("# Custom output path")}
+  ${pc.cyan("$")} op2env .env.tpl -o .env.local
+
+  ${pc.dim("# Preview without making changes")}
+  ${pc.cyan("$")} op2env .env.tpl --dry-run
+
+  ${pc.dim("# Overwrite existing .env without prompting")}
+  ${pc.cyan("$")} op2env .env.tpl -f
+
+${pc.bold("DOCUMENTATION")}
+  ${pc.dim("https://github.com/tolgamorf/env2op-cli")}
+`);
+}

package/src/utils/errors.ts

@@ -25,6 +25,8 @@ export const ErrorCodes = {
     ITEM_EXISTS: "ITEM_EXISTS",
     ITEM_CREATE_FAILED: "ITEM_CREATE_FAILED",
     PARSE_ERROR: "PARSE_ERROR",
+    TEMPLATE_NOT_FOUND: "TEMPLATE_NOT_FOUND",
+    INJECT_FAILED: "INJECT_FAILED",
 } as const;
 
 export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];