adspower-browser 2.0.0-beta.0 → 2.0.0-beta.2

package/README.MD

@@ -8,6 +8,16 @@ AdsPower browser automation CLI for AI agents.
 npm install -g adspower-browser
 ```
 
+After installation, you can use any of these equivalent commands:
+
+```bash
+adspower-browser
+adspower
+ads
+```
+
+`adspower-browser` is the original command name. `adspower` and `ads` are aliases that point to the same CLI entry.
+
 ## Install as Cursor / Agent Skill
 
 Skills live at the repo root. Install with:
@@ -23,80 +33,120 @@ npx skills add AdsPower/adspower-browser
 
 Use the CLI in terminal or let the agent run it; the installed skill gives the agent context on when and how to call `adspower-browser` (profiles, groups, proxies, etc.).
 
-
 ## How to Run
 
+The examples below use `ads` for brevity, but `adspower-browser` and `adspower` work the same way.
+
 ```bash
-adspower-browser [--port PORT] [--api-key KEY] <command> [<arg>]
+ads start -k <KEY>
+```
+
+If the `ADS_API_KEY` environment variable is set, you can start the CLI directly with the following command.
+
+```bash
+ads start
 ```
 
 **Two forms for `<arg>`:**
 
 1. **Single value (shorthand)** — for profile-related commands, pass one profile ID or number:
-   - `adspower-browser open-browser <ProfileId>`
-   - `adspower-browser close-browser <ProfileId>`
-   - `adspower-browser get-profile-cookies <ProfileId>`
-   - `adspower-browser get-browser-active <ProfileId>`
-   - `adspower-browser get-profile-ua <ProfileId>` (single ID)
-   - `adspower-browser new-fingerprint <ProfileId>` (single ID)
+   - `ads open-browser <ProfileId>`
+   - `ads close-browser <ProfileId>`
+   - `ads get-profile-cookies <ProfileId>`
+   - `ads get-browser-active <ProfileId>`
+   - `ads get-profile-ua <ProfileId>` (single ID)
+   - `ads new-fingerprint <ProfileId>` (single ID)
 
 2. **JSON string** — full parameters for any command (see Command Reference below):
-   - `adspower-browser open-browser '{"profileId":"abc123","launchArgs":"..."}'`
+   - `ads open-browser '{"profileId":"abc123","launchArgs":"..."}'`
    - Commands with no params: omit `<arg>` or use `'{}'`.
 
-## Essential Commands
+## Essential Commands With CLI
+
+You can use `ads -h` or `ads <command> -h` to view the specific parameters.
+
+### Start and stop CLI
+
+```bash
+ads start -k <KEY>                    # Start the adspower runtime
+ads stop                              # Stop the adspower runtime
+ads restart                           # Restart the adspower runtime
+ads status                            # Get the status of the adspower runtime
+```
 
 ### Browser profile – open/close
 
 ```bash
-adspower-browser open-browser <profileId>                    # Or JSON: profileId, profileNo?, ipTab?, launchArgs?, clearCacheAfterClosing?, cdpMask?
-adspower-browser close-browser <profileId>                   # Or JSON: profileId? | profileNo? (one required)
+ads open-browser <profileId>                    # Or JSON: profileId, profileNo?, ipTab?, launchArgs?, clearCacheAfterClosing?, cdpMask?
+ads close-browser <profileId>                   # Or JSON: profileId? | profileNo? (one required)
 ```
 
 ### Browser profile – create/update/delete/list
 
 ```bash
-adspower-browser create-browser '{"groupId":"0","proxyid":"random",...}'  # groupId + account field + proxy required
-adspower-browser update-browser '{"profileId":"...",...}'    # profileId required
-adspower-browser delete-browser '{"profileIds":["..."]}'     # profileIds required
-adspower-browser get-browser-list '{}'                       # Or groupId?, limit?, page?, profileId?, profileNo?, sortType?, sortOrder?
-adspower-browser get-opened-browser                          # No params
+ads create-browser '{"groupId":"0","proxyid":"random",...}'  # groupId + account field + proxy required
+ads update-browser '{"profileId":"...",...}'    # profileId required
+ads delete-browser '{"profileIds":["..."]}'     # profileIds required
+ads get-browser-list '{}'                       # Or groupId?, limit?, page?, profileId?, profileNo?, sortType?, sortOrder?
+ads get-opened-browser                          # No params
 ```
 
 ### Browser profile – move/cookies/UA/fingerprint/cache/share/active
 
 ```bash
