Command line reference
Install cloutctl, join a computer, run the shared service and use the complete command and flag reference.
On this page
cloutctl operates the same engine as the desktop app from a terminal. It can manage a Linux server without a desktop app window, while browsers themselves can run visibly on a virtual display.
Install
Download cloutctl-0.0.52.zip from Download or portal Downloads. It contains the bundled cloutctl.js, data assets, a cloutctl shim and a systemd template. Node 24 or later is required; there is no npm installation step.
node --version
unzip cloutctl-0.0.52.zip -d /opt
ln -s /opt/cloutctl-0.0.52/cloutctl /usr/local/bin/cloutctl
cloutctl --version
cloutctl system doctorUse a writable installation directory and the privileges appropriate to your server. CLOUTCTL_NODE selects another Node executable for the shim.
Choose the store
Use --store <path> when you intend a specific store. SUNCTL_STORE is the environment equivalent. The default app-support roots are:
| OS | Default root |
|---|---|
| macOS | ~/Library/Application Support/SunProfiles |
| Windows | %APPDATA%\SunProfiles |
| Linux | $XDG_CONFIG_HOME/SunProfiles, or ~/.config/SunProfiles |
An enrolled CLI uses the synced store.sqlite3; the legacy local store is sunprofiles.sqlite3. Profiles created locally before enrolment can remain in that legacy store. About → Data directory and system doctor help verify what you are operating.
Close a desktop that holds the store before starting another writer. A running system serve owns the shared queue; lifecycle commands forward to it when the store matches. --local explicitly bypasses that service for diagnosis.
Join the account
A device join token is created under Settings → Security. Pass it through stdin:
export CLOUT_SYNC_URL=https://sync.cloutlabs.co/v1
export CLOUT_ACCOUNT_API_URL=https://app.cloutlabs.co/api
printf %s "$CLOUT_JOIN_TOKEN" | cloutctl auth join --token - --label agency-node-a
cloutctl auth status
cloutctl node statusA workspace API token is a different credential:
printf %s "$CLOUT_TOKEN" | cloutctl auth login --token - --base-url https://app.cloutlabs.co/api
cloutctl auth whoami --refresh
cloutctl node enrol --self --label agency-node-aThe token needs devices.enrol for self-enrolment. One-time-code enrolment uses node enrol --code instead. Do not put a token directly into a command argument: arguments can remain in shell history and process listings.
auth logout --yes removes the stored workspace credential and cache. Revoke it in the portal too if it should no longer authorise requests.
Prepare browsers on Linux
Use a graphical session, or an X virtual framebuffer for visible browsers:
sudo apt install xvfb
Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp &
export DISPLAY=:99
cloutctl system doctorrun launch --headless is supported, but a hidden browser has a different detection surface. Cookie robot refuses headless operation. Do not treat published concurrency examples as a capacity guarantee for your host.
Prepare engines and launch one profile
cloutctl kernel status --for-fleet
cloutctl kernel install --for-fleet
cloutctl profile list --json
cloutctl run launch --id "$PROFILE_ID"
cloutctl run watch --id "$PROFILE_ID"
cloutctl run stop --id "$PROFILE_ID"Use an ID returned by profile list. run launch returns pid, port, browser, websocket and log. The detached browser survives the launching command’s exit. Stop through Clout to collect its session.
Run the shared service
cloutctl system serve --daemon --pidfile /run/cloutctl.pidThe service runs the Local API, launch queue and sync loop. It shares global and per-proxy-host admission limits across forwarded launches. Independent one-shot invocations without the service do not share one queue.
Sync only runs inside serve. Local write verbs enqueue account changes on an enrolled box, and serve drains them. A device-token-only box needs CLOUT_ACCOUNT_API_URL for its account write path; a workspace login records its base URL. If the address is missing, writes stay queued locally and the service reports why.
SIGTERM stops new admission, drains accepted launches and exits without killing running browsers. A second signal exits immediately. --json emits a readiness line for supervision.
Use the included cloutctl.service as a template: set its user, working directory and service URLs before enabling it. A CLI installation is not a reason to give a browser computer a database connection.
Script output and refusals
Pipes get JSON on stdout; terminals get readable output. --json forces JSON, --pretty indents it and --quiet suppresses the payload. Errors and progress go to stderr. run watch emits NDJSON state changes.
| Exit | Meaning | Response |
|---|---|---|
| 0 | Completed | Continue |
| 1 | Operation failed | Investigate the reported error |
| 2 | Invalid command or flags | Fix the command |
| 3 | Refused by state | Read the refusal before retrying |
Engine errors and state refusals carry code, message and detail as JSON on stderr. Usage errors and ordinary errors can be plain text; do not require every stderr line to be JSON. Destructive verbs require --yes or --confirm <n>. The latter is the expected item count, not a generic yes. A mismatch refuses the operation.
The command reference below is transcribed from the CLI’s verb declarations. cloutctl <noun> <verb> --help gives required flags, types, defaults and examples for the installed version.
Global flags
| Flag | Type | Purpose |
|---|---|---|
--store | string | Open this store instead of the default one |
--read-only | boolean | Open the store read-only; a write verb will fail |
--json | boolean | Force JSON on stdout even on a terminal |
--pretty | boolean | Indent JSON output by 2 |
--quiet | boolean | Print no payload on stdout; the exit code is the answer |
--yes | boolean | Consent to a destructive verb without naming a count |
--confirm | number | Consent to a destructive verb by naming the number of items it will touch |
--help | boolean | Show this verb’s flags and exit |
--version | boolean | Print the version, source sha, Node and platform |
Commands and flags
Commands are grouped by noun. string and number flags take a value; boolean flags can use the --no- form. Required flags are marked required. Repeatable flags accumulate. Global flags apply to every row.
Auth
| Command | Purpose | Flags |
|---|---|---|
auth login | Store a workspace API token minted in the portal | --token (string, required); --base-url (string, default: CLOUT_ACCOUNT_API_URL) |
auth join | Join this machine to an account with a device token from Settings | --token (string, required); --label (string, default: the hostname); --server (string, default: CLOUT_SYNC_URL); --agent-dir (string, default: <app-support>/agent) |
auth status | Whether this machine is enrolled as a device, and on which account | --agent-dir (string, default: <app-support>/agent) |
auth logout | Delete the stored token and the cached caps Requires destructive-operation confirmation. | None beyond global flags |
auth whoami | What this machine believes about its account, and how old that belief is | --refresh (boolean) |
Node
| Command | Purpose | Flags |
|---|---|---|
node enrol | Join this machine to an account’s fleet with a one-time code | --code (string); --self (boolean); --label (string, default: the hostname); --server (string, default: CLOUT_SYNC_URL); --agent-dir (string, default: <app-support>/agent) |
node status | Enrolment, cursor and how much of the offline window is left | --agent-dir (string, default: <app-support>/agent) |
Profile
| Command | Purpose | Flags |
|---|---|---|
profile list | List profiles with live runtime state | --group (string); --source (string); --running (boolean); --limit (number); --no-config (boolean); --facts (boolean) |
profile get | One profile, including its runtime state (absorbs the old status) | --id (string, required); --facts (boolean) |
profile create | Create a profile: mint a fingerprint locally, or clone a record with --from | --from (string); --group-id (string); --set (string, repeatable); --tab (string, repeatable); --launch-arg (string, repeatable); --disabled-font (string, repeatable); --tls-cipher (string, repeatable); --cookie-file (string); --copy-browser-data (boolean); --name (string); --group (string); --remark (string); --ua (string); --ua-os (string); --cookie (string); --proxy-setting (string); --proxy-type (string); --proxy-host (string); --proxy-port (string); --proxy-user (string); --proxy-pass (string); --proxy-soft (string); --ip-checker (string); --webrtc (string); --timezone-mode (string); --timezone (string); --location-mode (string); --geoposition (string); --language-mode (string); --language (string); --display-language-mode (string); --display-language (string); --screen-resolution-mode (string); --screen-resolution (string); --fonts-mode (string); --webgl-mode (string); --webgl-vendor (string); --webgl-renderer (string); --webgpu-mode (string); --cpu-mode (string); --ram-mode (string); --device-name-mode (string); --device-name (string); --mac-mode (string); --mac-address (string); --do-not-track (string); --port-scan (string); --port-scan-ports (string); --hardware-accel (string); --disable-tls (string); --random-fingerprint-on-startup (string); --chrome-version (number); --cpu-cores (number); --ram-gb (number); --media-mic (number); --media-camera (number); --media-speaker (number); --noise-canvas (boolean); --noise-webgl-image (boolean); --noise-audio (boolean); --noise-media (boolean); --noise-client-rects (boolean); --noise-speech (boolean); --location-ask (boolean); --merge-cookie (boolean) |
profile update | Edit the Label and Safe-subset fields of a profile | --id (string, required); --name (string); --remark (string); --group-id (string); --config (string) |
profile duplicate | Copy a profile under a new id | --id (string, required); --name (string); --group-id (string); --copy-browser-data (boolean) |
profile delete | Remove a profile and its record Requires destructive-operation confirmation. | --id (string, required) |
profile export | Write one profile to a JSON file | --id (string, required); --output (string; required by the handler) |
profile import | Register a profile from a JSON file | --input (string, required) |
profile clear-cache | Delete cache directories from a profile Requires destructive-operation confirmation. | --id (string, required); --type (string, repeatable, default: the browser cache directories) |
profile reclaim | Report recoverable disk across the fleet; --apply to sweep it | --id (string, default: every profile in the store); --apply (boolean, default: report only); --bucket (string, repeatable); --min-bytes (number) |
profile set-cookie | Store a fresh session cookie and arm one re-materialization | --id (string, required); --cookie (string); --cookie-file (string); --reason (string) |
profile fingerprint | Mint one fingerprint from AdsPower’s cloud and print it, writing nothing | --compose (boolean); --chrome-version (number); --webgl-vendor (string); --set (string, repeatable); --tab (string, repeatable); --launch-arg (string, repeatable); --disabled-font (string, repeatable); --tls-cipher (string, repeatable); --cookie-file (string); --name (string); --group (string); --remark (string); --ua (string); --ua-os (string); --cookie (string); --proxy-setting (string); --proxy-type (string); --proxy-host (string); --proxy-port (string); --proxy-user (string); --proxy-pass (string); --proxy-soft (string); --ip-checker (string); --webrtc (string); --timezone-mode (string); --timezone (string); --location-mode (string); --geoposition (string); --language-mode (string); --language (string); --display-language-mode (string); --display-language (string); --screen-resolution-mode (string); --screen-resolution (string); --fonts-mode (string); --webgl-mode (string); --webgl-renderer (string); --webgpu-mode (string); --cpu-mode (string); --ram-mode (string); --device-name-mode (string); --device-name (string); --mac-mode (string); --mac-address (string); --do-not-track (string); --port-scan (string); --port-scan-ports (string); --hardware-accel (string); --disable-tls (string); --random-fingerprint-on-startup (string); --cpu-cores (number); --ram-gb (number); --media-mic (number); --media-camera (number); --media-speaker (number); --noise-canvas (boolean); --noise-webgl-image (boolean); --noise-audio (boolean); --noise-media (boolean); --noise-client-rects (boolean); --noise-speech (boolean); --location-ask (boolean); --merge-cookie (boolean) |
Run
| Command | Purpose | Flags |
|---|---|---|
run launch | Launch a profile through the bounded job queue | --id (string, required); --headless (boolean); --start-url (string, repeatable); --launch-arg (string, repeatable); --wait-seconds (number, default: 20); --local (boolean); --concurrency (number) |
run stop | Stop a profile, adopted browsers included | --id (string, required); --ignore-missing (boolean); --local (boolean) |
run stop-all | Stop every running profile, never throwing on one failure Requires destructive-operation confirmation. | --local (boolean) |
run watch | Poll runtime state and print each state change as NDJSON | --id (string); --interval (number, default: 2000); --ticks (number, default: never) |
run list | Show job-queue runs | --id (string); --limit (number) |
Task
| Command | Purpose | Flags |
|---|---|---|
task list | Saved tasks | None beyond global flags |
task get | One task and its steps, described | --id (string, required) |
task create | Save a task from a JSON step list | --name (string, required); --steps (string, default: stdin) |
task delete | Delete a task Requires destructive-operation confirmation. | --id (string, required) |
task run | Run a task against named profiles; there is deliberately no --all | --task (string, required); --id (string, repeatable); --headless (boolean); --concurrency (number); --keep-open (boolean); --wait-seconds (number, default: 20); --artifacts (string, default: <app-support>/task-runs) |
task runs | Task-run history, or one run with its steps | --run (string); --limit (number) |
Group
| Command | Purpose | Flags |
|---|---|---|
group list | List groups with profile counts | None beyond global flags |
group create | Create a group | --name (string, required); --remark (string) |
group update | Rename a group or change its remark | --id (string, required); --name (string); --remark (string) |
group delete | Delete a group, re-homing its profiles Requires destructive-operation confirmation. | --id (string, required); --merge-into (string) |
group move | Move profiles into a group | --id (string, repeatable); --group-id (string, required) |
Folder
| Command | Purpose | Flags |
|---|---|---|
folder list | List folders with profile counts | None beyond global flags |
folder create | Create a folder | --name (string, required); --parent (string); --color (string) |
folder update | Rename, recolour or re-parent a folder (--parent '' moves to the root) | --id (string, required); --name (string); --parent (string); --color (string) |
folder delete | Delete a folder; the profiles in it are unfiled, not deleted Requires destructive-operation confirmation. | --id (string, required) |
folder assign | File profiles into folders | --id (string, repeatable); --folder (string, repeatable); --mode (string, default: set) |
System
| Command | Purpose | Flags |
|---|---|---|
system doctor | Explain lock, store, kernel, display and disk state in English | None beyond global flags |
system settings | Read or update app settings | --config (string) |
system backup | Checkpoint the WAL and copy the store | --dir (string); --output (string) |
system serve | Run the Local API, the job queue and the sync loop | --port (number, default: 50326); --daemon (boolean); --pidfile (string); --log (string, default: <app-support>/logs/serve.log); --sync (boolean, default: on); --concurrency (number, default: 4); --agent-dir (string, default: <app-support>/agent) |
system adopt | Copy the old app’s store and profile directories into --to <userData dir> | --to (string, required); --from (string); --inspect (boolean); --force (boolean); --limit (number) |
system directory-sync | Report which profiles have a directory to ship, and the current flags | None beyond global flags |
system directory-sync-set | Flip the ship/wipe policy | --wipe-on-stop (boolean); --ship (boolean); --id (string) |
Kernel
| Command | Purpose | Flags |
|---|---|---|
kernel list | Installed browser engines, with their root and disk cost | None beyond global flags |
kernel status | Installed vs published vs what this fleet pins | --for-fleet (boolean) |
kernel install | Download and install a browser engine | --major (number); --for-fleet (boolean) |
kernel remove | Delete an installed engine Requires destructive-operation confirmation. | --major (number, required) |
Proxy
| Command | Purpose | Flags |
|---|---|---|
proxy list | The proxy book, credentials removed | None beyond global flags |
proxy get | One saved proxy, credential removed | --id (string, required) |
proxy add | Book a proxy | --host (string, required); --port (string, required); --type (string, default: http); --user (string); --password (string); --title (string, default: host:port); --country (string); --city (string); --remark (string) |
proxy update | Edit a saved proxy; an absent --password leaves it alone | --id (string, required); --host (string); --port (string); --type (string); --user (string); --password (string); --title (string); --country (string); --city (string); --remark (string) |
proxy delete | Remove a saved proxy Requires destructive-operation confirmation. | --id (string, required) |
proxy check | Resolve the egress identity of a proxy | --proxy (string); --saved (string); --id (string); --config (string) |
proxy assign | Attach a booked proxy to profiles, or detach with --proxy '' | --id (string, repeatable); --proxy (string) |
proxy rotate-session | Mint fresh sticky-session tokens for profiles | --id (string, repeatable) |
Pool
| Command | Purpose | Flags |
|---|---|---|
pool list | Proxy pools with member and profile counts | None beyond global flags |
pool create | Create a proxy pool | --name (string, required); --rotation (string, default: round_robin); --remark (string) |
pool update | Rename a pool or change its rotation | --id (string, required); --name (string); --rotation (string); --remark (string) |
pool delete | Delete a pool; the profiles that drew from it are unassigned Requires destructive-operation confirmation. | --id (string, required) |
pool add-member | Put proxies in a pool, take them out, or replace the set | --id (string, required); --proxy (string, required, repeatable); --mode (string, default: add) |
pool assign | Point profiles at a pool, or at none with --id '' | --id (string); --profile (string, required, repeatable) |
pool rotate | Hand out the next proxy and advance the cursor; --peek takes nothing | --id (string, required); --peek (boolean) |
pool health | How many members of each pool check out | --id (string) |
Import
| Command | Purpose | Flags |
|---|---|---|
import detect | Detect all five vendors | --vendor (string, repeatable); --count (boolean); --kameleo-workspace (string) |
import adspower-preview | Dry-run an AdsPower export directory | --input (string, required); --group (string); --limit (number) |
import adspower | Import an AdsPower export directory | --input (string, required); --group (string); --limit (number); --overwrite (boolean, default: on) |
import adspower-pull | Import from the signed-in AdsPower account | --api-key (string); --group (string); --limit (number); --overwrite (boolean, default: on); --require-fingerprint (boolean) |
import dolphin | Import from a Dolphin Anty account | --token (string, required); --id (string, repeatable); --limit (number); --group (string); --dry-run (boolean); --full-fetch (boolean); --overwrite (boolean, default: on) |
import gologin | Import from a GoLogin account | --token (string, required); --id (string, repeatable); --limit (number); --group (string); --orbita-version (string); --dry-run (boolean); --overwrite (boolean, default: on) |
import multilogin | Import from the Multilogin store on this machine | --home (string, default: this user's home); --id (string, repeatable); --group (string); --dry-run (boolean); --overwrite (boolean, default: on) |
import kameleo-detect | Report whether a Kameleo workspace is importable | --workspace (string) |
import kameleo-preview | Dry-run a Kameleo workspace, copying nothing | --workspace (string); --limit (number) |
import kameleo | Import Kameleo profiles, directories included | --workspace (string); --id (string, repeatable); --limit (number); --group (string); --profiles-root (string); --overwrite (boolean, default: on) |
import kameleo-verify | Check an imported Kameleo profile has everything a launch needs | --id (string, required) |
Win32
| Command | Purpose | Flags |
|---|---|---|
win32 plan | Dry-count the MacIntel -> Win32 migration | --ledger (string); --batch-size (number); --surfaces (boolean); --vendors (boolean); --probe (boolean); --list (boolean); --chrome-version (number); --webgl-vendor (string); --gpu-family (string); --no-cohort (boolean); --only (string, repeatable); --exclude (string, repeatable) |
win32 migrate | Migrate ONE batch to Win32 identities Requires destructive-operation confirmation. | --ledger (string, required); --gpu-family (string); --batch-size (number); --target-arch (string); --chrome-version (number); --webgl-vendor (string); --speech-voices (string); --only (string, repeatable); --exclude (string, repeatable); --reseed (boolean); --clear-random-ua (boolean); --no-cohort (boolean); --dry (boolean); --force (boolean); --include-drift (boolean); --limit (number) |
win32 revert | Restore migrated profiles from the ledger Requires destructive-operation confirmation. | --ledger (string, required); --batch (string); --id (string, repeatable); --dry (boolean); --force (boolean); --limit (number) |
Profile creation field mappings
profile create and profile fingerprint --compose share these field flags. Use the value choices in Creating profiles; modes are passed using their wire values rather than translated button text. --set key=value can override a launch-record field and is repeatable.
| Flag | Type | Launch-record key |
|---|---|---|
--name | string | name |
--group | string | group |
--remark | string | remark |
--ua | string | ua |
--ua-os | string | ua_os |
--cookie | string | cookie |
--proxy-setting | string | proxy_setting |
--proxy-type | string | proxy_type |
--proxy-host | string | proxy_host |
--proxy-port | string | proxy_port |
--proxy-user | string | proxy_user |
--proxy-pass | string | proxy_pass |
--proxy-soft | string | proxy_soft |
--ip-checker | string | ip_checker |
--webrtc | string | webrtc |
--timezone-mode | string | timezone_mode |
--timezone | string | timezone |
--location-mode | string | location_mode |
--geoposition | string | geoposition |
--language-mode | string | language_mode |
--language | string | language |
--display-language-mode | string | display_language_mode |
--display-language | string | display_language |
--screen-resolution-mode | string | screen_resolution_mode |
--screen-resolution | string | screen_resolution |
--fonts-mode | string | fonts_mode |
--webgl-mode | string | webgl_mode |
--webgl-vendor | string | webgl_vendor |
--webgl-renderer | string | webgl_renderer |
--webgpu-mode | string | webgpu_mode |
--cpu-mode | string | cpu_mode |
--ram-mode | string | ram_mode |
--device-name-mode | string | device_name_mode |
--device-name | string | device_name |
--mac-mode | string | mac_mode |
--mac-address | string | mac_address |
--do-not-track | string | do_not_track |
--port-scan | string | port_scan |
--port-scan-ports | string | port_scan_ports |
--hardware-accel | string | hardware_accel |
--disable-tls | string | disable_tls |
--random-fingerprint-on-startup | string | random_fingerprint_on_startup |
--chrome-version | number | chrome_version |
--cpu-cores | number | cpu_cores |
--ram-gb | number | ram_gb |
--media-mic | number | media_mic |
--media-camera | number | media_camera |
--media-speaker | number | media_speaker |
--noise-canvas | boolean | noise_canvas |
--noise-webgl-image | boolean | noise_webgl_image |
--noise-audio | boolean | noise_audio |
--noise-media | boolean | noise_media |
--noise-client-rects | boolean | noise_client_rects |
--noise-speech | boolean | noise_speech |
--location-ask | boolean | location_ask |
--merge-cookie | boolean | merge_cookie |
Upgrade and backups
Use system backup --help to choose a destination and checkpoint the store. A store backup is not a complete copy of browser directories or your account-side data.
To upgrade, stop the service, unpack the new release alongside the old one, update the shim link, check --version and system doctor, then restart the service. The data root, kernels, identity and credentials are separate from the bundle. There is no automatic cloutctl upgrade command.
For account sync and revocation, also read Computers and sync. For HTTP calls served by this process, read Local API.
Recognise state refusals
Exit 3 includes PROFILE_ALREADY_RUNNING, PROFILE_RUNNING, KERNEL_UNPUBLISHED, KERNEL_UNAVAILABLE, enrolment or revocation refusals, ENTITLEMENT_DENIED, proxy availability refusals and OFFLINE_WINDOW_ELAPSED. Fix the named state before retrying.
CONFIRMATION_REQUIRED means a destructive command needs consent. CONFIRMATION_MISMATCH means the supplied count differs from the command’s measured target count; nothing was changed. Read the count and use the command’s --help before repeating it.
profile export needs both --id and --output even though the current help table does not mark the output flag required. profile fingerprint calls AdsPower’s cloud generator; profile create uses the local corpus. The fingerprint diagnostic therefore needs its vendor session and network access.
CLI profile import writes the supplied row and, when present, its adspower_record directly. An existing ID is upserted without the desktop’s separate replacement acknowledgement; verify the target store and ID first.
profile export omits the launch record. For a profile whose launch depends on that record, the exported row alone is insufficient to move its browser identity to another store. Use the desktop’s JSON or ZIP export for that transfer. CLI import accepts that credential-free embedded record; it does not add a missing one.