Command line

Local commands for agent-led recording.

The native Mac installer includes the compiled welles binary. Use it to let local agents inspect UI, drive screen recording, run AI video editor workflows, export, and create hosted shares. Agents can use the single record verb for the full demo loop, or call each planning, editing, and sharing step directly.

Browse commands API reference

Binarywelles

The CLI is the local control surface for macOS capture. Use HTTP when your agent runs remotely; use the CLI when it needs to inspect windows, click accessible controls, record the screen, or hand work to the native app.

Recommended agent path

Agent workflow

Use the record super-verb first.

welles login --all-scopes
welles sources
welles inspect --app-name Welles
welles storyboard --window Welles \
  --repo-context ./app > storyboard.json
welles record --project PROJECT_UUID \
  --plan storyboard.json

# Optional post-hoc polish
welles set-edit PROJECT_UUID --params edit.json
welles export PROJECT_UUID --preset web1080
welles share PROJECT_UUID --permission comment

For the highest-level path, let welles record handle capture, edit, export, upload, and share. Drop down to individual commands when you need finer control.

Install from the app

Download the DMG, move Welles to Applications, then open Settings → Command Line Tool and click Install CLI.

/usr/local/bin/welles → /Applications/Welles.app/Contents/Resources/welles

The PKG installer does that automatically during install.

Secure setup

Auth, one time

Connect the local CLI to a scoped Welles token and verify the Mac has the permissions it needs.

welles login

Device-flow auth. Stores scoped tokens in macOS Keychain.

welles whoami

Show the active token, project, expiry, and granted scopes.

welles revoke

Invalidate the current token and remove local access.

welles accessibility

Check or request macOS Accessibility access for real virtual clicks.

welles keychain-reset

Remove this channel's local CLI token after signing changes.

Plan before acting

Reconnaissance, read-only

Let agents discover windows, UI controls, projects, and story context before touching the recorder.

welles sources

List macOS displays, apps, and windows the agent can target.

welles inspect

Dump accessible UI controls for an app or window so the agent can plan clicks.

welles storyboard

Build a semantic JSON action plan from window, Accessibility, and repo context.

welles projects

List projects visible to this token.

welles project

Create a project shell for CLI-led recordings (sub-command: project create).

welles info

Fetch project state and edit metadata.

Capture the demo

Recording

Drive the native recorder, clean browser sessions, and multi-scene demos from a single local command surface.

welles record

The end-to-end verb: source-aware narration, native recorder control, export, upload, and share.

welles agent-browser

Launch a clean Chrome window for website demos, separate from the recorder.

welles demo

Plan and render a multi-scene narrated product video from a story prompt.

welles slides

Generate, render, and attach motion-graphics slides.

welles act

Press accessible controls locally — internal staging/dev verb for agent-driven scripts.

Polish and publish

Editing and output

Patch edits, generate narration, export finished videos, and create or update hosted share links.

welles set-edit

Patch supported edit fields, including mutes, trims, zooms, captions, and related metadata.

welles edit-schema

Print the supported set-edit fields with types, ranges, and examples.

welles script

Generate a voiceover script for a project.

welles voiceover

Synthesize ElevenLabs voiceover audio.

welles export

Queue a project export.

welles share

Create a hosted share link.

welles update-share

Replace media behind an existing hosted share link (keeps the same URL).

welles upload-share

Upload a locally rendered MP4 and create a hosted share.

welles command

Escape hatch for posting raw project commands to the backend.

Token scopes

project:read

Projects, info, and read-only planning.

project:edit

set-edit and Claude edit operations.

project:export

Exports and Claude video export operations.

project:share

Hosted shares and upload-share.

ai:included

Script and voiceover within the included quota.

ai:premium

Paid AI operations such as extra-long narration or premium voices.

billing:read

Plan checks before premium operations.

Request scopes per command with repeated --scope flags, or grab everything an agent needs with --all-scopes.

Remove or repair

Use Welles → Remove Welles CLI or Settings → Command Line Tool → Remove CLI. The app only removes /usr/local/bin/welles when it is a symlink to a bundled Welles CLI.

LLM context

Copy for LLMs

Command, install, scope, and workflow context formatted for Claude, Cursor, or another coding agent.

Welles CLI quick context for LLM agents:

Welles is a macOS screen recorder and AI video editor. The native app bundles a compiled "welles" CLI for agent-driven recording, editing, exporting, and sharing.

Authentication:
- Run "welles login --all-scopes" once for trusted local automation.
- Tokens are scoped by the backend and stored in macOS Keychain.
- Use "welles whoami" to inspect active token, project, expiry, and scopes.
- Use "welles revoke" to invalidate local access.

Core read-only planning commands:
- "welles sources" lists macOS displays, apps, and windows.
- "welles inspect" dumps accessible UI controls for an app/window.
- "welles storyboard" builds a semantic JSON action plan from window, Accessibility, and repo context.
- "welles projects" lists projects visible to the token.
- "welles info" fetches project state and edit metadata.

Recording commands:
- "welles record" is the end-to-end demo verb: source-aware narration, native recorder control, export, upload, and hosted share.
- "welles agent-browser" launches a clean Chrome window for website demos.
- "welles demo" plans and renders a multi-scene narrated product video.
- "welles slides" generates, renders, and attaches motion-graphics slides.

Editing/output commands:
- "welles set-edit" patches mutes, trims, zooms, captions, and other edit fields.
- "welles script" generates a project voiceover script.
- "welles voiceover" synthesizes ElevenLabs voiceover audio.
- "welles export" queues a project export.
- "welles share" creates a hosted share link.
- "welles upload-share" uploads a local MP4 and creates a hosted share.
- "welles command" posts raw backend project commands.

Useful scopes:
- project:read, project:edit, project:export, project:share
- ai:included, ai:premium
- billing:read

Recommended end-to-end recipe:
welles login --all-scopes
welles sources
welles inspect --app-name Welles --query "New Recording"
welles storyboard --window Welles --repo-context ./app > storyboard.json
welles record --project PROJECT_UUID --plan storyboard.json
welles share PROJECT_UUID