-adspower-browser move-browser '{"groupId":"1","userIds":["..."]}'   # groupId + userIds required
-adspower-browser get-profile-cookies <profileId>             # Or JSON: profileId? | profileNo?
-adspower-browser get-profile-ua <profileId>                  # Or JSON: profileId[]? | profileNo[]? (up to 10)
-adspower-browser close-all-profiles                          # No params
-adspower-browser new-fingerprint <profileId>                 # Or JSON: profileId[]? | profileNo[]? (up to 10)
-adspower-browser delete-cache-v2 '{"profileIds":["..."],"type":["cookie","history"]}'  # type: local_storage|indexeddb|extension_cache|cookie|history|image_file
-adspower-browser share-profile '{"profileIds":["..."],"receiver":"email@example.com"}' # receiver required; shareType?, content?
-adspower-browser get-browser-active <profileId>              # Or JSON: profileId? | profileNo?
-adspower-browser get-cloud-active '{"userIds":"id1,id2"}'    # userIds comma-separated, max 100
+ads move-browser '{"groupId":"1","userIds":["..."]}'   # groupId + userIds required
+ads get-profile-cookies <profileId>             # Or JSON: profileId? | profileNo?
+ads get-profile-ua <profileId>                  # Or JSON: profileId[]? | profileNo[]? (up to 10)
+ads close-all-profiles                          # No params
+ads new-fingerprint <profileId>                 # Or JSON: profileId[]? | profileNo[]? (up to 10)
+ads delete-cache-v2 '{"profileIds":["..."],"type":["cookie","history"]}'  # type: local_storage|indexeddb|extension_cache|cookie|history|image_file
+ads share-profile '{"profileIds":["..."],"receiver":"email@example.com"}' # receiver required; shareType?, content?
+ads get-browser-active <profileId>              # Or JSON: profileId? | profileNo?
+ads get-cloud-active '{"userIds":"id1,id2"}'    # userIds comma-separated, max 100
 ```
 
 ### Group
 
 ```bash
-adspower-browser create-group '{"groupName":"My Group","remark":"..."}'   # groupName required
-adspower-browser update-group '{"groupId":"1","groupName":"New Name"}'    # groupId + groupName required; remark? (null to clear)
-adspower-browser get-group-list '{}'                         # groupName?, size?, page?
+ads create-group '{"groupName":"My Group","remark":"..."}'   # groupName required
+ads update-group '{"groupId":"1","groupName":"New Name"}'    # groupId + groupName required; remark? (null to clear)
+ads get-group-list '{}'                         # groupName?, size?, page?
 ```
 
 ### Application (categories)
 
 ```bash
-adspower-browser check-status                                # No params – API availability
-adspower-browser get-application-list '{}'                   # category_id?, page?, limit?
+ads check-status                                # No params – API availability
+ads get-application-list '{}'                   # category_id?, page?, limit?
 ```
 
 ### Proxy
 
 ```bash
