feat!: simplify the cli for 0.5

README.md

@@ -106,26 +106,20 @@ See the [Steel browser reference](docs/references/steel-browser.md) and the [com
 
 ## Endpoint Resolution
 
-For browser sessions, browser actions, and top-level API tools (`scrape`, `screenshot`, `pdf`), endpoint selection is deterministic.
-
-Self-hosted precedence (highest to lowest):
+Every command that calls the Steel API uses one URL, chosen in this order:
 
 1. `--api-url <url>`
-2. `STEEL_BROWSER_API_URL`
-3. `STEEL_LOCAL_API_URL`
-4. `browser.apiUrl` in `~/.config/steel/config.json`
-5. `http://localhost:3000/v1`
-
-Cloud precedence:
+2. `--local`: `browser.apiUrl` in `~/.config/steel/config.json`, or `http://localhost:3000/v1`
+3. `STEEL_API_URL`
+4. `https://api.steel.dev/v1`
 
-1. `STEEL_API_URL`
-2. `https://api.steel.dev/v1`
+URLs on `steel.dev` are Steel Cloud and need an API key. Any other URL is treated as self-hosted.
 
 ## Output and Runtime Notes
 
-- `steel scrape` defaults to markdown-first output for token efficiency; use `--raw` for the full JSON payload.
+- `steel scrape` prints markdown by default for token efficiency; use `--json` for the full API response.
 - `steel browser start` prints a display-safe connect URL with sensitive query values redacted.
-- Piped output auto-switches to JSON for machine-readable workflows. Use `--json` to force it, or `STEEL_FORCE_TTY=1` to disable.
+- Output is text by default, including when piped. Pass `--json` for machine-readable output.
 
 ## Documentation Map
 

docs/cli-reference.md

@@ -67,7 +67,6 @@ Steel CLI - browser automation for AI agents. This file is generated from `steel
 - [steel browser dialog](#steel-browser-dialog)
 - [steel browser status](#steel-browser-status)
 - [steel browser cancel](#steel-browser-cancel)
-- [steel browser close](#steel-browser-close)
 - [steel sessions](#steel-sessions)
 - [steel sessions list](#steel-sessions-list)
 - [steel sessions get](#steel-sessions-get)
@@ -113,7 +112,7 @@ These options are accepted by every command.
 
 - `--json` (boolean, optional): Output all results as JSON (structured output for automation)
 - `--local` (boolean, optional): Use local Steel runtime instead of cloud
-- `--api-url` (string, optional): Explicit self-hosted API endpoint URL
+- `--api-url` (string, optional): Steel API endpoint URL (overrides --local and STEEL_API_URL)
 - `-h, --help`: Print help for a command
 - `-V, --version`: Print the Steel CLI version
 
@@ -225,7 +224,6 @@ steel browser
 - `dialog`: Accept or dismiss an open dialog
 - `status`: Wait for a command that is still running
 - `cancel`: Stop a command that is still running
-- `close`: Close the browser session
 
 ## steel browser start
 
@@ -241,9 +239,9 @@ steel browser start
 
 - `--stealth` (boolean, optional): Enable stealth mode (humanize interactions + auto CAPTCHA)
 - `-p, --proxy` (string, optional): Use a residential proxy
-- `--session-timeout` (string, optional): Session timeout in milliseconds (create-time only)
+- `--timeout` (string, optional): Session timeout in milliseconds (create-time only)
 - `--inactivity-timeout` (string, optional): Inactivity timeout in milliseconds: release the session when no command, CDP message, or remote input arrives for this long. Defaults to 600000 (10 minutes); pass 0 to disable (create-time only)
-- `--session-solve-captcha` (boolean, optional): Enable manual CAPTCHA solving on new sessions (create-time only)
+- `--solve-captcha` (boolean, optional): Enable manual CAPTCHA solving on new sessions (create-time only)
 - `--profile` (string, optional): Named profile to persist browser state across sessions
 - `--update-profile` (boolean, optional): Save session state back to the profile when the session ends
 - `--namespace` (string, optional): Credential namespace
@@ -259,6 +257,8 @@ Stop a browser session
 steel browser stop
 ```
 
+Aliases: `close`, `quit`, `exit`
+
 ### Parameters
 
 - `-a, --all` (boolean, optional): Stop all sessions
@@ -310,7 +310,6 @@ steel browser captcha solve
 
 ### Parameters
 
-- `--session-id` (string, optional): Explicit session ID (overrides --session name lookup)
 - `--page-id` (string, optional): Page ID
 - `--url` (string, optional): Page URL for targeted CAPTCHA solving
 - `--task-id` (string, optional): CAPTCHA task ID for targeted solving
@@ -327,7 +326,6 @@ steel browser captcha status
 
 ### Parameters
 
-- `--session-id` (string, optional): Explicit session ID (overrides --session name lookup)
 - `--page-id` (string, optional): Page ID
 - `-w, --wait` (boolean, optional): Wait for terminal status
 - `--timeout` (string, optional): Timeout in milliseconds for --wait mode
@@ -1089,18 +1087,6 @@ steel browser cancel
 
 - `execution` (string, required): Execution id such as x-7
 
-## steel browser close
-
-Close the browser session
-
-### Usage
-
-```bash
-steel browser close
-```
-
-Aliases: `quit`, `exit`
-
 ## steel sessions
 
 Cloud session management and debugging

docs/references/agent-troubleshooting.md

@@ -32,7 +32,7 @@ From `steel browser start` output:
 
 Do not assume `connect_url` contains usable raw credentials.
 
-From action output (`--json`, or any piped output):
+From action output with `--json`:
 
 - `success`: whether the command did what it was asked.
 - `error_code`: the engine error code on failure, such as `stale_ref`.

docs/references/steel-browser-commands.md

@@ -8,8 +8,7 @@ Every `steel browser` action sends one request to the session's commands API (`P
 steel browser start [--session <name>]   # create a session (default name: default)
 steel browser sessions                   # list local sessions that are still live
 steel browser live                       # print the live viewer URL
-steel browser stop [--session <name>]    # release the session (-a for all)
-steel browser close                      # same as stop (aliases: quit, exit)
+steel browser stop [--session <name>]    # release the session (-a for all; aliases: close, quit, exit)
 ```
 
 - Actions without `--session` use the `default` session. It starts on first use.
@@ -128,14 +127,14 @@ Dialogs stay open until you answer them. A command that opens one prints the dia
 steel browser batch "fill e3 Seoul" "fill e4 Tokyo" "click e5" "snapshot -i"
 ```
 
-Batch sends all commands in one request (at most 50). They run in order and stop at the first failure. `tab new`, `tab switch`, `tab close`, `dialog`, `status`, `cancel`, and `close` must run on their own.
+Batch sends all commands in one request (at most 50). They run in order and stop at the first failure. `tab new`, `tab switch`, `tab close`, `dialog`, `status`, and `cancel` must run on their own. `stop` is not a batch command.
 
 ## Retries and output
 
 - The CLI sends a random `Idempotency-Key` and the last operation id. If the API cannot reach the browser, it retries with the same key, so the command never runs twice.
 - When a command's response is lost, run the same command again. You get the stored result instead of a second run, with the note `This is the stored result of an earlier run`.
 - Text output prints the result. Notes about dialogs, new tabs, downloads, and replays go to stderr.
-- `--json` (or piped output) prints the engine response under `data`, with any `notices`.
+- `--json` prints the engine response under `data`, with any `notices`.
 - A failed command exits with code 1 and prints the engine error code, such as `stale_ref`, `not_actionable`, or `tab_required`.
 
 ## Removed in 0.5

docs/references/steel-browser.md

@@ -12,27 +12,16 @@ Each `steel browser` action is one HTTP request to the session's commands API:
 
 The full command list is in [./steel-browser-commands.md](./steel-browser-commands.md).
 
-## Modes
-
-- Cloud mode (default): no mode flag required.
-- Self-hosted mode: use `--local` or `--api-url <url>`.
-
-`--api-url` implies self-hosted mode.
-
 ## Endpoint Resolution
 
-Self-hosted endpoint precedence:
+The API URL is chosen in this order:
 
 1. `--api-url <url>`
-2. `STEEL_BROWSER_API_URL`
-3. `STEEL_LOCAL_API_URL`
-4. `browser.apiUrl` in `~/.config/steel/config.json`
-5. `http://localhost:3000/v1`
+2. `--local`: `browser.apiUrl` in `~/.config/steel/config.json`, or `http://localhost:3000/v1`
+3. `STEEL_API_URL`
+4. `https://api.steel.dev/v1`
 
-Cloud endpoint precedence:
-
-1. `STEEL_API_URL`
-2. `https://api.steel.dev/v1`
+URLs on `steel.dev` are Steel Cloud and need an API key. Any other URL is treated as self-hosted.
 
 ## Steel-Owned Command Contracts
 
@@ -47,9 +36,9 @@ Main flags:
 - `--session <name>`
 - `--stealth`
 - `--proxy <url>`
-- `--session-timeout <ms>`
+- `--timeout <ms>`
 - `--inactivity-timeout <ms>` (default 600000; `0` turns it off)
-- `--session-solve-captcha`
+- `--solve-captcha`
 - `--namespace <name>`
 - `--credentials`
 - `--profile <name>`
@@ -61,7 +50,7 @@ Flag semantics:
   - `stealthConfig.humanizeInteractions = true`
   - `stealthConfig.autoCaptchaSolving = true`
   - `solveCaptcha = true`
-- `--session-solve-captcha` enables manual CAPTCHA solving for new sessions:
+- `--solve-captcha` enables manual CAPTCHA solving for new sessions:
   - `solveCaptcha = true`
   - `stealthConfig.autoCaptchaSolving` is not forced on
 - `--proxy <url>` sets `proxyUrl` on session creation. The Sessions API may return
@@ -135,14 +124,12 @@ Purpose: manually trigger CAPTCHA solving for a target session.
 
 Main flags:
 
-- `--session-id <id>`
-- `--session <name>`
+- `--session <name|id>`
 - `--page-id <id>`
 - `--url <url>`
 - `--task-id <id>`
 - `--local`
 - `--api-url <url>`
-- `--raw`
 
 API mapping:
 
@@ -199,7 +186,7 @@ Self-hosted steel-browser serves the commands API only when it runs with
 - CAPTCHA solving notes:
   - CAPTCHA solving requires a paid Steel plan.
   - `--stealth` enables auto solving; wait and monitor with screenshots.
-  - `--session-solve-captcha` enables manual solving; use `steel browser captcha solve`.
+  - `--solve-captcha` enables manual solving; use `steel browser captcha solve`.
   - Default sessions do not solve captchas; restart with CAPTCHA solving enabled and navigate back.
   - Proxy + CAPTCHA solving together is a strong anti-bot evasion combination.
 - Need hard reset of stale session mapping:

docs/references/steel-cli.md

@@ -64,8 +64,8 @@ For generated flags and argument schemas, use [../cli-reference.md](../cli-refer
   keys redacted.
 - `steel scrape`, `steel screenshot`, and `steel pdf` share local/cloud endpoint
   resolution conventions with browser lifecycle commands.
-- `steel scrape` defaults to markdown-first output for token efficiency; use
-  `--raw` to print the full API JSON payload.
+- `steel scrape` prints markdown by default for token efficiency; use `--json`
+  to print the full API response.
 
 ## Core Config Paths
 
@@ -75,7 +75,7 @@ For generated flags and argument schemas, use [../cli-reference.md](../cli-refer
 - Browser session state: `~/.config/steel/browser-sessions/<name>.json`
 - Profile metadata: `~/.config/steel/profiles/<name>.json`
 
-On the first run where telemetry is enabled, the CLI prints a one-time notice to stderr describing what is collected and how to opt out. The notice is suppressed in JSON/non-TTY output.
+On the first run where telemetry is enabled, the CLI prints a one-time notice to stderr describing what is collected and how to opt out. The notice is suppressed with `--json`.
 
 Telemetry can be disabled persistently in `config.json` with:
 
@@ -90,13 +90,11 @@ Telemetry can be disabled persistently in `config.json` with:
 ## Environment Variables (Common)
 
 - `STEEL_API_KEY`: cloud auth for the session and commands APIs.
-- `STEEL_API_URL`: cloud API endpoint override.
-- `STEEL_BROWSER_API_URL`: canonical self-hosted local endpoint override.
-- `STEEL_LOCAL_API_URL`: backward-compatible self-hosted alias.
+- `STEEL_API_URL`: API endpoint override, cloud or self-hosted.
+- `STEEL_WS_URL`: WebSocket endpoint for `steel sessions logs --follow` and `traces --follow`.
 - `STEEL_CONFIG_DIR`: override config directory root.
 - `STEEL_TELEMETRY_HOST`: override the PostHog ingest host.
 - `STEEL_TELEMETRY_DISABLED`: force telemetry off.
-- `STEEL_PROFILE`: default profile name for browser sessions.
 
 ## Key References
 

scripts/generate-api.mjs

@@ -218,12 +218,7 @@ ${queryPushes}
 }
 
 function methodArgs(operation) {
-  const args = [
-    "&self",
-    "base_url: &str",
-    "mode: ApiMode",
-    "auth: &Auth",
-  ];
+  const args = ["&self"];
   if (operation.pathParams.some((parameter) => parameter.name === "id")) {
     args.push("session_id: &str");
   }
@@ -248,15 +243,8 @@ function renderClientMethod(operation) {
   return `    pub async fn cli_${snakeCase(operation.id)}(
         ${methodArgs(operation)},
     ) -> Result<Value, ApiError> {
-        self.request(
-            base_url,
-            mode,
-            reqwest::Method::${operation.method},
-            ${requestPath},
-            None,
-            auth,
-        )
-        .await
+        self.request(reqwest::Method::${operation.method}, ${requestPath}, None)
+            .await
     }`;
 }
 
@@ -317,8 +305,6 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 
 use crate::api::client::{ApiError, SteelClient};
-use crate::config::auth::Auth;
-use crate::config::settings::ApiMode;
 
 #[derive(Debug, Clone, Copy, Serialize, Deserialize)]
 pub struct OperationMetadata {