{"_id":"@aluvia/cli","_rev":"8-2b309911b90b4295375e1edc62f39c58","name":"@aluvia/cli","dist-tags":{"latest":"1.1.1"},"versions":{"1.0.0":{"name":"@aluvia/cli","version":"1.0.0","keywords":["cli","browser-automation","playwright","aluvia"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/cli@1.0.0","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://aluvia.io","bugs":{"url":"https://github.com/aluvia-connect/sdk-node/issues"},"bin":{"aluvia":"dist/esm/cli.js"},"dist":{"shasum":"5075288ad48becb6f6ad29ad5c0caa8416c457e7","tarball":"https://registry.npmjs.org/@aluvia/cli/-/cli-1.0.0.tgz","fileCount":31,"integrity":"sha512-wBPz1LO1nrl7b/YzwNp+oOZot33qw3IM2drWM0eNgMnDb8uJbQIV/KlDbHXp6Hd9trsepi3un77sJC5oFZiwPQ==","signatures":[{"sig":"MEUCIQDXUmlme+xWjAvg/pn543Lpr932rwDKeakKTloJpgRX1AIgMyjYGV6R0R7cv+8URZBsy3BxcRDRX1KnaReNkqz7Shg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":96716},"main":"./dist/esm/cli.js","type":"module","types":"./dist/types/cli.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/cli-adapter.d.ts","import":"./dist/esm/cli-adapter.js","require":"./dist/cjs/cli-adapter.js"},"./package.json":"./package.json"},"gitHead":"762ca4dc9cb23a46fb29ee475af873dd93cb7552","scripts":{"lint":"prettier --check src","build":"tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true});require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}')\"","lint:fix":"prettier --write src"},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","repository":{"url":"git+https://github.com/aluvia-connect/sdk-node.git","type":"git"},"_npmVersion":"11.8.0","description":"Aluvia CLI - command line tools for browser automation and session management","directories":{},"_nodeVersion":"22.21.0","dependencies":{"@aluvia/sdk":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.4.2","typescript":"^5.9.3","@types/node":"^24.10.2"},"_npmOperationalInternal":{"tmp":"tmp/cli_1.0.0_1771812726244_0.644277036305287","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aluvia/cli","version":"1.0.1","keywords":["cli","browser-automation","playwright","aluvia"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/cli@1.0.1","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://aluvia.io","bugs":{"url":"https://github.com/aluvia-connect/sdk-node/issues"},"bin":{"aluvia":"dist/esm/cli.js"},"dist":{"shasum":"168574b0c003dde2fd6124599d1b28b8af5a543d","tarball":"https://registry.npmjs.org/@aluvia/cli/-/cli-1.0.1.tgz","fileCount":31,"integrity":"sha512-IQ7OwU5lWNJH5QitRG0rODTcWcXFR357GjRVU6OmmHzYOuL41hLROruQT9lxHw/C+z291GG4EOyNVedLpE9cqg==","signatures":[{"sig":"MEQCICtcClsmAfTW17Tg5gS0SEN9UnyLcO16yokpgBtVJo1KAiB7v/4TTdk68GhmlvDQ38G2ImM2KU3S+NVvkgaVAUUcNA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":96710},"main":"./dist/esm/cli.js","type":"module","types":"./dist/types/cli.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/cli-adapter.d.ts","import":"./dist/esm/cli-adapter.js","require":"./dist/cjs/cli-adapter.js"},"./package.json":"./package.json"},"gitHead":"745cc8cb3050c77c21452b02aed096232c7ac3af","scripts":{"lint":"prettier --check src","build":"tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true});require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}')\"","lint:fix":"prettier --write src"},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","repository":{"url":"git+https://github.com/aluvia-connect/sdk-node.git","type":"git"},"_npmVersion":"11.8.0","description":"Aluvia CLI - command line tools for browser automation and session management","directories":{},"_nodeVersion":"22.21.0","dependencies":{"@aluvia/sdk":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.4.2","typescript":"^5.9.3","@types/node":"^24.10.2"},"_npmOperationalInternal":{"tmp":"tmp/cli_1.0.1_1773629407401_0.18218952016531986","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aluvia/cli","version":"1.1.0","keywords":["cli","browser-automation","playwright","aluvia"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/cli@1.1.0","maintainers":[{"name":"herbertxtrella","email":"herbert@xtrella.com"},{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://aluvia.io","bugs":{"url":"https://github.com/aluvia-connect/sdk-node/issues"},"bin":{"aluvia":"dist/esm/cli.js"},"dist":{"shasum":"27295861d714d25adea96881efc1512aaf063377","tarball":"https://registry.npmjs.org/@aluvia/cli/-/cli-1.1.0.tgz","fileCount":37,"integrity":"sha512-fWmbvzze5sOiuztVGR/AB4Dz0RR+6Rt9FUHIlgwhD9yfvd7y9qKMn9CTgJM8pckNNyFhjC786iEeKSuXHsPvmw==","signatures":[{"sig":"MEQCIC1dc9P50vakr8Oa34bwpTtzNAvD4UwU74ep6fk8OEiWAiAtAwyRetMpt749jLg6PTOp3B0gYP2I4QqwEkF50+l3MA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":113845},"main":"./dist/esm/cli.js","type":"module","types":"./dist/types/cli.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/cli-adapter.d.ts","import":"./dist/esm/cli-adapter.js","require":"./dist/cjs/cli-adapter.js"},"./package.json":"./package.json"},"gitHead":"75d1ffce43b928cd6955491210b4c688ccfa5f9d","scripts":{"lint":"prettier --check src","build":"tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true});require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}')\"","lint:fix":"prettier --write src"},"_npmUser":{"name":"herbertxtrella","email":"herbert@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","repository":{"url":"git+https://github.com/aluvia-connect/sdk-node.git","type":"git"},"_npmVersion":"11.13.0","description":"Aluvia CLI - command line tools for browser automation and session management","directories":{},"_nodeVersion":"24.16.0","dependencies":{"@aluvia/sdk":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.4.2","typescript":"^5.9.3","@types/node":"^24.10.2"},"_npmOperationalInternal":{"tmp":"tmp/cli_1.1.0_1780541527565_0.19209196260611838","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@aluvia/cli","version":"1.1.1","keywords":["cli","browser-automation","playwright","aluvia"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/cli@1.1.1","maintainers":[{"name":"herbertxtrella","email":"herbert@xtrella.com"},{"name":"denniskrol","email":"dennis@xtrella.com"}],"homepage":"https://aluvia.io","bugs":{"url":"https://github.com/aluvia-connect/sdk-node/issues"},"bin":{"aluvia":"dist/esm/cli.js"},"dist":{"shasum":"a21b7c3d0afe3bb24522317b3608697b1615abd0","tarball":"https://registry.npmjs.org/@aluvia/cli/-/cli-1.1.1.tgz","fileCount":37,"integrity":"sha512-lVrgcOLZD0qrcjo4H7cPqZmL0YXHJV4anXUEy/ng1QDoRZzgCdllekOGyXsO9c+S3J0iegdRCKFwyYBNuVdUDw==","signatures":[{"sig":"MEYCIQDx5S3sNCTsl/U9rv62NRVsemXwPDgjSznKTSt35ns1OwIhALLyK3L+c8aCqLEgmWqLH3EoZag4lxVD7l6vCfIaiYx5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114686},"main":"./dist/esm/cli.js","type":"module","types":"./dist/types/cli.d.ts","engines":{"node":">=18"},"exports":{".":{"types":"./dist/types/cli-adapter.d.ts","import":"./dist/esm/cli-adapter.js","require":"./dist/cjs/cli-adapter.js"},"./package.json":"./package.json"},"gitHead":"2c4a4c7f9f22d0f8595ff3e00d7a52a81eb040cb","scripts":{"lint":"prettier --check src","build":"tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true});require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}')\"","lint:fix":"prettier --write src"},"_npmUser":{"name":"herbertxtrella","email":"herbert@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","repository":{"url":"git+https://github.com/aluvia-connect/sdk-node.git","type":"git"},"_npmVersion":"11.13.0","description":"Aluvia CLI - command line tools for browser automation and session management","directories":{},"_nodeVersion":"24.16.0","dependencies":{"@aluvia/sdk":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"prettier":"^3.4.2","typescript":"^5.9.3","@types/node":"^24.10.2"},"_npmOperationalInternal":{"tmp":"tmp/cli_1.1.1_1780637881688_0.7218156795621222","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-02-23T02:12:06.134Z","modified":"2026-08-31T13:00:35.954Z","1.0.0":"2026-02-23T02:12:06.392Z","1.0.1":"2026-03-16T02:50:07.552Z","1.1.0":"2026-06-04T02:52:07.720Z","1.1.1":"2026-06-05T05:38:01.831Z"},"bugs":{"url":"https://github.com/aluvia-connect/sdk-node/issues"},"author":{"name":"Aluvia"},"license":"MIT","homepage":"https://aluvia.io","keywords":["cli","browser-automation","playwright","aluvia"],"repository":{"url":"git+https://github.com/aluvia-connect/sdk-node.git","type":"git"},"description":"Aluvia CLI - command line tools for browser automation and session management","maintainers":[{"name":"biggyc","email":"chris@xtrella.com"},{"name":"denniskrol","email":"dennis@xtrella.com"},{"name":"herbertxtrella","email":"herbert@xtrella.com"}],"readme":"# @aluvia/cli\r\n\r\nThe official command-line interface for [Aluvia](https://aluvia.io) — launch and manage browser sessions with automatic unblocking, smart routing, and resident proxy daemons.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install -g @aluvia/cli\r\n```\r\n\r\n## Authentication\r\n\r\n```bash\r\naluvia auth\r\n```\r\n\r\nOpen the link it prints, confirm the code, and you're done. Your API key is saved to `~/.aluvia/config.json`.\r\n\r\n```bash\r\naluvia auth status   # check whether you're authenticated\r\naluvia auth logout   # remove the stored API key\r\n```\r\n\r\n### Using an environment variable instead\r\n\r\nFor CI or scripted environments you can skip `aluvia auth` and set the key directly. The environment variable always takes precedence over a key stored by `aluvia auth`.\r\n\r\n```bash\r\nexport ALUVIA_API_KEY=\"aluvia_...\"\r\n```\r\n\r\nYou can find your API key in the dashboard's **API & SDKs** section. Add it to a `.env` file if you prefer (never commit it).\r\n\r\n## Features\r\n\r\n- **Resident Browser Sessions**: Launches a headless Chromium instance managed by a background daemon.\r\n- **Auto-Unblocking**: Automatically detects blocks (403s, CAPTCHAs) and rotates IPs/headers to bypass them.\r\n- **Script Injection**: Run ephemeral scripts against the browser session with zero boilerplate.\r\n- **Live Control**: Rotate IPs, change geo-targeting, and update routing rules on running sessions.\r\n- **JSON Output**: All commands output structured JSON, making this CLI ideal for building agents and tools.\r\n\r\n## Command Reference\r\n\r\nRun `aluvia help` for a quick list of commands, or `aluvia help --json` for machine-readable output.\r\n\r\n### `session start`\r\n\r\nStarts a new browser session. This spawns a background daemon that manages the browser and proxy.\r\n\r\n```bash\r\naluvia session start <url> [options]\r\n```\r\n\r\n**Options:**\r\n\r\n- `--auto-unblock`: **(Recommended)** Enable automatic block detection and unblocking.\r\n- `--headful`: Show the browser window (useful for debugging).\r\n- `--run <script>`: Run a JavaScript/TypeScript module immediately after the session starts.\r\n- `--browser-session <name>`: Assign a custom name to the session (default: auto-generated like `swift-falcon`).\r\n- `--connection-id <id>`: Reuse an existing Aluvia connection ID (persists rules/history).\r\n- `--disable-block-detection`: Turn off all block detection features.\r\n\r\n**Examples:**\r\n\r\n```bash\r\n# Start a session with auto-unblocking\r\naluvia session start https://example.com --auto-unblock\r\n\r\n# Start a visible browser (headful)\r\naluvia session start https://google.com --headful\r\n\r\n# Run a script and exit\r\naluvia session start https://example.com --auto-unblock --run ./scrape.mjs\r\n```\r\n\r\n### `session list`\r\n\r\nLists all active browser sessions managed by the CLI.\r\n\r\n```bash\r\naluvia session list\r\n```\r\n\r\n**Output:**\r\n\r\n```json\r\n{\r\n  \"sessions\": [\r\n    {\r\n      \"browserSession\": \"swift-falcon\",\r\n      \"pid\": 12345,\r\n      \"startUrl\": \"https://example.com\",\r\n      \"cdpUrl\": \"http://127.0.0.1:39201\",\r\n      \"connectionId\": 5592,\r\n      \"autoUnblock\": true\r\n    }\r\n  ],\r\n  \"count\": 1\r\n}\r\n```\r\n\r\n### `session get`\r\n\r\nRetrieves detailed information about a specific session, including its CDP endpoint and Proxy URL.\r\n\r\n```bash\r\naluvia session get [--browser-session <name>]\r\n```\r\n\r\nIf only one session is running, it is selected automatically.\r\n\r\n### `session close`\r\n\r\nStops a browser session and kills the background daemon.\r\n\r\n```bash\r\naluvia session close [--browser-session <name>] [--all]\r\n```\r\n\r\n- `--all`: Close all running sessions.\r\n\r\n### `session rotate-ip`\r\n\r\nForces an IP rotation for the current session. The connection ID remains the same, but the exit node changes.\r\n\r\n```bash\r\naluvia session rotate-ip [--browser-session <name>]\r\n```\r\n\r\n### `session set-geo`\r\n\r\nUpdates the target geography for the session's exit node.\r\n\r\n```bash\r\naluvia session set-geo <geo_code> [--browser-session <name>]\r\naluvia session set-geo --clear\r\n```\r\n\r\n- `<geo_code>`: A geo code (e.g., `us`, `gb`, `de`). See `aluvia geos` for a full list.\r\n- `--clear`: Remove geo targeting (use any available IP).\r\n\r\n### `session set-rules`\r\n\r\nUpdates the routing rules for the session. These rules determine which domains are routed through Aluvia's proxy network versus direct connections.\r\n\r\n```bash\r\n# Append rules\r\naluvia session set-rules \"example.com,api.example.com\"\r\n\r\n# Remove rules\r\naluvia session set-rules --remove \"example.com\"\r\n```\r\n\r\n### `account` & `geos`\r\n\r\n- `aluvia account`: View your current balance and account status.\r\n- `aluvia account usage`: View usage statistics (bandwidth, requests).\r\n  - `--start <ISO8601>` / `--end <ISO8601>`: Filter by date range.\r\n- `aluvia geos`: List all available regions for geo-targeting.\r\n\r\n## Scripting (`--run`)\r\n\r\nYou can pass a script to `session start` to execute automation logic immediately. The CLI injects `page`, `browser`, and `context` (Playwright objects) into the global scope.\r\n\r\n**script.mjs:**\r\n\r\n```javascript\r\n// 'page' is already navigated to the start URL\r\nconsole.log('Title:', await page.title());\r\n\r\n// You can use standard Playwright API\r\nawait page.click('button.login');\r\nconsole.log('Logged in!');\r\n\r\n// The session closes automatically when this script finishes\r\n```\r\n\r\n**Run it:**\r\n\r\n```bash\r\naluvia session start https://example.com --auto-unblock --run script.mjs\r\n```\r\n\r\n## Connecting from SDK\r\n\r\nYou can also connect to a CLI-managed session from your own Node.js code using the `@aluvia/sdk` package.\r\n\r\n```typescript\r\nimport { connect } from '@aluvia/sdk';\r\n\r\n// Connects to the active session\r\nconst { page, browser } = await connect();\r\n\r\nawait page.goto('https://another-site.com');\r\n```\r\n\r\nSee the [SDK Documentation](../sdk/README.md) for more details.\r\n\r\n## Troubleshooting\r\n\r\n- **\"No API key found\"**: Run `aluvia auth` to log in, or export `ALUVIA_API_KEY` in your shell.\r\n- **`aluvia auth` times out**: Open the printed link in a browser and confirm the code matches.\r\n- **\"Browser process exited unexpectedly\"**: The daemon failed to start. Check if Chrome/Chromium is installed or if there are port conflicts.\r\n- **\"Invalid session name\"**: Session names must contain only letters, numbers, hyphens, and underscores.\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}