obscura-cli

name

obscura-cli

description

Use this skill when a task involves installing, configuring, or using the obscura-cli client: connecting to local or remote Obscura Gateway servers, setting server URLs/API keys/default stealth, creating and closing sessions, controlling session/profile stealth, managing browser fingerprint identity fields, navigating/evaluating/dumping pages, managing profiles, importing/exporting cookies, issuing CDP grants, setting proxy/domain policies through the CLI, or giving agents command examples for browser automation workflows.

Obscura CLI

Use This Skill For

obscura-cli is the first-class command-line client for Obscura Gateway. It configures local client state and sends authenticated HTTP requests to the gateway API.

Use this skill for agent/browser workflows: sessions, profiles, cookies, stealth/fingerprint controls, CDP grants, proxy policies, domain policies, remote gateway setup, and CLI troubleshooting.

For server deployment, Docker, gateway process lifecycle, API implementation, and release packaging, use the obscura-gateway skill instead.

Fast Start

Point the CLI at a gateway:

obscura-cli config set-server-url http://127.0.0.1:18789
obscura-cli config set-api-key <gateway_api_key>
obscura-cli config set-default-stealth true

Create and use an ephemeral browser session:

obscura-cli session create
obscura-cli session navigate <session_id> https://example.com/
obscura-cli session eval <session_id> "document.title"
obscura-cli session dump <session_id> --format text
obscura-cli session close <session_id>

Override stealth per session when needed:

obscura-cli session create --no-stealth
obscura-cli session create --stealth

From source, replace obscura-cli with:

cargo run --bin obscura-cli --

Always close sessions when finished. Sessions are ephemeral and backed by live gateway-owned obscura child processes.

Core Rules

• server_url is what the CLI calls and what CDP grants use for public URLs.
• api_key must match the gateway API key.
• Session IDs refer to live gateway runtimes; after gateway restart, create a new session.
• Prefer session navigate, session eval, and session dump over raw CDP unless the tool specifically needs CDP.
• Use profiles for persistent identity/cookies; use ephemeral direct sessions for one-off browsing.
• Stealth defaults on unless overridden by gateway config, profile settings, or session flags.
• Session --stealth and --no-stealth override gateway/profile defaults for that session only.
• Profile --stealth and --no-stealth are persistent overrides; omit them to inherit the gateway default.
• Profile sessions fill missing identity fields with the built-in Chrome 145/macOS fingerprint defaults.
• Effective profile user agents are passed to obscura serve --user-agent; timezone and viewport are applied through CDP emulation.
• Do not import cookies into a profile while it has active sessions.

Reference Files

Read only the reference that matches the task:

• CLI operations: install, setup, remote config, status, quotas, common commands, and source equivalents.
• Sessions, profiles, and cookies: lifecycle rules, profile modes, stealth/fingerprint controls, identity fields, cookie formats, and persistence gotchas.
• CLI CDP, proxies, and troubleshooting: CDP grant commands, proxy policy commands, domain policy commands, and diagnostic workflow.