CLI

The supported CLI is the rel binary bundled in /Applications/Rel.app and normally linked at ~/.local/bin/rel. It is a thin client built on the public rel-client Rust crate. Every user-facing command maps directly to an RPC v1 operation; the CLI does not implement another browser or read application data directly.

Related documents: SDK, RPC, Services, and Architecture.

Commands

rel health
rel status
rel capture URL [options]
rel page attach URL [options]
rel page action PAGE_ID --action JSON [options]
rel proxy list
rel proxy get ID
rel proxy create --upstream-host HOST --upstream-port PORT [options]
rel proxy update ID [options]
rel proxy delete ID
rel proxy rotate ID
rel session list
rel session get ID
rel session create [options]
rel session update ID [options]
rel session delete ID
rel --help | -h
rel --version

rel --agent is an internal process mode used by Rel.app. It is not part of the public CLI.

health and status inspect the currently running agent without launching the app. Every other command, including proxy and session reads, starts Rel.app in the background when its agent is unavailable. REL_AGENT_PORT overrides the default local port, 17319.

The removed bare-URL, ping, logs, and --rotate-proxy-session interfaces have no compatibility aliases. Use capture, status, the app’s Logs view, and proxy rotate, respectively.

Output and errors

Ordinary commands print the complete pretty-printed RPC v1 success envelope:

{
  "status": "ok",
  "request_id": "req_...",
  "data": {}
}

Capture prints validated NDJSON, one compact event envelope per physical line. The CLI verifies response content types and request IDs through rel-client.

An RPC failure is printed to standard error as the complete structured error envelope. Argument, transport, and protocol failures are plain text on standard error. Clients should branch on error.id, not error.message.

Exit status is:

Status	Meaning
0	Help/version or a successful RPC operation. status also requires overall_status:"ok".
1	Usage, transport, protocol, or RPC failure; unhealthy status; or the terminal exit code from an unsuccessful capture.

Health and status

rel health
rel status

health calls GET /v1/health and reports agent worker readiness. status calls GET /v1/status and reports the app, agent, Browser Proxy, and Chromium bridge checks. Neither command synthesizes a local process report when the agent is unavailable.

Capture

rel capture URL [options]

Capture loads a page in an embedded Chromium session, performs optional actions, and writes the rendered HTML to disk.

Option	RPC field	Contract
--output PATH	output	Optional output HTML path.
--timeout SECONDS	timeout	Positive finite Chromium-operation timeout; default 90.
--wait SECONDS	wait	Nonnegative finite delay after main-frame readiness; default 1.
--action JSON	actions[]	One canonical action object; repeat the option for multiple actions.
--session-id ID	session_id	Reuse an existing immutable federated session ID.
--proxy ID|UUID|NAME	proxy	Select a proxy by numeric ID, UUID, or unique name.
--retry COUNT	retry	Retry count from 0 through 100; default 1.
--retry-delay SECONDS	retry_delay	Finite delay from 0 through 86400 seconds; default 3.

Exactly one URL is required before the options. Scheme-less localhost addresses use HTTP; other scheme-less hosts use HTTPS. Only HTTP and HTTPS are accepted.

Omitting --session-id creates a persistent browser session. Its default label is Session<ID> and its immutable identifier is:

machine-<installation UUID>.Session<ID>

For a new session, omitting --proxy means direct networking. For an existing session, omission preserves its current assignment; an explicit proxy updates the assignment.

Canonical actions are:

{"action":"click","selector":"button.more"}
{"action":"wait","seconds":0.5}
{"action":"click-link","link":"https://example.com/more","match":{"type":"fuzzy-link","threshold":0.9}}

Function-style action strings and legacy action object shapes are rejected.

A normal capture emits capture.started, capture.browser_requested, capture.page_ready, capture.rendered, capture.writing, optional capture.retrying, capture.traffic, capture.completed or capture.failed, and finally capture.finished. The final event contains the CLI exit code. A target website response such as HTTP 404 or 429 is reported as target_http_status; it is not a Rel RPC error.

Example:

rel capture https://example.com \
  --output /tmp/example.html \
  --session-id machine-7b6063e7-f43b-447f-b3ea-9958c754fcec.Session12 \
  --action '{"action":"wait","seconds":0.5}'

Attached pages

Attach an ephemeral automation page:

rel page attach https://example.com \
  --session-id machine-7b6063e7-f43b-447f-b3ea-9958c754fcec.Session12 \
  --timeout 90 --wait 1

page attach accepts --session-id, --proxy, --output, --timeout, and --wait. Its result contains a process-local page.id.

Perform one canonical action on that attachment:

rel page action page_... \
  --action '{"action":"click","selector":"button.more"}' \
  --output /tmp/after-click.html

page action requires exactly one --action and also accepts --output, --timeout, and --wait. The page remains pinned to the session, URL, and proxy selected by page attach. Page IDs disappear when the agent restarts.

Proxies

Read and remove proxy resources by positive numeric ID:

rel proxy list
rel proxy get 3
rel proxy delete 3

Create a proxy:

rel proxy create \
  --name Office \
  --upstream-host proxy.example.com \
  --upstream-port 8000 \
  --username account \
  --password secret

--upstream-host and --upstream-port are required. Optional write fields are --name, --username, --password, --oxylabs-enabled true|false, --oxylabs-location-parameter cc|country|st, and --oxylabs-location-value VALUE.

Update only the named fields:

rel proxy update 3 --name Residential --upstream-port 9000
rel proxy update 3 --clear-username --clear-password
rel proxy update 3 --clear-oxylabs-location

An update requires at least one mutable option. The clear options send explicit JSON null values instead of omitting their fields.

Rotate the generated sticky session for an Oxylabs-enabled proxy:

rel proxy rotate 3

Sessions

Read and delete persistent browser sessions by positive numeric profile ID:

rel session list
rel session get 12
rel session delete 12

Create a session:

rel session create \
  --name Research \
  --proxy-id 3 \
  --adblock-enabled true \
  --image-blocking-mode over_limit \
  --image-size-limit-kb 100

Every create option is optional. Omit --proxy-id for a direct session. --image-blocking-mode is all or over_limit.

Partially update a session:

rel session update 12 --name Research-2 --adblock-enabled false
rel session update 12 --direct

--direct clears the proxy assignment by sending proxy_id:null. An update requires at least one mutable option. Session name and filtering policy are mutable; numeric ID and federated session_id are immutable.