Browser Automation with cmux

Read the CLI contract first

Check the binary that will actually run before giving an exact command:

cmux browser --help
cmux --version

There are two deliberately different command shapes:

• Create a browser surface with open, open-split, or new. These commands may be workspace-scoped and do not need a surface handle.
• Use an existing surface with every surface-bound navigation, inspection, interaction, tab, state, or diagnostic command. Pass the handle explicitly with --surface <handle> or as the first positional token.

Prefer the flag form in scripts because it makes the target unmissable:

SURFACE="surface:7" # use a ref returned by discovery; do not guess an index
cmux browser --surface "$SURFACE" get url
cmux browser --surface "$SURFACE" get-url       # accepted alias
cmux browser --surface "$SURFACE" snapshot --interactive
cmux browser --surface "$SURFACE" snapshot -i   # accepted alias
cmux browser --surface "$SURFACE" url            # accepted alias
cmux browser --surface "$SURFACE" tab list
cmux browser --surface "$SURFACE" click e1 --snapshot-after

The positional form is equivalent (cmux browser "$SURFACE" get url). url and get-url are accepted URL aliases, and the short interactive snapshot flag is accepted when a surface is already present; use get url and snapshot --interactive in new documentation so the target and operation are clear. Surface-bound operations have no unscoped form. The current CLI's explicitly global browser verbs (open, open-split, new, identify, import, profile, profiles, react-grab, reactgrab, devtools, dev-tools, focus-mode, design-mode, zoom, and history) may omit the handle and use caller/workspace routing; do not infer a target from visible focus for any other verb.

Find an existing browser surface without changing focus