02 — AdsPower CLI + Hermes Skill Layer
The adspower-browser npm package exposes AdsPower’s Local API as a shell CLI. It is also shipped as a Hermes skill (adspower-browser) so that the agent can call the CLI directly from the terminal without any MCP server running. This document covers the CLI surface, the skill’s intent mapping, and the critical capability boundary the Reddit workflow must respect.
1. Installation & Aliases
npm install -g adspower-browserThree equivalent commands are installed; they all hit the same entry point:
| Command | Role |
|---|---|
adspower-browser | Original/canonical name |
adspower | Alias |
ads | Alias (used in all examples below) |
Shell tab completion is available via ads complete <shell> (zsh / bash / PowerShell / Git Bash). Not required for Hermes usage but handy on an interactive host.
The skill is already installed in Hermes at /opt/data/skills/adspower-browser/ (14 reference files). The skill is loaded automatically when a user phrase matches its triggers (see §6).
2. Authentication & Runtime
AdsPower’s Local API runs on the user’s machine (default port 50325). The CLI talks to that local API. Two ways to authenticate:
| Method | Command | Notes |
|---|---|---|
| Inline API key | ads start -k <KEY> | One-shot; key not persisted |
| Env var | export ADS_API_KEY=<KEY> then ads start | Recommended for Hermes runs |
General command form:
ads <command> [<arg>] [--port PORT] [--api-key KEY]Runtime management commands:
| Command | Purpose |
|---|---|
ads start [-k KEY] | Start the AdsPower Local API runtime |
ads stop | Stop the runtime |
ads restart | Restart the runtime |
ads status | Get runtime status |
ads check-status | Ping the Local API for availability (no params) |
AdsPower client headless mode (Linux example):
adspower_global --headless=true --api-key=<KEY> --api-port=50325Argument forms — two variants:
- Shorthand (single profile ID or number):
ads open-browser <profile_id>. Numeric tokens are treated asprofile_no. Used byopen-browser,close-browser,get-profile-cookies,get-browser-active,get-profile-ua,new-fingerprint. - JSON string (full parameters):
ads open-browser '{"profile_id":"abc123","headless":"1"}'. Commands with no params: omit<arg>or pass'{}'.
Help: ads -h or ads <command> -h.
3. Complete Command Catalog
3.1 Profile CRUD — create / update / delete / list
| Command | Required fields | Key optional fields |
|---|---|---|
create-browser | group_id (use "0" for Ungrouped) + one of username/password/cookie/fakey | user_proxy_config (default no_proxy; ignored if proxyid given), proxyid ("random" allowed), name, platform, remark, tabs, fingerprint_config, profile_tag_ids (max 30), country (lowercase 2-letter), region, city, ipchecker (ip2location|ipapi|ipfoxy) |
update-browser | profile_id | Same fields as create, plus tags_update_type ('1' replace all, '2' append) |
delete-browser | profile_id (array) | — |
get-browser-list | — (CLI defaults page=1, limit=200) | group_id, limit (1–200), page, profile_id[], profile_no[], sort_type (profile_no|last_open_time|created_time), sort_order (asc|desc), tag_ids, tags_filter (include|exclude), name, name_filter |
get-opened-browser | — | None — lists profiles currently open on this device |
Pagination note: the CLI sends page=1, limit=200 by default (the raw API returns only 1 per call). Response includes total_count and total_pages. For “operate on all profiles in a group” tasks, loop page until total_pages exhausted, then act on every collected profile_id — never just the first page.
3.2 Profile Operations — open / close / cookies / UA / fingerprint / cache / share / active
| Command | Purpose | Notes |
|---|---|---|
open-browser <id> | Launch a profile’s browser | Optional: headless, launch_args (URL or Chrome args), ip_tab, last_opened_tabs, proxy_detection, password_filling, password_saving, delete_cache, cdp_mask, device_scale |
close-browser <id> | Stop a running profile | profile_id OR profile_no |
close-all-profiles | Close every opened profile on this device | No params |
move-browser | Move profiles to a group | group_id + user_ids[] required |
get-profile-cookies <id> | Read cookies for one profile | One profile per request |
get-profile-ua <id> | Get UA for up to 10 profiles | Shorthand: numeric → profile_no[], non-numeric → profile_id[] |
new-fingerprint <id> | Regenerate fingerprint for up to 10 profiles | Same shorthand rules as get-profile-ua |
delete-cache-v2 | Clear local cache by type | profile_id[] + type[] (local_storage|indexeddb|extension_cache|cookie|history|image_file). Ensure no browser is open for the profile. |
share-profile | Share to another AdsPower account | profile_id[] + receiver (email or phone). share_type (1 email default, 2 phone), content[] (name|proxy|remark|tabs). Max 200. |
get-browser-active <id> | Active status for one profile | profile_id OR profile_no |
get-cloud-active | Cloud-side active status, up to 100 | user_ids comma-separated string |
3.3 Group Management
| Command | Required | Optional |
|---|---|---|
create-group | group_name | remark |
update-group | group_id + group_name | remark (null to clear) |
get-group-list | — | group_name, page_size, page |
3.4 Tag Management
| Command | Required | Optional |
|---|---|---|
get-tag-list | — | ids, limit, page |
create-tag | tags[].name (per item) | tags[].color — darkBlue|blue|purple|red|yellow|orange|green|lightGreen |
update-tag | tags[].id (per item) | tags[].name, tags[].color |
delete-tag | ids[] (max 100) | — |
3.5 Proxy Management
| Command | Required | Notes |
|---|---|---|
create-proxy | Per-item array: type (http|https|socks5), host, port | Top-level JSON array (not object). proxy_user, proxy_password optional. |
update-proxy | proxy_id | proxy_url and other proxy fields optional |
get-proxy-list | — | limit, page, proxy_id[] |
delete-proxy | proxy_id[] (max 100) | — |
3.6 Kernel Management
| Command | Required | Notes |
|---|---|---|
get-kernel-list | — | kernel_type: Chrome|Firefox (omit for both) |
download-kernel | kernel_type + kernel_version | Poll for progress after invocation |
3.7 Patch / Application
| Command | Purpose |
|---|---|
update-patch | Update AdsPower client; version_type: stable (default) | beta |
get-application-list | List app/extension categories; category_id, page, limit |
check-status | Ping Local API health (no params) |
4. Inline Config Objects
4.1 user_proxy_config (for create/update-browser)
Defaults to {"proxy_soft":"no_proxy"} when omitted. Ignored when proxyid is also given.
| Field | Required | Values |
|---|---|---|
proxy_soft | yes | brightdata | brightauto | oxylabsauto | 922S5auto | ipfoxyauto | 922S5auth | kookauto | ssh | other | no_proxy |
proxy_type | optional | http | https | socks5 | no_proxy |
proxy_host / proxy_port | optional | e.g. 127.0.0.1 / 8080 |
proxy_user / proxy_password | optional | Auth credentials |
proxy_url | optional | Full URL, e.g. http://127.0.0.1:8080 |
global_config | optional | '0' (default) | '1' |
4.2 fingerprint_config (for create/update-browser)
All fields optional. Most relevant for the Reddit use case:
| Field | Default | Notes |
|---|---|---|
automatic_timezone | '1' (by IP) | '0' to set timezone manually, e.g. America/New_York |
language_switch | '1' (by IP) | '0' + language array e.g. ["en-US"] |
ua | — | Custom UA string; overrides random_ua |
random_ua.ua_system_version | — | OS version enum array (see ua-system-version.md) |
webrtc | disabled | forward | proxy | local — use proxy for proxy-based workflows |
canvas / webgl_image / audio | '1' (noise) | Keep noise defaults for anti-detect |
screen_resolution | none | random or "WIDTH_HEIGHT" |
browser_kernel_config | — | { "type": "chrome"|"firefox", "version": "..." } — type and version must match |
tls_switch + tls | '0' | Chrome-only; comma-separated hex codes when enabled |
Full field list in /opt/data/skills/adspower-browser/references/fingerprint-config.md.
5. Docker Usage (Headless Deployment)
The package ships a docker-compose.yml:
docker-compose -f ./docker-compose.yml up -d
docker-compose exec adspower-cli /bin/bashUse this for running the CLI inside a containerized Hermes host (the Hostinger VPS case). Inside the container, ads is available on PATH and ADS_API_KEY can be baked into the compose env. This is the cleanest way to keep the CLI isolated from the host’s Node version.
6. Skill Intent Mapping (Natural Language → CLI Command)
The skill’s tool-intent-map.md (mirrors toolIntentMetadata.ts) maps user phrases to commands. Hermes loads the skill when a phrase matches a trigger. Most relevant mappings for the Reddit workflow:
| User says (EN) | User says (ZH) | CLI command |
|---|---|---|
| ”open browser”, “launch profile”, “start environment” | 打开浏览器, 启动环境, 打开profile | open-browser |
| ”close browser”, “stop profile” | 关闭浏览器, 停止环境 | close-browser |
| ”create profile”, “new browser”, “add account” | 新建环境, 创建profile, 添加浏览器 | create-browser |
| ”edit profile”, “change settings”, “modify browser” | 修改配置, 更新profile, 改代理 | update-browser |
| ”remove profile”, “delete account” | 删除环境, 移除profile | delete-browser |
| ”list profiles”, “search browsers”, “show all profiles” | 列表, 查询环境, 搜索profile | get-browser-list |
| ”opened browsers”, “running profiles” | 已打开, 正在运行 | get-opened-browser |
| ”move to group”, “regroup profiles” | 移动分组, 换组 | move-browser |
| ”get cookies”, “export cookies” | 导出Cookie, 查看Cookie | get-profile-cookies |
| ”user agent”, “UA string” | UA, 用户代理 | get-profile-ua |
| ”close everything”, “stop all browsers” | 全部关闭, 一键关环境 | close-all-profiles |
| ”refresh fingerprint”, “regenerate fp” | 刷新指纹, 重新指纹 | new-fingerprint |
| ”clear cache”, “wipe storage” | 清缓存, 删历史 | delete-cache-v2 |
| ”share account”, “transfer profile” | 分享环境, 转让profile | share-profile |
| ”is profile running”, “active status” | 是否在线, 活跃状态 | get-browser-active |
| ”cloud status”, “remote active” | 云端状态, 远程是否打开 | get-cloud-active |
| ”new group”, “add folder for profiles” | 新建分组, 创建组 | create-group |
| ”list groups”, “search group name” | 分组列表, 查组名 | get-group-list |
| ”API health”, “connection status” | 接口通不通, 检测API | check-status |
| ”add proxy”, “new proxy row” | 添加代理, 新建代理 | create-proxy |
| ”list proxies”, “search proxy” | 代理列表, 查代理 | get-proxy-list |
| ”list tags”, “label list” | 标签列表, 查看标签 | get-tag-list |
| ”new tag”, “add label” | 新建标签, 添加标签 | create-tag |
| ”download chrome kernel” | 下载内核, 更新Chrome内核 | download-kernel |
| ”upgrade client”, “patch update” | 升级客户端, 补丁更新 | update-patch |
The intent map also lists automation-only tools (navigate, click-element, fill-input, screenshot, evaluate-script, connect-browser-with-ws, etc.) — these are NOT available via the CLI. See §7.
7. CRITICAL Limitation — CLI ≠ Browser Automation
This is the single most important boundary for the Reddit workflow.
| Capability | CLI / Skill layer | MCP / RPA layer |
|---|---|---|
| Create / update / delete profiles | ✅ | — |
| Open / close browser profiles | ✅ (launches the browser) | — |
| Manage groups, tags, proxies, kernels | ✅ | — |
| Read cookies / UA / active status | ✅ | — |
| Navigate to a URL inside the browser | ❌ | ✅ (navigate) |
| Click elements, fill inputs, select options | ❌ | ✅ (click-element, fill-input, select-option) |
| Take screenshots, read page text/HTML | ❌ | ✅ (screenshot, get-page-visible-text, get-page-html) |
| Execute JS in page context | ❌ | ✅ (evaluate-script) |
| Connect Playwright via WebSocket | ❌ | ✅ (connect-browser-with-ws) |
The CLI can launch a browser profile (open-browser) and close it, but it cannot drive the browser after launch. For Reddit upvoting, commenting, posting, scrolling, or any in-page interaction, the MCP server (Playwright-based) or RPA layer is required. The open-browser response does include a ws (WebSocket) endpoint that the MCP server uses to attach Playwright — but the CLI itself does not consume it.
Practical consequence: the CLI/skill layer is the profile management backbone for the Reddit workflow. It creates the anti-detect profiles, assigns proxies, rotates fingerprints, and launches browsers. Once a browser is open, control must be handed off to the MCP server for any in-page action.
8. How This Layer Fits the Reddit Multi-Profile Workflow
The Reddit marketing workflow (per AdsPower task t_00d0d06f) needs many isolated Reddit accounts, each with its own fingerprint and proxy. The CLI/skill layer handles the “profile farm”:
| Workflow step | CLI command(s) |
|---|---|
| 1. Create a group for Reddit accounts | create-group '{"group_name":"reddit-marketing","remark":"GrowReach Reddit personas"}' |
| 2. Create N profiles, each with unique proxy + fingerprint | create-browser '{"group_id":"<gid>","username":"reddit_acct_1","user_proxy_config":{"proxy_soft":"other","proxy_type":"http","proxy_host":"...","proxy_port":"..."},"fingerprint_config":{"webrtc":"proxy","automatic_timezone":"1","language_switch":"1"}}' — repeat per profile |
| 3. Tag profiles by persona (e.g. “saas-founder”, “developer”) | create-tag '{"tags":[{"name":"saas-founder","color":"blue"}]}' then update-browser '{"profile_id":"...","profile_tag_ids":["..."],"tags_update_type":"1"}' |
| 4. Rotate fingerprint periodically | new-fingerprint <profile_id> (batch up to 10) |
| 5. Clear cookies/session between campaigns | delete-cache-v2 '{"profile_id":["..."],"type":["cookie","history","local_storage"]}' |
| 6. Launch a profile for a session | open-browser <profile_id> → returns ws endpoint |
7. Hand off ws to MCP server for Reddit automation | (MCP layer — not this CLI) |
| 8. Close profile after session | close-browser <profile_id> |
| 9. Audit: list all Reddit profiles + active status | get-browser-list '{"group_id":"<gid>","limit":200}' + get-cloud-active '{"user_ids":"..."}' |
| 10. Share a profile to a teammate | share-profile '{"profile_id":["..."],"receiver":"teammate@example.com"}' |
Proxy-per-profile is mandatory for Reddit anti-detect. Use user_proxy_config with proxy_soft: "other" + residential proxies, or pre-create proxies via create-proxy and reference them by proxyid. Always set fingerprint_config.webrtc to "proxy" so WebRTC leaks don’t expose the real IP.
Fingerprint rotation cadence: call new-fingerprint for each profile on a schedule (e.g. weekly) to keep device identity fresh. Batch up to 10 profiles per call. Combine with delete-cache-v2 (cookies + history) on the same cadence to reset session state.
9. Reference File Index
All 14 deep-dive files live at /opt/data/skills/adspower-browser/references/:
| File | When to consult |
|---|---|
browser-profile-management.md | Any profile CRUD/operation — full parameter list |
group-management.md | Group create/update/list |
browser-tag-management.md | Tag CRUD + color enum |
proxy-management.md | Proxy CRUD + type enum |
user-proxy-config.md | Inline proxy config fields for create/update-browser |
fingerprint-config.md | Full fingerprint_config field list |
browser-kernel-config.md | Kernel type+version pairing |
browser-kernel-management.md | download-kernel / get-kernel-list |
browser-kernel-download-management.md | Kernel download progress polling |
client-patch-management.md | update-patch (stable/beta) |
application-management.md | check-status / get-application-list |
tool-intent-map.md | Natural language → command mapping (full table) |
ua-system-version.md | UA OS version enum for random_ua |
chrome-tls-cipher.md | TLS hex codes for tls field (Chrome only) |
country-code.md | Lowercase 2-letter country codes for country field |