feat: profiles

README.md

@@ -93,6 +93,7 @@ Read more:
 | Quickstart          | `forge`, `run`                                                                        |
 | Browser lifecycle   | `browser start`, `browser stop`, `browser sessions`, `browser live`                   |
 | Browser passthrough | `steel browser <inherited-command>`                                                   |
+| Browser profiles    | `profile import`, `profile sync`, `profile list`, `profile delete`                    |
 | API tools           | `scrape`, `screenshot`, `pdf`                                                         |
 | Local runtime       | `dev install`, `dev start`, `dev stop`                                                |
 | Account and utility | `login`, `logout`, `config`, `settings`, `cache`, `docs`, `support`, `star`, `update` |

docs/README.md

@@ -9,6 +9,7 @@ This folder contains both generated command docs and hand-maintained migration/r
 - `migration-agent-browser.md`: migration guide from `agent-browser` to `steel browser`.
 - `upstream-sync.md`: maintainer guide for vendored runtime updates.
 - `references/`: stable quick-reference docs and synced upstream command catalogs.
+  - Profile commands and persistence are documented in `references/steel-browser.md` and `references/steel-cli.md`.
 
 ## References Subfolder
 

docs/references/steel-browser.md

@@ -62,6 +62,8 @@ Main flags:
 - `--session-solve-captcha`
 - `--namespace <name>`
 - `--credentials`
+- `--profile <name>`
+- `--update-profile`
 
 Flag semantics:
 
@@ -78,7 +80,12 @@ Flag semantics:
   stored under this namespace will be available for injection.
 - `--credentials` enables credential injection for the session. Sends
   `credentials: {}` in the session creation payload.
-- `--stealth`, `--proxy`, `--namespace`, and `--credentials` are create-time flags.
+- `--profile <name>` loads a previously imported browser profile (cookies, local
+  storage, etc.) into the session.
+- `--update-profile` saves session state back to the profile when the session ends.
+  Requires `--profile`.
+- `--stealth`, `--proxy`, `--namespace`, `--credentials`, `--profile`, and
+  `--update-profile` are create-time flags.
   If `--session <name>` attaches to an existing live session, these values are not
   re-applied.
 
@@ -161,6 +168,28 @@ API mapping:
 - Request body: optional `pageId`, `url`, `taskId`
 - Response: `success` + optional `message`
 
+## Profile Persistence
+
+Profiles let sessions start with pre-existing browser state (cookies, local storage, IndexedDB, etc.) imported from a local Chrome installation.
+
+Setup (macOS only, run by user):
+
+```bash
+steel profile import --name myapp          # import Chrome profile to Steel
+steel profile sync --name myapp            # re-sync local changes to Steel
+steel profile list                         # list saved profiles
+steel profile delete --name myapp          # remove local metadata
+```
+
+Usage in sessions:
+
+```bash
+steel browser start --session job --profile myapp                # load profile
+steel browser start --session job --profile myapp --update-profile  # load + save back
+```
+
+Profile metadata is stored at `~/.config/steel/profiles/<name>.json`.
+
 ## Passthrough Bootstrap Rules
 
 For inherited commands, Steel bootstrap injects a resolved `--cdp` endpoint unless explicit attach flags are present.

docs/references/steel-cli.md

@@ -19,6 +19,13 @@ For generated flags and argument schemas, use [../cli-reference.md](../cli-refer
 - `steel browser live`: print the active session live-view URL.
 - `steel browser <inherited-command>`: pass through to vendored `agent-browser` runtime.
 
+### Profile Commands
+
+- `steel profile import`: import a local Chrome profile into Steel (macOS only).
+- `steel profile sync`: sync a local Chrome profile to an existing Steel profile (macOS only).
+- `steel profile list`: list all saved Steel browser profiles.
+- `steel profile delete`: delete a saved Steel profile (local metadata only).
+
 ### Credentials Commands
 
 - `steel credentials create`: store a new credential for a given origin.
@@ -67,6 +74,7 @@ For generated flags and argument schemas, use [../cli-reference.md](../cli-refer
 - Config directory: `~/.config/steel`
 - Main config: `~/.config/steel/config.json`
 - Browser session state: `~/.config/steel/browser-session-state.json`
+- Profile metadata: `~/.config/steel/profiles/<name>.json`
 
 ## Environment Variables (Common)
 
@@ -75,6 +83,7 @@ For generated flags and argument schemas, use [../cli-reference.md](../cli-refer
 - `STEEL_BROWSER_API_URL`: canonical self-hosted local endpoint override.
 - `STEEL_LOCAL_API_URL`: backward-compatible self-hosted alias.
 - `STEEL_CONFIG_DIR`: override config directory root.
+- `STEEL_PROFILE`: default profile name for browser sessions.
 
 ## Key References