chrome-tools 1.0.4 → 1.0.5

package/README.md

@@ -80,8 +80,8 @@ npx chrome-tools passwords
 # Filter credentials using a search term (matches URL or username)
 npx chrome-tools passwords --search "gmail"
 
-# Target a specific profile directory only
-npx chrome-tools passwords --profile "Profile 1"
+# Target a specific profile directory only (placed before the subcommand)
+npx chrome-tools --profile "Profile 1" passwords
 ```
 
 #### Bookmarks
@@ -149,20 +149,20 @@ npx chrome-tools top-sites
 
 ### Global Options
 
-These options apply globally to all subcommands and can be placed anywhere in your command line:
+These options apply globally to all subcommands and should be placed before the command (e.g. `npx chrome-tools --profile-path <path> --profile <name> cookies --url <url>`):
 
-- `--chrome-dir <path>`: Specify a custom Chrome User Data folder (e.g., a backed-up profile from another machine).
-- `--profile <name>`: Limit operations to a single profile directory (e.g., `Default`, `Profile 1`).
+- `--profile-path <path>`: Specify a custom Chrome User Data/profile folder (e.g., a backed-up profile from another machine). Defaults to the `PROFILE_PATH` env/`.env` variable, or falls back to the standard macOS Chrome User Data location.
+- `--profile <name>`: Target a specific profile directory (e.g., `Default`, `Profile 1`). Defaults to the `PROFILE_NAME` env/`.env` variable.
 - `--json`: Output strictly in JSON format (ideal for programmatic pipes or exporting to files).
 - `--limit <number>`: Restrict the output results count (for history, autofill, cookies, etc.).
 
 #### Custom Directory & JSON Examples
 ```bash
 # Export bookmarks from a backed-up Chrome folder directly to a JSON file
-npx chrome-tools bookmarks --chrome-dir "/path/to/backup/Chrome" --json > bookmarks.json
+npx chrome-tools --profile-path "/path/to/backup/Chrome" bookmarks --json > bookmarks.json
 
 # Retrieve all history from a specific profile in JSON format