-adspower-browser create-proxy '{"proxies":[{"type":"http","host":"127.0.0.1","port":"8080"}]}'  # type, host, port required per item
-adspower-browser update-proxy '{"proxyId":"...","host":"..."}'   # proxyId required
-adspower-browser get-proxy-list '{}'                         # limit?, page?, proxyId?
-adspower-browser delete-proxy '{"proxyIds":["..."]}'        # proxyIds required, max 100
+ads create-proxy '{"proxies":[{"type":"http","host":"127.0.0.1","port":"8080"}]}'  # type, host, port required per item
+ads update-proxy '{"proxyId":"...","host":"..."}'   # proxyId required
+ads get-proxy-list '{}'                         # limit?, page?, proxyId?
+ads delete-proxy '{"proxyIds":["..."]}'        # proxyIds required, max 100
 ```
+
+### Tag
+
+```bash
+ads get-tag-list '{}'  # limit?, page?, ids?
+ads create-tag '{"tags":[{"name":"test","color":"darkBlue"}]}'   # name required, color?: darkBlue|blue|purple|red|yellow|orange|green|lightGreen
+ads update-tag '{"tags":[{"id":"...","name":"test2","color":"yellow"}]}'                         # id required,name?, color?: darkBlue|blue|purple|red|yellow|orange|green|lightGreen
+ads delete-tag '{"ids":["..."]}'        # ids required, max 100
+```
+
+### Kernel
+
+```bash
+ads get-kernel-list '{"kernel_type":"Chrome"}'  # kernel_type?:Chrome|Firefox
+ads download-kernel '{"kernel_type":"Chrome","kernel_version":"..."}'   # kernel_type:Chrome|Firefox required,kernel_version required
+```
+
+### Update Patch
+
+```bash
+ads update-patch '{"version_type":"stable"}'  # version_type?:stable|beta
+```

package/cli/index.js

@@ -53,6 +53,9 @@ var Store = class {
     this.pid = "";
   }
   getStoreValue(key) {
+    if (key === "apiKey" && !this.apiKey) {
+      return process.env.ADS_API_KEY || "";
+    }
     return this[key];
   }
   setStoreValue(key, value) {
@@ -205,8 +208,12 @@ var getApiKeyAndPort = (options) => {
     port
   };
   const processInstance = readPidFile();
-  if (!apiKey && processInstance.apiKey) {
-    result.apiKey = processInstance.apiKey;
+  if (!apiKey) {
+    if (processInstance.apiKey) {
+      result.apiKey = processInstance.apiKey;
+    } else if (process.env.ADS_API_KEY) {
+      result.apiKey = process.env.ADS_API_KEY;
+    }
   }
   if (!port && processInstance.apiPort) {
     result.port = processInstance.apiPort;
@@ -274,6 +281,43 @@ var initSqlite3 = () => {
     logSuccess(`[i] SQLite file initialized successfully!`);
   }
 };
+var renderKernelProgress = (result) => {
+  const status = result.status || "pending";
+  const progress = ["completed", "installing"].includes(status) ? 100 : Math.max(0, Math.min(100, Number(result.progress) || 0));
+  if (!process.stdout.isTTY) {
+    logInfo(`Kernel progress: ${progress}% [${status}]`);
+    return;
+  }
+  const width = 30;
+  const filled = Math.round(progress / 100 * width);
+  const bar = `${"=".repeat(filled)}${"-".repeat(width - filled)}`;
+  process.stdout.write(`\r[${bar}] ${progress.toFixed(0).padStart(3, " ")}% ${status}     `);
+};
+var finishKernelProgress = () => {
+  if (process.stdout.isTTY) {
+    process.stdout.write("\n");
+  }
+};
+var trackKernelDownload = async (fnc, args) => {
+  while (true) {
+    const result = await fnc(args);
+    try {
+      const resultJson = JSON.parse(result.replace("Kernel download/update status: ", ""));
+      if (resultJson && resultJson.status && ["pending", "downloading", "completed", "installing", "failed"].includes(resultJson.status)) {
+        renderKernelProgress(resultJson);
+        if (["completed", "failed"].includes(resultJson.status)) {
+          finishKernelProgress();
+          return result;
+        }
+        await sleepTime(3e3);
+      } else {
+        return result;
+      }
+    } catch (error) {
+      return result;
+    }
+  }
+};
 
 // src/core/start.ts
 var getEnv = () => {
@@ -511,7 +555,7 @@ function parseArgs() {
     }
   }
   return {
-    port: port || process.env.PORT || "50326",
+    port: port || process.env.PORT || "50325",
     apiKey: apiKey || process.env.API_KEY
   };
 }
@@ -2048,9 +2092,16 @@ var SINGLE_PROFILE_ID_ARRAY_COMMANDS = ["get-profile-ua", "new-fingerprint"];
 // src/index.ts
 var program = new import_commander.Command();
 program.name("adspower-browser").description("CLI and runtime for adspower-browser").version(VERSION);
-program.command("start").description("Start the adspower runtime").requiredOption("-k, --api-key <apiKey>", "Set the API key for the adspower runtime").addOption(new import_commander.Option("--base-url <baseUrl>", "Set the base URL for the adspower runtime").hideHelp()).addOption(new import_commander.Option("--node-env <nodeEnv>", "Set the node environment for the adspower runtime").hideHelp()).action(async (options) => {
+program.command("start").description("Start the adspower runtime").option("-k, --api-key <apiKey>", "Set the API key for the adspower runtime").addOption(new import_commander.Option("--base-url <baseUrl>", "Set the base URL for the adspower runtime").hideHelp()).addOption(new import_commander.Option("--node-env <nodeEnv>", "Set the node environment for the adspower runtime").hideHelp()).action(async (options) => {
   if (options.apiKey) {
     store.setStoreValue("apiKey", options.apiKey);
+  } else {
+    const apiKey = process.env.ADS_API_KEY;
+    if (!apiKey) {
+      logError("error: required option '-k, --api-key <apiKey>' not specified");
+      process.exit(1);
+    }
+    store.setStoreValue("apiKey", "");
   }
   if (options.baseUrl) {
     store.setStoreValue("baseUrl", options.baseUrl);
@@ -2112,15 +2163,27 @@ for (const cmd of Object.keys(STATELESS_HANDLERS)) {
     logSuccess(`Executing command: ${command.name()}, params: ${JSON.stringify(args)}`);
     const loading = createLoading(`Executing ${command.name()}...`);
     try {
-      const result = await fnc(args);
-      const out = typeof result === "string" ? result : JSON.stringify(result, null, 2);
-      logInfo(`
+      if (command.name() === "download-kernel") {
+        loading.stop();
+        const result = await trackKernelDownload(fnc, args);
+        const out = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        logInfo(`
+
+${out}
+
+`);
+      } else {
+        const result = await fnc(args);
+        const out = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        logInfo(`
 
 ${out}
 `);
-      if (command.name() === "update-patch") {
-        await sleepTime(1e3 * 60);
-        await restartChild();
+        if (command.name() === "update-patch" && !out.includes("The client is already on the latest patch version. No update is required")) {
+          loading.stop();
+          await sleepTime(1e3 * 60);
+          await restartChild();
+        }
       }
     } finally {
       loading.stop();