-npx chrome-tools history --profile "Profile 2" --json --limit 10
+npx chrome-tools --profile-path "/path/to/backup/Chrome" --profile "Profile 2" history --json --limit 10
 ```
 
 ---
@@ -187,7 +187,7 @@ console.log(profiles);
 
 // 2. Fetch bookmarks programmatically
 const githubBookmarks = getBookmarks({
-  chromeDir: "/path/to/chrome/User Data",
+  profilePath: "/path/to/chrome/User Data",
   search: "github"
 });
 
@@ -214,27 +214,28 @@ for (const cred of credentials) {
 ### Available API Modules & Signatures
 
 All core functions accept an options object with the following fields:
-- `chromeDir` *(string)*: Custom Chrome User Data directory.
+- `profilePath` *(string)*: Custom Chrome User Data/profile directory (alias: `chromeDir`).
+- `chromeDir` *(string)*: Alias for `profilePath`.
 - `profile` *(string)*: Specific profile subdirectory name (e.g., `"Default"`).
 - `search` *(string)*: Case-insensitive filter term.
 - `limit` *(number)*: Maximum returned rows count.
 
 | Function | Module Path | Returns |
 | --- | --- | --- |
-| `discoverProfiles(chromeDir)` | `chrome-tools` | `Array<{name, path}>` |
-| `getProfileStates(chromeDir)` | `chrome-tools` | `Array<ProfileState>` |
-| `getPasswords({chromeDir, profile, search})` | `chrome-tools/passwords` | `Array<Credentials>` |
-| `getBookmarks({chromeDir, profile, folder, search})` | `chrome-tools/bookmarks` | `Array<Bookmark>` |
-| `getHistory({chromeDir, profile, search, limit})` | `chrome-tools/history` | `Array<HistoryEntry>` |
-| `getSearchTerms({chromeDir, profile, limit})` | `chrome-tools/history` | `Array<SearchTerm>` |
-| `getCookies({chromeDir, profile, domain, url, decrypt, limit})` | `chrome-tools/cookies` | `Array<Cookie>` |
-| `getAutofillEntries({chromeDir, profile, search, limit})` | `chrome-tools/autofill` | `Array<AutofillEntry>` |
-| `getCreditCards({chromeDir, profile})` | `chrome-tools/autofill` | `Array<CreditCard>` |
-| `getAddresses({chromeDir, profile})` | `chrome-tools/autofill` | `Array<Address>` |
-| `getDownloads({chromeDir, profile, search, limit})` | `chrome-tools/downloads` | `Array<Download>` |
-| `getExtensions({chromeDir, profile, search})` | `chrome-tools/extensions` | `Array<Extension>` |
-| `getSearchEngines({chromeDir, profile})` | `chrome-tools/search-engines` | `Array<SearchEngine>` |
-| `getTopSites({chromeDir, profile})` | `chrome-tools/top-sites` | `Array<TopSite>` |
+| `discoverProfiles(profilePath)` | `chrome-tools` | `Array<{name, path}>` |
+| `getProfileStates(profilePath)` | `chrome-tools` | `Array<ProfileState>` |
+| `getPasswords({profilePath, chromeDir, profile, search})` | `chrome-tools/passwords` | `Array<Credentials>` |
+| `getBookmarks({profilePath, chromeDir, profile, folder, search})` | `chrome-tools/bookmarks` | `Array<Bookmark>` |
+| `getHistory({profilePath, chromeDir, profile, search, limit})` | `chrome-tools/history` | `Array<HistoryEntry>` |
+| `getSearchTerms({profilePath, chromeDir, profile, limit})` | `chrome-tools/history` | `Array<SearchTerm>` |
+| `getCookies({profilePath, chromeDir, profile, domain, url, decrypt, limit})` | `chrome-tools/cookies` | `Array<Cookie>` |
+| `getAutofillEntries({profilePath, chromeDir, profile, search, limit})` | `chrome-tools/autofill` | `Array<AutofillEntry>` |
+| `getCreditCards({profilePath, chromeDir, profile})` | `chrome-tools/autofill` | `Array<CreditCard>` |
+| `getAddresses({profilePath, chromeDir, profile})` | `chrome-tools/autofill` | `Array<Address>` |
+| `getDownloads({profilePath, chromeDir, profile, search, limit})` | `chrome-tools/downloads` | `Array<Download>` |
+| `getExtensions({profilePath, chromeDir, profile, search})` | `chrome-tools/extensions` | `Array<Extension>` |
+| `getSearchEngines({profilePath, chromeDir, profile})` | `chrome-tools/search-engines` | `Array<SearchEngine>` |
+| `getTopSites({profilePath, chromeDir, profile})` | `chrome-tools/top-sites` | `Array<TopSite>` |
 
 ---
 

package/bin/cli.js

@@ -7,12 +7,13 @@
  * Supports subcommands and shortcut flags for quick access to all data types.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
 import { Command } from "commander";
 import chalk from "chalk";
 import Table from "cli-table3";
 
-import { discoverProfiles, getProfileMetadata, getProfileStates } from "../src/core/chrome.js";
+import { discoverProfiles, getProfileMetadata, getProfileStates, getDefaultChromeDir } from "../src/core/chrome.js";
 import { getPasswords } from "../src/modules/passwords.js";
 import { getBookmarks } from "../src/modules/bookmarks.js";
 import { getHistory, getSearchTerms } from "../src/modules/history.js";
@@ -23,6 +24,39 @@ import { getExtensions } from "../src/modules/extensions.js";
 import { getSearchEngines } from "../src/modules/search-engines.js";
 import { getTopSites } from "../src/modules/top-sites.js";
 
+// ─── Environment Loading ─────────────────────────────────────────────────────
+
+function loadEnv() {
+  const env = { ...process.env };
+  const envPath = join(process.cwd(), ".env");
+  if (existsSync(envPath)) {
+    try {
+      const content = readFileSync(envPath, "utf8");
+      for (const line of content.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const index = trimmed.indexOf("=");
+        if (index !== -1) {
+          const key = trimmed.substring(0, index).trim();
+          let val = trimmed.substring(index + 1).trim();
+          // Remove wrapping quotes
+          if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+          }
+          env[key] = val;
+        }
+      }
+    } catch {
+      // Ignore
+    }
+  }
+  return env;
+}
+
+const env = loadEnv();
+const defaultProfilePath = env.PROFILE_PATH || getDefaultChromeDir();
+const defaultProfileName = env.PROFILE_NAME || undefined;
+
 // ─── Output Helpers ──────────────────────────────────────────────────────────
 
 function outputJSON(data) {
@@ -50,8 +84,8 @@ function printCount(label, count) {
 
 function addCommonOptions(cmd) {
   return cmd
-    .option("--chrome-dir <path>", "Custom Chrome User Data directory")
-    .option("--profile <name>", "Target a specific profile")
+    .option("--profile-path <path>", "Custom Chrome Profile Path", defaultProfilePath)
+    .option("--profile <name>", "Target a specific profile", defaultProfileName)
     .option("--json", "Output as JSON");
 }
 
@@ -79,25 +113,11 @@ program
   .option("--passwords", "Shortcut: list saved passwords")
   .option("--bookmarks", "Shortcut: list bookmarks")
   .option("--profiles", "Shortcut: list profiles")
-  .option("--chrome-dir <path>", "Custom Chrome User Data directory")
-  .option("--profile <name>", "Target a specific profile")
+  .option("--profile-path <path>", "Custom Chrome Profile Path", defaultProfilePath)
+  .option("--profile <name>", "Target a specific profile", defaultProfileName)
   .option("--json", "Output as JSON")
   .option("--search <term>", "Filter results (for shortcut flags)")
-  .option("--limit <n>", "Limit results (for shortcut flags)")
-  .action((opts) => {
-    // Handle shortcut flags at the top level
-    if (opts.passwords) {
-      return handlePasswords(opts);
-    }
-    if (opts.bookmarks) {
-      return handleBookmarks(opts);
-    }
-    if (opts.profiles) {
-      return handleProfiles(opts);
-    }
-    // No shortcut flag — show help
-    program.help();
-  });
+  .option("--limit <n>", "Limit results (for shortcut flags)");
 
 // ─── Profiles Command ───────────────────────────────────────────────────────
 
@@ -112,13 +132,13 @@ addCommonOptions(profilesCmd).action((opts, cmd) => {
 profilesCmd
   .command("states")
   .description("Show detailed profile states with available data files")
-  .option("--chrome-dir <path>", "Custom Chrome User Data directory")
+  .option("--profile-path <path>", "Custom Chrome Profile Path", defaultProfilePath)
   .option("--json", "Output as JSON")
   .action((opts, cmd) => handleProfileStates(cmd.optsWithGlobals()));
 
 function handleProfiles(opts) {
-  const profiles = discoverProfiles(opts.chromeDir);
-  const metadata = getProfileMetadata(opts.chromeDir);
+  const profiles = discoverProfiles(opts.profilePath);
+  const metadata = getProfileMetadata(opts.profilePath);
 
   if (opts.json) {
     const metaMap = new Map(metadata.map((m) => [m.directory, m]));
@@ -154,7 +174,7 @@ function handleProfiles(opts) {
 }
 
 function handleProfileStates(opts) {
-  const states = getProfileStates(opts.chromeDir);
+  const states = getProfileStates(opts.profilePath);
 
   if (opts.json) {
     return outputJSON(states);
@@ -193,11 +213,11 @@ function handleProfileStates(opts) {
 // ─── Passwords Command ──────────────────────────────────────────────────────
 
 const passwordsCmd = program.command("passwords").description("List saved passwords");
-addCommonOptions(addSearchOption(passwordsCmd)).action((opts, cmd) => handlePasswords(cmd.optsWithGlobals()));
+addSearchOption(addCommonOptions(passwordsCmd)).action((opts, cmd) => handlePasswords(cmd.optsWithGlobals()));
 
 function handlePasswords(opts) {
   const results = getPasswords({
-    chromeDir: opts.chromeDir,
+    chromeDir: opts.profilePath,
     profile: opts.profile,
     search: opts.search,
   });
@@ -233,13 +253,13 @@ function handlePasswords(opts) {
 // ─── Bookmarks Command ──────────────────────────────────────────────────────
 
 const bookmarksCmd = program.command("bookmarks").description("List bookmarks");
-addCommonOptions(addSearchOption(bookmarksCmd))
+addSearchOption(addCommonOptions(bookmarksCmd))
   .option("--folder <name>", "Filter by folder name")
   .action((opts, cmd) => handleBookmarks(cmd.optsWithGlobals()));
 
 function handleBookmarks(opts) {
   const results = getBookmarks({
-    chromeDir: opts.chromeDir,
+    chromeDir: opts.profilePath,
     profile: opts.profile,
     folder: opts.folder,
     search: opts.search,
@@ -268,10 +288,10 @@ function handleBookmarks(opts) {
 // ─── History Command ─────────────────────────────────────────────────────────
 
 const historyCmd = program.command("history").description("List browsing history");
-addCommonOptions(addSearchOption(addLimitOption(historyCmd))).action((opts, cmd) => {
+addSearchOption(addLimitOption(addCommonOptions(historyCmd))).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getHistory({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
     search: mergedOpts.search,
     limit: parseInt(mergedOpts.limit, 10) || 100,
@@ -300,10 +320,10 @@ addCommonOptions(addSearchOption(addLimitOption(historyCmd))).action((opts, cmd)
 // ─── Search Terms Command ────────────────────────────────────────────────────
 
 const searchTermsCmd = program.command("search-terms").description("List search terms from history");
-addCommonOptions(addLimitOption(searchTermsCmd)).action((opts, cmd) => {
+addLimitOption(addCommonOptions(searchTermsCmd)).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getSearchTerms({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
     limit: parseInt(mergedOpts.limit, 10) || 100,
   });
@@ -326,14 +346,14 @@ addCommonOptions(addLimitOption(searchTermsCmd)).action((opts, cmd) => {
 // ─── Cookies Command ─────────────────────────────────────────────────────────
 
 const cookiesCmd = program.command("cookies").description("List cookies (encrypted values decrypted)");
-addCommonOptions(addLimitOption(cookiesCmd))
+addLimitOption(addCommonOptions(cookiesCmd))
   .option("--domain <domain>", "Filter by domain")
   .option("--url <url>", "Filter by URL with path")
   .option("--no-decrypt", "Skip decryption of encrypted values")
   .action((opts, cmd) => {
     const mergedOpts = cmd.optsWithGlobals();
     const results = getCookies({
-      chromeDir: mergedOpts.chromeDir,
+      chromeDir: mergedOpts.profilePath,
       profile: mergedOpts.profile,
       domain: mergedOpts.domain,
       url: mergedOpts.url,
@@ -365,10 +385,10 @@ addCommonOptions(addLimitOption(cookiesCmd))
 // ─── Autofill Command ────────────────────────────────────────────────────────
 
 const autofillCmd = program.command("autofill").description("List autofill entries");
-addCommonOptions(addSearchOption(addLimitOption(autofillCmd))).action((opts, cmd) => {
+addSearchOption(addLimitOption(addCommonOptions(autofillCmd))).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getAutofillEntries({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
     search: mergedOpts.search,
     limit: parseInt(mergedOpts.limit, 10) || 100,
@@ -400,7 +420,7 @@ const creditCardsCmd = program.command("credit-cards").description("List saved c
 addCommonOptions(creditCardsCmd).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getCreditCards({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
   });
 
@@ -430,7 +450,7 @@ const addressesCmd = program.command("addresses").description("List saved addres
 addCommonOptions(addressesCmd).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getAddresses({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
   });
 
@@ -458,10 +478,10 @@ addCommonOptions(addressesCmd).action((opts, cmd) => {
 // ─── Downloads Command ───────────────────────────────────────────────────────
 
 const downloadsCmd = program.command("downloads").description("List download history");
-addCommonOptions(addSearchOption(addLimitOption(downloadsCmd))).action((opts, cmd) => {
+addSearchOption(addLimitOption(addCommonOptions(downloadsCmd))).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getDownloads({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
     search: mergedOpts.search,
     limit: parseInt(mergedOpts.limit, 10) || 100,
@@ -493,10 +513,10 @@ addCommonOptions(addSearchOption(addLimitOption(downloadsCmd))).action((opts, cm
 // ─── Extensions Command ─────────────────────────────────────────────────────
 
 const extensionsCmd = program.command("extensions").description("List installed extensions");
-addCommonOptions(addSearchOption(extensionsCmd)).action((opts, cmd) => {
+addSearchOption(addCommonOptions(extensionsCmd)).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getExtensions({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
     search: mergedOpts.search,
   });
@@ -528,7 +548,7 @@ const searchEnginesCmd = program.command("search-engines").description("List con
 addCommonOptions(searchEnginesCmd).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getSearchEngines({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
   });
 
@@ -558,7 +578,7 @@ const topSitesCmd = program.command("top-sites").description("List top sites");
 addCommonOptions(topSitesCmd).action((opts, cmd) => {
   const mergedOpts = cmd.optsWithGlobals();
   const results = getTopSites({
-    chromeDir: mergedOpts.chromeDir,
+    chromeDir: mergedOpts.profilePath,
     profile: mergedOpts.profile,
   });
 
@@ -593,3 +613,17 @@ function formatBytes(bytes) {
 // ─── Run ─────────────────────────────────────────────────────────────────────
 
 program.parse();
+
+const rootOpts = program.opts();
+const hasSubcommand = program.args.length > 0;
+if (!hasSubcommand) {
+  if (rootOpts.passwords) {
+    handlePasswords(rootOpts);
+  } else if (rootOpts.bookmarks) {
+    handleBookmarks(rootOpts);
+  } else if (rootOpts.profiles) {
+    handleProfiles(rootOpts);
+  } else {
+    program.help();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-tools",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "CLI & Node.js library to extract Chrome browser data (bookmarks, history, cookies, autofill, extensions, and more) on macOS",
   "type": "module",
   "main": "./src/index.js",

package/src/core/chrome.js

@@ -158,12 +158,13 @@ export function resolveProfilePath(chromeDir, profileName) {
  * Otherwise returns all discovered profiles.
  *
  * @param {Object} options
- * @param {string} [options.chromeDir] - Chrome User Data path.
+ * @param {string} [options.profilePath] - Custom Chrome User Data/profile directory.
+ * @param {string} [options.chromeDir] - Chrome User Data path (alias for profilePath).
  * @param {string} [options.profile] - Specific profile name to target.
  * @returns {Array<{name: string, path: string}>}
  */
-export function resolveTargetProfiles({ chromeDir, profile } = {}) {
-  const dir = chromeDir || getDefaultChromeDir();
+export function resolveTargetProfiles({ profilePath, chromeDir, profile } = {}) {
+  const dir = profilePath || chromeDir || getDefaultChromeDir();
   const allProfiles = discoverProfiles(dir);
 
   if (profile) {